> ## 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.

# Presencia

# Presencia

La “presencia” de OpenClaw es una vista ligera y de mejor esfuerzo de:

* el **Gateway** en sí, y
* **los clientes conectados al Gateway** (app de macOS, WebChat, CLI, etc.)

La presencia se utiliza principalmente para renderizar la pestaña **Instances** de la app de macOS y para
proporcionar visibilidad rápida al operador.

## Campos de presencia (lo que se muestra)

Las entradas de presencia son objetos estructurados con campos como:

* `instanceId` (opcional pero muy recomendado): identidad estable del cliente (normalmente `connect.client.instanceId`)
* `host`: nombre de host legible para humanos
* `ip`: dirección IP de mejor esfuerzo
* `version`: cadena de versión del cliente
* `deviceFamily` / `modelIdentifier`: indicios de hardware
* `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
* `lastInputSeconds`: “segundos desde la última entrada del usuario” (si se conoce)
* `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
* `ts`: marca de tiempo de la última actualización (ms desde epoch)

## Productores (de dónde proviene la presencia)

Las entradas de presencia son producidas por múltiples fuentes y se **combinan**.

### 1. Entrada propia del Gateway

El Gateway siempre inicializa una entrada “self” al arrancar para que las IU muestren el host del gateway
incluso antes de que se conecten clientes.

### 2. Conexión WebSocket

Cada cliente WS comienza con una solicitud `connect`. Tras un handshake exitoso, el
Gateway hace un upsert de una entrada de presencia para esa conexión.

#### Por qué los comandos puntuales de la CLI no aparecen

La CLI suele conectarse para comandos cortos y puntuales. Para evitar saturar la
lista de Instances, `client.mode === "cli"` **no** se convierte en una entrada de presencia.

### 3. Beacons `system-event`

Los clientes pueden enviar beacons periódicos más completos mediante el método `system-event`. La app de macOS
usa esto para informar el nombre de host, la IP y `lastInputSeconds`.

### 4. Conexiones de nodos (rol: node)

Cuando un nodo se conecta por el WebSocket del Gateway con `role: node`, el Gateway
hace un upsert de una entrada de presencia para ese nodo (el mismo flujo que otros clientes WS).

## Reglas de combinación y deduplicación (por qué `instanceId` importa)

Las entradas de presencia se almacenan en un único mapa en memoria:

* Las entradas se indexan por una **clave de presencia**.
* La mejor clave es un `instanceId` estable (de `connect.client.instanceId`) que sobrevive a reinicios.
* Las claves no distinguen mayúsculas de minúsculas.

Si un cliente se reconecta sin un `instanceId` estable, puede aparecer como una
fila **duplicada**.

## TTL y tamaño acotado

La presencia es intencionalmente efímera:

* **TTL:** las entradas con más de 5 minutos se depuran
* **Entradas máximas:** 200 (las más antiguas se descartan primero)

Esto mantiene la lista actualizada y evita un crecimiento de memoria sin límites.

## Advertencia de remoto/túnel (IP de loopback)

Cuando un cliente se conecta a través de un túnel SSH / reenvío de puertos local, el Gateway puede
ver la dirección remota como `127.0.0.1`. Para evitar sobrescribir una IP informada por el cliente que sea válida,
se ignoran las direcciones remotas de loopback.

## Consumidores

### Pestaña Instances de macOS

La app de macOS renderiza la salida de `system-presence` y aplica un pequeño indicador de estado
(Active/Idle/Stale) según la antigüedad de la última actualización.

## Consejos de depuración

* Para ver la lista sin procesar, llame a `system-presence` contra el Gateway.
* Si ve duplicados:
  * confirme que los clientes envían un `client.instanceId` estable en el handshake
  * confirme que los beacons periódicos usan el mismo `instanceId`
  * verifique si a la entrada derivada de la conexión le falta `instanceId` (los duplicados son esperables)