Перейти к основному содержимому

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

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

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