--- read_when: - Отладка вкладки Instances - Исследование повторяющихся или устаревших строк экземпляров - Изменение WS-подключения Gateway или маяков system-event summary: Как создаются, объединяются и отображаются записи присутствия OpenClaw title: Присутствие x-i18n: generated_at: "2026-06-28T22:52:16Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 6ab76e81fc1842c747b0a33da8cf9874e3537c5ab023450ee1a6a314453e7263 source_path: concepts/presence.md workflow: 16 --- «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` в записи, полученной из подключения (дубликаты ожидаемы) ## Связанное Когда отправляются индикаторы набора текста и как их настраивать. Исходящая потоковая передача, разбиение на фрагменты и форматирование для отдельных каналов. Компоненты Gateway и протокол WebSocket, который управляет обновлениями presence. Проводной протокол для `connect`, `system-event` и `system-presence`.