Присутствие

"Присутствие" OpenClaw - это легковесное представление наилучшего усилия:

  • самого Gateway, и
  • клиентов, подключенных к Gateway (приложение mac, WebChat, CLI и т.д.)

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

Поля присутствия (что отображается)

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

  • 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: временная метка последнего обновления (мс с эпохи)

Производители (откуда берется присутствие)

Записи присутствия производятся несколькими источниками и объединяются.

1) Самозапись Gateway

Gateway всегда инициализирует "self" запись при запуске, чтобы UI показывали хост gateway даже до того, как любые клиенты подключатся.

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

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

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

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

3) Маяки system-event

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

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

Когда узел подключается через WebSocket Gateway с role: node, Gateway обновляет запись присутствия для этого узла (тот же поток, что и для других WS-клиентов).

Правила слияния + дедупликации (почему instanceId важен)

Записи присутствия хранятся в единой карте в памяти:

  • Записи имеют ключ по ключу присутствия.
  • Лучший ключ - это стабильный instanceId (из connect.client.instanceId), который переживает перезапуски.
  • Ключи нечувствительны к регистру.

Если клиент переподключается без стабильного instanceId, он может отображаться как дублирующаяся строка.

TTL и ограниченный размер

Присутствие намеренно эфемерно:

  • TTL: записи старше 5 минут обрезаются
  • Максимум записей: 200 (сначала удаляются самые старые)

Это сохраняет список свежим и избегает неограниченного роста памяти.

Предостережение удаленного/туннеля (IP-адреса обратной связи)

Когда клиент подключается через SSH-туннель / переадресацию локального порта, Gateway может видеть удаленный адрес как 127.0.0.1. Чтобы избежать перезаписи хорошего IP-адреса, сообщенного клиентом, удаленные адреса обратной связи игнорируются.

Потребители

Вкладка Instances macOS

Приложение macOS отображает вывод system-presence и применяет небольшой индикатор состояния (Active/Idle/Stale) на основе возраста последнего обновления.

Советы по отладке

  • Чтобы увидеть необработанный список, вызовите system-presence для Gateway.
  • Если вы видите дубликаты:
    • подтвердите, что клиенты отправляют стабильный client.instanceId в рукопожатии
    • подтвердите, что периодические маяки используют тот же instanceId
    • проверьте, отсутствует ли instanceId в записи, полученной из подключения (ожидаются дубликаты)
← Назад к документации