Protocolo Bridge (transporte de nodos legacy)

El protocolo Bridge es un transporte de nodos legacy (TCP JSONL). Los nuevos clientes de nodo deben usar el protocolo unificado WebSocket del Gateway en su lugar.

Si estás construyendo un operador o cliente de nodo, usa el protocolo Gateway.

Nota: Las builds actuales de OpenClaw ya no incluyen el listener TCP bridge; este documento se conserva como referencia histórica. Las claves de configuración legacy bridge.* ya no forman parte del esquema de configuración.

Por qué existen ambos

Frontera de seguridad: el bridge expone una pequeña lista de permitidos en lugar de toda la superficie API del gateway.
Emparejamiento + identidad de nodo: la admisión de nodos es responsabilidad del gateway y está vinculada a un token por nodo.
UX de descubrimiento: los nodos pueden descubrir gateways vía Bonjour en LAN, o conectarse directamente por tailnet.
WS en loopback: el plano de control WS completo permanece local a menos que se tunelice vía SSH.

Transporte

TCP, un objeto JSON por línea (JSONL).
TLS opcional (cuando bridge.tls.enabled es true).
El puerto por defecto del listener legacy era 18790 (las builds actuales no inician un bridge TCP).

Cuando TLS está habilitado, los registros TXT de descubrimiento incluyen bridgeTls=1 más bridgeTlsSha256 como indicación no secreta. Ten en cuenta que los registros TXT de Bonjour/mDNS son no autenticados; los clientes no deben tratar la huella digital anunciada como un pin autoritativo sin la intención explícita del usuario u otra verificación fuera de banda.

Handshake + emparejamiento

El cliente envía hello con metadatos del nodo + token (si ya está emparejado).
Si no está emparejado, el gateway responde error (NOT_PAIRED/UNAUTHORIZED).
El cliente envía pair-request.
El gateway espera aprobación, luego envía pair-ok y hello-ok.

hello-ok devuelve serverName y puede incluir canvasHostUrl.

Tramas

Cliente → Gateway:

req / res: RPC del gateway con alcance (chat, sessions, config, health, voicewake, skills.bins)
event: señales del nodo (transcripción de voz, solicitud de agente, suscripción a chat, ciclo de vida exec)

Gateway → Cliente:

invoke / invoke-res: comandos del nodo (canvas.*, camera.*, screen.record, location.get, sms.send)
event: actualizaciones de chat para sesiones suscritas
ping / pong: keepalive

La aplicación de la lista de permitidos legacy vivía en src/gateway/server-bridge.ts (eliminado).

Eventos de ciclo de vida exec

Los nodos pueden emitir eventos exec.finished o exec.denied para exponer actividad de system.run. Estos se mapean a eventos del sistema en el gateway. (Los nodos legacy pueden seguir emitiendo exec.started.)

Campos del payload (todos opcionales excepto los indicados):

sessionKey (obligatorio): sesión del agente que recibe el evento del sistema.
runId: id único de exec para agrupar.
command: cadena de comando sin formato o formateada.
exitCode, timedOut, success, output: detalles de finalización (solo finished).
reason: razón de denegación (solo denied).

Uso con Tailnet

Enlaza el bridge a una IP tailnet: bridge.bind: "tailnet" en ~/.openclaw/openclaw.json.
Los clientes se conectan vía nombre MagicDNS o IP de tailnet.
Bonjour no cruza redes; usa host/puerto manual o DNS-SD de área amplia cuando sea necesario.

Versionado

Bridge es actualmente v1 implícito (sin negociación min/max). Se espera compatibilidad hacia atrás; agrega un campo de versión del protocolo bridge antes de cualquier cambio incompatible.