Descubrimiento y transportes

OpenClaw tiene dos problemas distintos que parecen similares en la superficie:

Control remoto del operador: la app de barra de menú de macOS controlando un gateway que se ejecuta en otro lugar.
Emparejamiento de nodos: iOS/Android (y futuros nodos) encontrando un gateway y emparejándose de forma segura.

El objetivo de diseño es mantener todo el descubrimiento/anuncio de red en el Gateway de nodos (openclaw gateway) y mantener a los clientes (app mac, iOS) como consumidores.

Términos

Gateway: un único proceso de gateway de larga duración que posee el estado (sesiones, emparejamiento, registro de nodos) y ejecuta canales. La mayoría de las configuraciones usan uno por host; las configuraciones aisladas de múltiples gateways son posibles.
Gateway WS (plano de control): el endpoint WebSocket en 127.0.0.1:18789 por defecto; puede enlazarse a LAN/tailnet vía gateway.bind.
Transporte WS directo: un endpoint Gateway WS orientado a LAN/tailnet (sin SSH).
Transporte SSH (respaldo): control remoto reenviando 127.0.0.1:18789 por SSH.
Bridge TCP legacy (obsoleto/eliminado): transporte de nodos antiguo (consulta Protocolo Bridge); ya no se anuncia para descubrimiento.

Detalles del protocolo:

Por qué mantenemos tanto “directo” como SSH

WS directo es la mejor experiencia en la misma red y dentro de una tailnet:
- auto-descubrimiento en LAN vía Bonjour
- tokens de emparejamiento + ACLs propiedad del gateway
- no se requiere acceso al shell; la superficie del protocolo puede mantenerse ajustada y auditable
SSH sigue siendo el respaldo universal:
- funciona en cualquier lugar donde tengas acceso SSH (incluso entre redes no relacionadas)
- sobrevive a problemas de multicast/mDNS
- no requiere nuevos puertos entrantes más allá de SSH

Entradas de descubrimiento (cómo los clientes aprenden dónde está el gateway)

1) Bonjour / mDNS (solo LAN)

Bonjour funciona con el mejor esfuerzo y no cruza redes. Solo se usa para la conveniencia de “misma LAN”.

Dirección objetivo:

El gateway anuncia su endpoint WS vía Bonjour.
Los clientes navegan y muestran una lista de “elegir un gateway”, luego almacenan el endpoint elegido.

Solución de problemas y detalles del beacon: Bonjour.

Detalles del beacon de servicio

Tipos de servicio:
- _openclaw-gw._tcp (beacon de transporte del gateway)
Claves TXT (no secretas):
- role=gateway
- lanHost=<hostname>.local
- sshPort=22 (o el que se anuncie)
- gatewayPort=18789 (Gateway WS + HTTP)
- gatewayTls=1 (solo cuando TLS está habilitado)
- gatewayTlsSha256=<sha256> (solo cuando TLS está habilitado y la huella digital está disponible)
- canvasPort=<puerto> (puerto del host canvas; actualmente el mismo que gatewayPort cuando el host canvas está habilitado)
- cliPath=<ruta> (opcional; ruta absoluta a un punto de entrada o binario ejecutable openclaw)
- tailnetDns=<magicdns> (indicación opcional; auto-detectada cuando Tailscale está disponible)

Notas de seguridad:

Los registros TXT de Bonjour/mDNS son no autenticados. Los clientes deben tratar los valores TXT solo como indicaciones de UX.
El enrutamiento (host/puerto) debe preferir el endpoint de servicio resuelto (SRV + A/AAAA) sobre lanHost, tailnetDns o gatewayPort proporcionados por TXT.
El pinning TLS nunca debe permitir que un gatewayTlsSha256 anunciado sobrescriba un pin previamente almacenado.
Los nodos iOS/Android deben tratar las conexiones directas basadas en descubrimiento como solo TLS y requerir una confirmación explícita de “confiar en esta huella digital” antes de almacenar un pin por primera vez (verificación fuera de banda).

Desactivar/sobrescribir:

OPENCLAW_DISABLE_BONJOUR=1 desactiva el anuncio.
gateway.bind en ~/.openclaw/openclaw.json controla el modo de enlace del Gateway.
OPENCLAW_SSH_PORT sobrescribe el puerto SSH anunciado en TXT (por defecto 22).
OPENCLAW_TAILNET_DNS publica una indicación tailnetDns (MagicDNS).
OPENCLAW_CLI_PATH sobrescribe la ruta CLI anunciada.

2) Tailnet (entre redes)

Para configuraciones tipo Londres/Viena, Bonjour no ayudará. El objetivo “directo” recomendado es:

Nombre MagicDNS de Tailscale (preferido) o una IP tailnet estable.

Si el gateway puede detectar que se ejecuta bajo Tailscale, publica tailnetDns como indicación opcional para clientes (incluyendo beacons de área amplia).

3) Manual / objetivo SSH

Cuando no hay ruta directa (o la directa está deshabilitada), los clientes siempre pueden conectarse vía SSH reenviando el puerto del gateway en loopback.

Consulta Acceso remoto.

Selección de transporte (política del cliente)

Comportamiento recomendado del cliente:

Si un endpoint directo emparejado está configurado y es accesible, úsalo.
Si no, si Bonjour encuentra un gateway en LAN, ofrece una opción de “Usar este gateway” con un toque y guárdalo como endpoint directo.
Si no, si hay un DNS/IP de tailnet configurado, intenta directo.
Si no, usa SSH como respaldo.

Emparejamiento + autenticación (transporte directo)

El gateway es la fuente de verdad para la admisión de nodos/clientes.

Las solicitudes de emparejamiento se crean/aprueban/rechazan en el gateway (consulta Emparejamiento del gateway).
El gateway aplica:
- autenticación (token / par de claves)
- alcances/ACLs (el gateway no es un proxy directo a todos los métodos)
- límites de tasa

Responsabilidades por componente

Gateway: anuncia beacons de descubrimiento, posee las decisiones de emparejamiento y aloja el endpoint WS.
App macOS: te ayuda a elegir un gateway, muestra prompts de emparejamiento y usa SSH solo como respaldo.
Nodos iOS/Android: navegan Bonjour como conveniencia y se conectan al Gateway WS emparejado.