Мульти-агент

Presence

«Presence» в OpenClaw — это облегчённое, ориентированное на максимальную доступность представление о:

самом Gateway, и
клиентах, подключённых к Gateway (mac app, WebChat, CLI и т.д.)

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

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

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

instanceId (опционально, но настоятельно рекомендуется): стабильный идентификатор клиента (обычно connect.client.instanceId)
host: понятное человеку имя хоста
ip: определённый по возможности IP-адрес
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 добавляет или обновляет запись presence для этого соединения.

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

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

3) Сигналы system-event

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

4) Подключения узлов (role: node)

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

Маршрутизация в мульти-агентных системах Сообщения