> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Присутність

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>