Присутствие

«presence» в OpenClaw — это легковесное представление по принципу best-effort о:

• самом Gateway, и
• клиентах, подключенных к Gateway (приложение для Mac, 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 всегда создает «собственную» запись при запуске, чтобы интерфейсы показывали хост Gateway еще до подключения клиентов.

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

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

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

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

3) Маяки system-event

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

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

Связанное