Gateway
Protocolo del puente
Por qué existía
- Límite de seguridad: exponía una pequeña lista de permitidos en lugar de toda la superficie de la API del Gateway.
- Emparejamiento e identidad del nodo: la admisión de nodos estaba a cargo del Gateway y vinculada a un token específico de cada nodo.
- Experiencia de detección: los nodos podían detectar Gateways mediante Bonjour en la red LAN o conectarse directamente a través de una tailnet.
- WS en local loopback: el plano de control WS completo permanecía local, salvo que se canalizara mediante SSH.
Transporte
- TCP, un objeto JSON por línea (JSONL).
- TLS opcional (
bridge.tls.enabled: true). - El puerto predeterminado del proceso de escucha era
18790.
Cuando TLS estaba habilitado, los registros TXT de detección incluían bridgeTls=1 y bridgeTlsSha256 como indicación no secreta. Los registros TXT de Bonjour/mDNS no están autenticados; los clientes no podían tratar la huella digital anunciada como un pin autoritativo sin otra verificación fuera de banda.
Negociación inicial y emparejamiento
- El cliente envía
hellocon los metadatos del nodo y el token (si ya está emparejado). - Si no está emparejado, el Gateway responde con
error(NOT_PAIRED/UNAUTHORIZED). - El cliente envía
pair-request. - El Gateway espera la aprobación y, a continuación, envía
pair-okyhello-ok.
Anteriormente, hello-ok devolvía serverName; las superficies de Plugin alojadas ahora se anuncian mediante pluginSurfaceUrls en el protocolo actual del Gateway (Canvas/A2UI usa pluginSurfaceUrls.canvas).
Tramas
Del cliente al Gateway:
req/res: RPC con ámbito limitado del Gateway (chat, sesiones, configuración, estado, activación por voz, skills.bins).event: señales del nodo (transcripción de voz, solicitud del agente, suscripción al chat, ciclo de vida de ejecución).
Del Gateway al cliente:
invoke/invoke-res: comandos del nodo (canvas.*,camera.*,screen.record,location.get,sms.send).event: actualizaciones del chat para las sesiones suscritas.ping/pong: mantenimiento de la conexión.
La aplicación de la lista de permitidos se encontraba en src/gateway/server-bridge.ts (eliminado).
Eventos del ciclo de vida de ejecución
Los nodos emitían exec.finished para mostrar la actividad completada de system.run, que el Gateway asignaba a eventos del sistema (los nodos heredados también podían emitir exec.started). exec.denied marcaba un intento denegado de system.run como denegación terminal, sin poner en cola un evento del sistema ni activar el trabajo del agente.
Campos de la carga útil (todos opcionales, salvo que se indique lo contrario):
| Campo | Notas |
|---|---|
sessionKey |
Obligatorio. Sesión del agente para correlacionar eventos y, en el caso de exec.finished, entregar el evento del sistema. |
runId |
Identificador único de la ejecución para agrupar. |
command |
Cadena del comando sin procesar o con formato. |
exitCode, timedOut, output |
Detalles de finalización (solo cuando finaliza). |
reason |
Motivo de la denegación (solo cuando se deniega). |
Uso histórico de tailnet
- Vincular el puente a una dirección IP de tailnet:
bridge.bind: "tailnet"en~/.openclaw/openclaw.json(solo con fines históricos;bridge.*ya no es una configuración válida). - Los clientes se conectaban mediante el nombre de MagicDNS o la dirección IP de tailnet.
- Bonjour no atraviesa redes; de lo contrario, se requería DNS-SD de área extensa o un host y puerto especificados manualmente.
Control de versiones
El puente usaba implícitamente la versión 1, sin negociación de valores mínimos y máximos. Los clientes actuales de nodos y operadores usan el protocolo del Gateway mediante WebSocket, que sí negocia un intervalo de versiones del protocolo.
