Присутність

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 (дублікати очікувані)

# Повʼязане