Protocolo Bridge (transporte de Node legacy)

Conectar diferentes partes de un sistema distribuido suele ser un dolor de cabeza, especialmente cuando los protocolos cambian y tienes que mantener compatibilidad con versiones anteriores. Si alguna vez has tenido que lidiar con sockets TCP que envían JSON línea por línea, sabes lo frustrante que es gestionar la comunicación cuando el estándar empieza a quedar obsoleto.

El protocolo Bridge es un transporte de Node legacy basado en TCP JSONL. Si estás construyendo un operador o un nuevo cliente de Node, mi recomendación es que ignores esto y uses el protocolo unificado Gateway WebSocket. Las versiones actuales de OpenClaw ya no incluyen el listener TCP de Bridge y las claves de configuración bridge.* han sido eliminadas.

What You’ll Need

• Una build de OpenClaw que aún soporte el listener TCP (referencia histórica).
• Un token por Node para gestionar la identidad y el acceso.
• Cliente TCP capaz de procesar JSONL (un objeto JSON por línea).
• Configuración de red compatible con Bonjour o una Tailnet para el descubrimiento.

Quick Start

Si necesitas trabajar con este protocolo por razones de compatibilidad, estos son los pasos para establecer la conexión:

1. Conexión inicial: Conéctate al puerto TCP 18790 (puerto por defecto en versiones legacy).
2. Handshake: Envía un mensaje hello que incluya los metadatos de tu Node y el token de emparejamiento.
3. Pairing: Si el Gateway responde con un error NOT_PAIRED, envía un pair-request.
4. Confirmación: Espera a que el Gateway envíe pair-ok y hello-ok tras la aprobación manual.

Frames y comunicación

La comunicación se divide en frames que viajan en ambas direcciones. Aquí tienes lo que puedes enviar y recibir:

De Cliente a Gateway:

• req / res: RPC para interactuar con chat, sesiones, configuración o salud del sistema.
• event: Señales del Node como transcripciones de voz o solicitudes del agente.

De Gateway a Cliente:

• invoke / invoke-res: Comandos directos al Node (cámara, ubicación, envío de SMS).
• event: Actualizaciones de chat para las sesiones a las que estés suscrito.
• ping / pong: Control de keepalive para mantener la conexión activa.

Eventos de ciclo de vida de ejecución

Los Nodes pueden informar sobre la actividad de system.run mediante eventos específicos. Estos datos se mapean a eventos del sistema en el Gateway:

• exec.finished: Indica que el comando terminó.
• exec.denied: Indica que la ejecución fue rechazada.

El payload de estos eventos requiere el sessionKey para identificar la sesión del agente. También puedes incluir de forma opcional el runId, el command ejecutado, el exitCode y el output resultante.

Uso con Tailnet

Si quieres usar el Bridge a través de una Tailnet, puedes vincularlo en tu archivo ~/.openclaw/openclaw.json:

{
  "bridge.bind": "tailnet"
}

Los clientes podrán conectarse usando el nombre MagicDNS o la IP de la Tailnet. Ten en cuenta que Bonjour no funciona a través de redes distintas; en esos casos, tendrás que configurar el host y el puerto de forma manual.

Troubleshooting

• Error NOT_PAIRED o UNAUTHORIZED: Esto ocurre si el token no es válido o el Node aún no ha sido aprobado. Debes iniciar un pair-request y esperar la aprobación en el Gateway.
• El Node no descubre el Gateway: Bonjour no cruza segmentos de red automáticamente. Si no estás en la misma LAN, usa la IP de la Tailnet o configura DNS-SD de área amplia.

Para resolver dudas específicas sobre tu implementación, consulta al AI Setup Assistant.

What’s Next

• Gateway protocol
• Node identity and pairing