---
read_when:
    - Налагодження вкладки «Екземпляри»
    - Дослідження дубльованих або застарілих рядків екземплярів
    - Зміна WS-підключення Gateway або маяків системних подій
summary: Як створюються, об’єднуються та відображаються записи присутності OpenClaw
title: Присутність
x-i18n:
    generated_at: "2026-05-06T01:36:06Z"
    model: gpt-5.5
    provider: openai
    source_hash: 6ab76e81fc1842c747b0a33da8cf9874e3537c5ab023450ee1a6a314453e7263
    source_path: concepts/presence.md
    workflow: 16
---

OpenClaw «присутність» — це легке, best-effort представлення:

- самого **Gateway**, і
- **клієнтів, підключених до Gateway** (застосунок Mac, WebChat, CLI тощо)

Присутність використовується переважно для відображення вкладки **Instances** у застосунку macOS і для
швидкої видимості для оператора.

## Поля присутності (що відображається)

Записи присутності — це структуровані обʼєкти з такими полями, як:

- `instanceId` (необовʼязкове, але настійно рекомендоване): стабільна ідентичність клієнта (зазвичай `connect.client.instanceId`)
- `host`: зручна для людини назва хоста
- `ip`: best-effort IP-адреса
- `version`: рядок версії клієнта
- `deviceFamily` / `modelIdentifier`: підказки щодо апаратного забезпечення
- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
- `lastInputSeconds`: «секунди від останнього введення користувача» (якщо відомо)
- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
- `ts`: мітка часу останнього оновлення (мс від епохи)

## Виробники (звідки надходить присутність)

Записи присутності створюються кількома джерелами та **обʼєднуються**.

### 1) Власний запис Gateway

Gateway завжди ініціалізує запис «self» під час запуску, щоб UI показували хост gateway
ще до підключення будь-яких клієнтів.

### 2) Підключення WebSocket

Кожен WS-клієнт починає із запиту `connect`. Після успішного рукостискання
Gateway вставляє або оновлює запис присутності для цього підключення.

#### Чому одноразові команди CLI не відображаються

CLI часто підключається для коротких одноразових команд. Щоб не засмічувати
список Instances, `client.mode === "cli"` **не** перетворюється на запис присутності.

### 3) Маяки `system-event`

Клієнти можуть надсилати багатші періодичні маяки через метод `system-event`. Застосунок Mac
використовує це, щоб повідомляти назву хоста, IP і `lastInputSeconds`.

### 4) Підключення Node (role: node)

Коли Node підключається через WebSocket Gateway з `role: node`, Gateway
вставляє або оновлює запис присутності для цього Node (той самий потік, що й для інших WS-клієнтів).

## Правила обʼєднання та усунення дублікатів (чому `instanceId` важливий)

Записи присутності зберігаються в одній карті в памʼяті:

- Записи індексуються за **ключем присутності**.
- Найкращий ключ — стабільний `instanceId` (із `connect.client.instanceId`), який зберігається після перезапусків.
- Ключі нечутливі до регістру.

Якщо клієнт повторно підключається без стабільного `instanceId`, він може зʼявитися як
**дубльований** рядок.

## TTL і обмежений розмір

Присутність навмисно ефемерна:

- **TTL:** записи старші за 5 хвилин видаляються
- **Максимум записів:** 200 (найстаріші видаляються першими)

Це підтримує список актуальним і запобігає необмеженому зростанню памʼяті.

## Застереження щодо віддаленого доступу/тунелю (loopback IP-адреси)

Коли клієнт підключається через SSH-тунель / локальне перенаправлення порту, Gateway може
бачити віддалену адресу як `127.0.0.1`. Щоб не перезаписати коректну IP-адресу,
повідомлену клієнтом, віддалені loopback-адреси ігноруються.

## Споживачі

### Вкладка macOS Instances

Застосунок macOS відображає результат `system-presence` і застосовує невеликий індикатор
стану (активний/бездіяльний/застарілий) на основі віку останнього оновлення.

## Поради з налагодження

- Щоб побачити необроблений список, викличте `system-presence` для Gateway.
- Якщо бачите дублікати:
  - переконайтеся, що клієнти надсилають стабільний `client.instanceId` під час рукостискання
  - переконайтеся, що періодичні маяки використовують той самий `instanceId`
  - перевірте, чи запис, отриманий із підключення, не має `instanceId` (дублікати очікувані)

## Повʼязане

<CardGroup cols={2}>
  <Card title="Індикатори введення" href="/uk/concepts/typing-indicators" icon="ellipsis">
    Коли надсилаються індикатори введення та як їх налаштовувати.
  </Card>
  <Card title="Потокове передавання та розбиття на фрагменти" href="/uk/concepts/streaming" icon="bars-staggered">
    Вихідне потокове передавання, розбиття на фрагменти та форматування для кожного каналу.
  </Card>
  <Card title="Архітектура Gateway" href="/uk/concepts/architecture" icon="diagram-project">
    Компоненти Gateway і протокол WebSocket, який керує оновленнями присутності.
  </Card>
  <Card title="Протокол Gateway" href="/uk/gateway/protocol" icon="plug">
    Дротовий протокол для `connect`, `system-event` і `system-presence`.
  </Card>
</CardGroup>