---
read_when:
    - Налагодження вкладки Instances
    - Дослідження дублікатів або застарілих рядків екземплярів
    - Зміна підключення gateway WS або beacon системних подій
summary: Як створюються, об’єднуються та відображаються записи присутності OpenClaw
title: Присутність
x-i18n:
    generated_at: "2026-04-05T18:01:37Z"
    model: gpt-5.4
    provider: openai
    source_hash: a004a1f87be08699c1b2cba97cad8678ce5e27baa425f59eaa18006fdcff26e7
    source_path: concepts/presence.md
    workflow: 15
---

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

“Присутність” OpenClaw — це легке представлення за принципом best-effort для:

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

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

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

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

- `instanceId` (необов’язкове, але наполегливо рекомендоване): стабільна ідентичність клієнта (зазвичай `connect.client.instanceId`)
- `host`: зрозуміла людині назва хоста
- `ip`: IP-адреса за принципом best-effort
- `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 connect

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

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

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

### 3) beacon `system-event`

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

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

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

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

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

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

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

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

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

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

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

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

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

## Споживачі

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

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

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

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