Presencia
Cómo se producen, fusionan y muestran las entradas de presencia de OpenClaw
"Presencia" de OpenClaw es una vista ligera de mejor esfuerzo de:
- el Gateway mismo, y
- clientes conectados al Gateway (app mac, WebChat, CLI, etc.)
La presencia se usa principalmente para renderizar la pestaña Instancias de la app macOS y para proporcionar visibilidad rápida del operador.
Campos de presencia (qué aparece)
Las entradas de presencia son objetos estructurados con campos como:
- ''instanceId'' (opcional pero fuertemente recomendado): identidad de cliente estable (usualmente ''connect.client.instanceId'')
- ''host'': nombre de host amigable para humanos
- ''ip'': dirección IP de mejor esfuerzo
- ''version'': string de versión del cliente
- ''deviceFamily'' / ''modelIdentifier'': pistas 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'', ...
Productores (de dónde viene la presencia)
Las entradas de presencia son producidas por múltiples fuentes y fusionadas.
1) Entrada propia del Gateway
El Gateway siempre siembra una entrada "self" al inicio para que las UIs muestren el host del gateway
Anulaciones de runtime (solo propietario):
2) Conexión WebSocket
Cada cliente WS comienza con una solicitud ''connect''. En un handshake exitoso el
Gateway inserta/actualiza una entrada de presencia para esa conexión.
Por qué los comandos CLI puntuales no aparecen
El CLI a menudo se conecta para comandos cortos y puntuales. Para evitar spamear 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 ricas via el método ''system-event''. La app
mac usa esto para reportar nombre de host, IP, y ''lastInputSeconds''.
4) Conexiones de nodo (rol: node)
Cuando un nodo se conecta sobre el WebSocket del Gateway con ''role: node'', el Gateway
inserta/actualiza una entrada de presencia para ese nodo (mismo flujo que otros clientes WS).
Reglas de fusión + desduplicación (por qué `instanceId` importa)
Las entradas de presencia se almacenan en un único mapa en memoria:
- Las entradas se clavean por una clave de presencia.
ReferenceConceptsPresencePage.step08.p3
ReferenceConceptsPresencePage.step08.p4
ReferenceConceptsPresencePage.step08.p5
TTL y tamaño acotado
La presencia es intencionalmente efímera:
- TTL: entradas más antiguas de 5 minutos se podan
- Max entradas: 200 (las más antiguas se descartan primero)
Esto mantiene la lista fresca y evita crecimiento de memoria sin límite.
Caveat remoto/tunnel (IPs de loopback)
Cuando un cliente se conecta sobre un tunnel SSH / local port forward, el Gateway puede
ver la dirección remota como ''127.0.0.1''. Para evitar sobrescribir una buena IP
reportada por el cliente, las direcciones remotas de loopback se ignoran.
Consumidores
Pestaña de Instancias macOS
La app macOS renderiza la salida de ''system-presence'' y aplica un pequeño indicador
de estado (Active/Idle/Stale) basado en la antigüedad de la última actualización.
Tips de depuración
- Para ver la lista cruda, llama ''system-presence'' contra el Gateway.
- Si ves duplicados:
- confirma que los clientes envían un ''client.instanceId'' estable en el handshake
- confirma que las balizas periódicas usan el mismo ''instanceId''
- verifica si la entrada derivada de conexión falta ''instanceId'' (los duplicados son esperados)