Присутствие

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

​

Связанное