Presencia

OpenClaw "presencia" es una vista ligera y de mejor esfuerzo de:

• el propio Gateway, y
• clientes conectados al Gateway (aplicación para Mac, WebChat, CLI, etc.)

La presencia se usa principalmente para representar la pestaña Instancias de la aplicación de macOS y para proporcionar visibilidad rápida al operador.

# Campos de presencia (lo que aparece)

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 la época)

# Productores (de dónde viene la presencia)

Las entradas de presencia son producidas por varias fuentes y se fusionan.

# 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 protocolo de enlace correcto, el Gateway inserta o actualiza una entrada de presencia para esa conexión.

# Por qué los comandos puntuales de CLI no aparecen

La CLI a menudo se conecta para comandos breves y puntuales. Para evitar llenar de ruido la lista de Instancias, client.mode === "cli" no se convierte en una entrada de presencia.

# 3) Balizas system-event

Los clientes pueden enviar balizas periódicas más completas mediante el método system-event. La aplicación para Mac usa esto para informar el nombre de host, la IP y lastInputSeconds.

# 4) Conexiones de Node (role: node)

Cuando un Node se conecta a través del WebSocket del Gateway con role: node, el Gateway inserta o actualiza una entrada de presencia para ese Node (el mismo flujo que otros clientes WS).

# Reglas de fusió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 los reinicios.
• Las claves no distinguen entre mayúsculas y minúsculas.

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

# TTL y tamaño limitado

La presencia es intencionalmente efímera:

• TTL: se eliminan las entradas con más de 5 minutos de antigüedad
• Entradas máximas: 200 (las más antiguas se descartan primero)

Esto mantiene la lista actualizada y evita el crecimiento ilimitado de la memoria.

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

Cuando un cliente se conecta mediante un túnel SSH / reenvío de puerto local, el Gateway puede ver la dirección remota como 127.0.0.1. Para evitar sobrescribir una buena IP informada por el cliente, se ignoran las direcciones remotas de loopback.

# Consumidores

# Pestaña Instancias de macOS

La aplicación de macOS representa la salida de system-presence y aplica un pequeño indicador de estado (Activo/Inactivo/Obsoleto) según la antigüedad de la última actualización.

# Consejos de depuración

• Para ver la lista sin procesar, llama a system-presence contra el Gateway.
• Si ves duplicados:
  • confirma que los clientes envíen un client.instanceId estable en el protocolo de enlace
  • confirma que las balizas periódicas usen el mismo instanceId
  • comprueba si a la entrada derivada de la conexión le falta instanceId (se esperan duplicados)

# Relacionado