Presencia

La «presencia» de OpenClaw es una vista ligera y basada en el mejor esfuerzo de:

• el propio Gateway, y
• los clientes visibles para el usuario conectados al Gateway (aplicación para Mac, WebChat, nodos, etc.)

La presencia muestra metadatos de conexión en tiempo real en la página Dispositivos de la interfaz de control (en Configuración → Dispositivos) y en la pestaña Instancias de la aplicación para macOS.

Esta página trata sobre la lista de clientes del Gateway. Para detectar el Mac que se ha usado más recientemente y dirigir allí las alertas de los nodos, consulta Presencia del ordenador activo.

Campos de presencia (qué se muestra)

Las entradas de presencia son objetos estructurados con campos como:

• instanceId (opcional, pero muy recomendable): identidad estable del cliente (normalmente connect.client.instanceId)
• host: nombre de host fácil de reconocer
• ip: dirección IP basada en el mejor esfuerzo
• version: cadena de versión del cliente
• deviceFamily / modelIdentifier: indicaciones de hardware
• mode: ui, webchat, cli, backend, node, probe, test
• lastInputSeconds: segundos desde la última entrada del usuario, si se conoce
• reason: cadena de formato libre proporcionada por el cliente; el propio Gateway solo emite self, connect y disconnect
• deviceId, roles, scopes: identidad del dispositivo e indicaciones de rol y ámbito procedentes del protocolo de enlace de conexión
• ts: marca de tiempo de la última actualización (ms desde la época)

Productores (de dónde procede la presencia)

Las entradas de presencia se generan a partir de varias fuentes y se combinan.

1) Entrada del propio Gateway

El Gateway siempre crea una entrada «propia» al iniciarse para que las interfaces de usuario muestren el host del Gateway incluso antes de que se conecte ningún cliente.

2) Conexión WebSocket

Cada cliente WS comienza con una solicitud connect. Cuando el protocolo de enlace finaliza correctamente, el Gateway inserta o actualiza una entrada de presencia para esa conexión.

Por qué no aparecen las conexiones efímeras del plano de control

Los comandos de la CLI, los clientes RPC de backend y las sondas suelen conectarse brevemente. Para evitar conservar esa rotación durante todo el TTL de presencia, los clientes en modo cli, backend o probe no se convierten en entradas de presencia. Los clientes en modo de prueba se siguen registrando porque los conjuntos de pruebas los utilizan como sustitutos de clientes reales.

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 lo utiliza para comunicar el nombre del host, la IP, la versión y los metadatos de disponibilidad. La actividad de entrada física no forma parte de esta baliza genérica; el evento nativo específico del nodo descrito en Presencia del ordenador activo se encarga de ella. El Mac etiqueta estas balizas con system-presence-clear-last-input; los Gateways actuales utilizan ese marcador compatible con versiones anteriores para eliminar cualquier dato de actividad de entrada reciente conservado de una aplicación anterior. La baliza también incluye un valor fijo de 30 días para que los Gateways antiguos que ignoran la etiqueta sobrescriban la actividad reciente exacta en lugar de conservarla. No se muestrea ninguna actividad nueva para este valor de compatibilidad.

4) Conexiones de nodos (rol: nodo)

Cuando un nodo se conecta mediante el WebSocket del Gateway con role: node, el Gateway inserta o actualiza una entrada de presencia para ese nodo (el mismo flujo que para los demás clientes WS).

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

Las entradas de presencia se almacenan en un único mapa en memoria, cuyas claves no distinguen entre mayúsculas y minúsculas y corresponden al primer valor disponible, en este orden: un identificador de dispositivo emparejado, connect.client.instanceId o, como último recurso, el identificador de cada conexión.

Los clientes efímeros del plano de control se excluyen por completo del seguimiento (consulta la explicación anterior), por lo que sus identificadores de conexión nunca se convierten en claves. Para el resto de los clientes, el uso alternativo del identificador de conexión implica que un cliente que vuelve a conectarse sin un instanceId estable aparece como una fila duplicada.

TTL y tamaño limitado

La presencia es efímera de forma intencionada:

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

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

Advertencia sobre conexiones remotas y túneles (IP de bucle local)

Cuando un cliente se conecta mediante un túnel SSH o un reenvío de puerto local, el Gateway puede ver la dirección remota como 127.0.0.1. Para evitar registrar esa dirección del túnel como IP del cliente, el procesamiento de la conexión omite por completo ip para los clientes detectados como locales (bucle local), en lugar de escribir la dirección de bucle local en la entrada.

Consumidores

Página Dispositivos de la interfaz de control

La página Dispositivos combina system-presence con los registros persistentes de emparejamiento y nodos. Fija primero la baliza propia del Gateway y utiliza los identificadores coincidentes de dispositivo o instancia para los metadatos en tiempo real de plataforma, versión, modelo y actividad de entrada reciente.

Pestaña Instancias de macOS

La aplicación para macOS muestra 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 en el Gateway.
• Si aparecen duplicados:
  • confirma que los clientes envíen un client.instanceId estable en el protocolo de enlace
  • confirma que las balizas periódicas utilicen el mismo instanceId
  • comprueba si a la entrada derivada de la conexión le falta instanceId (en ese caso, los duplicados son previsibles)

Contenido relacionado