​

Присутність

“Присутність” 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 у записі, похідному від підключення (у такому разі дублікати очікувані)