​

Присутствие

«Presence» в OpenClaw — это лёгкое, best‑effort представление:

• самого Gateway (шлюза), и
• клиентов, подключённых к Gateway (приложение для macOS, WebChat, CLI и т. д.).

Presence используется в первую очередь для отрисовки вкладки Instances в приложении для macOS и для быстрого обзора состояния оператором.

​

Поля presence (что отображается)

Записи presence представляют собой структурированные объекты с такими полями, как:

• 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: метка времени последнего обновления (мс с начала эпохи)

​

Производители (откуда берётся presence)

Записи presence создаются несколькими источниками и объединяются.

​

1. Собственная запись Gateway

Gateway всегда инициализирует «self»‑запись при запуске, чтобы интерфейсы показывали хост шлюза даже до подключения каких‑либо клиентов.

​

2. Подключение WebSocket

Каждый WS‑клиент начинает с запроса connect. При успешном рукопожатии Gateway выполняет upsert записи presence для этого соединения.

​

Почему разовые команды CLI не отображаются

CLI часто подключается для коротких разовых команд. Чтобы не засорять список Instances, client.mode === "cli" не преобразуется в запись presence.

​

3. Маяки system-event

Клиенты могут отправлять более насыщенные периодические маяки через метод system-event. Приложение для macOS использует это для передачи имени хоста, IP и lastInputSeconds.

​

4. Подключение узла (роль: node)

Когда узел подключается через WebSocket Gateway с role: node, Gateway выполняет upsert записи presence для этого узла (тот же процесс, что и для других WS‑клиентов).

​

Правила объединения и дедупликации (почему важен instanceId)

Записи presence хранятся в единой карте в памяти:

• Записи индексируются по ключу presence.
• Лучший ключ — это стабильный instanceId (из connect.client.instanceId), сохраняющийся между перезапусками.
• Ключи нечувствительны к регистру.

Если клиент переподключается без стабильного instanceId, он может отображаться как дублирующаяся строка.

​

TTL и ограниченный размер

Presence намеренно является эфемерным:

• 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 при рукопожатии
  • убедитесь, что периодические маяки используют тот же instanceId
  • проверьте, не отсутствует ли у записи, полученной из соединения, instanceId (в этом случае дубликаты ожидаемы)