Protocolo Bridge (Legacy)

El protocolo Bridge es un transporte de nodo **legacy** (TCP JSONL). Los nuevos clientes de nodo deberían usar el protocolo WebSocket unificado del Gateway.

Si eres operador o construyendo un cliente de nodo, usa el protocolo Gateway.

Ver [Protocolo Gateway](/gateway/protocol).

Nota: El OpenClaw actual no proporciona un listener de bridge TCP. Esta página permanece como referencia histórica.

Las claves de config legacy bridge.* ya no son parte del schema de configuración.

• Límite de seguridad: el bridge expone una pequeña lista permitida en lugar de la superficie completa de API del gateway.
• Emparejamiento + identidad de nodo: la admisión de nodo es propiedad del gateway y vinculada a un token por nodo.
• UX de descubrimiento: los nodos pueden descubrir gateways via Bonjour en LAN, o conectar directamente sobre un tailnet.
• WS de loopback: el plano de control WS completo permanece local a menos que se tunelice via SSH.

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

Cuando TLS está habilitado, los registros TXT de descubrimiento incluyen bridgeTls=1 más bridgeTlsSha256 para que los nodos puedan fijar el certificado.

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

hello-ok devuelve serverName y puede incluir canvasHostUrl.

Cliente → Gateway:

• req / res: RPC de gateway con scope (chat, sesiones, config, salud, voicewake, skills.bins)
• event: señales de nodo (transcripción de voz, solicitud de agente, suscripción de chat, ciclo de vida de exec)

Gateway → Cliente:

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

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

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

Campos de payload (todos opcionales a menos que se indique):

Campos de payload (todos opcionales a menos que se indique):

• sessionKey (requerido): sesión de agente para recibir el evento del sistema.
• runId: id de exec único para agrupar.
• command: string de comando raw o formateado.
• exitCode, timedOut, success, output: detalles de completación (solo terminado).
• reason: razón de denegación (solo denegado).

• Vincular el bridge a una IP de tailnet: bridge.bind: "tailnet" en ~/.openclaw/openclaw.json.
• Los clientes conectan via nombre MagicDNS o IP de tailnet.
• Bonjour **no** cruza redes; usa host/puerto manual o DNS‑SD de área amplia cuando sea necesario.

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