Присутствие¶

«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 (в этом случае дубликаты ожидаемы)