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

«Присутність» OpenClaw — це легке, найкраще можливе подання:

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

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

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

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

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

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

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

### 3) beacons `system-event`

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

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

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

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

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

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

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

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

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

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

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

## Особливість remote/tunnel (loopback IP)

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

## Споживачі

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

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

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

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

## Пов’язане

- [Індикатори введення](/uk/concepts/typing-indicators)
- [Потокова передача й поділ на фрагменти](/uk/concepts/streaming)
