> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Присутствие

# Присутствие

«Presence» в OpenClaw — это лёгкое, best‑effort представление:

* самого **Gateway (шлюза)**, и
* **клиентов, подключённых к Gateway** (приложение для macOS, 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 всегда инициализирует «self»‑запись при запуске, чтобы интерфейсы показывали хост шлюза
даже до подключения каких‑либо клиентов.

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

Каждый WS‑клиент начинает с запроса `connect`. При успешном рукопожатии
Gateway выполняет upsert записи presence для этого соединения.

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

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

### 3. Маяки `system-event`

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

### 4. Подключение узла (роль: 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` (в этом случае дубликаты ожидаемы)