Descubrimiento y Transportes
Descubrimiento de nodos y transportes (Bonjour, Tailscale, SSH) para encontrar el gateway
OpenClaw tiene dos problemas distintos que parecen similares en la superficie:
1. Control remoto del operador: la app de barra de menú de macOS controlando un gateway ejecutándose en otro lugar.
2. Emparejamiento de nodos: iOS/Android (y nodos futuros) encontrando un gateway y emparejando de forma segura.
El objetivo de diseño es mantener todo el descubrimiento/publicidad de red en el ''Node Gateway'' (''openclaw gateway'') y mantener clientes (mac app, iOS) solo como consumidores.
Términos
- Gateway: un único proceso de gateway de larga duración que posee estado (sesiones, emparejamiento, registro de nodos) y ejecuta canales. La mayoría de configuraciones usan uno por host; configuraciones multi-gateway aisladas son posibles.
- ''Gateway WS (plano de control)'': el endpoint WebSocket en ''127.0.0.1:18789'' por defecto; puede vincularse a LAN/tailnet via ''gateway.bind''.
- Transporte WS directo: un endpoint Gateway WS面向 LAN/tailnet (sin SSH).
- ''Transporte SSH (fallback)'': control remoto reenviando ''127.0.0.1:18789'' sobre SSH.
- ''Puente TCP legado (deprecado/removido)'': transporte de nodo antiguo (ver ''Protocolo Bridge''); ya no se anuncia para descubrimiento.
Detalles de protocolo:
Por qué mantenemos tanto "directo" como SSH
- WS Directo es la mejor UX en la misma red y dentro de un tailnet:
- Auto-descubrimiento en LAN via Bonjour
- Tokens de emparejamiento + ACLs propiedad del gateway
- No se requiere acceso shell; la superficie del protocolo puede mantenerse ajustada y auditable
- SSH permanece como el fallback universal:
- Funciona en cualquier lugar donde tengas acceso SSH (incluso a través de redes no relacionadas)
- Sobrevive problemas de multicast/mDNS
- No requiere nuevos puertos entrantes además de SSH
Entradas de descubrimiento (cómo los clientes aprenden dónde está el gateway)
#
1) Bonjour / mDNS (solo LAN)
Bonjour es de mejor esfuerzo y no cruza redes. Solo se usa para conveniencia de "misma LAN".
Dirección objetivo:
- El gateway anuncia su endpoint WS via Bonjour.
- Los clientes navegan y muestran una lista "elige un gateway", luego guardan el endpoint elegido.
Solución de problemas y detalles de beacon: ''Bonjour''.
##
Detalles del beacon de servicio
- Tipos de servicio:
- ''_openclaw-gw._tcp'' (beacon de transporte gateway)
- Claves TXT (no secretas):
- ''role=gateway''
- ''lanHost=<hostname>.local''
- ''sshPort=22'' (o puerto anunciado)
- ''gatewayPort=18789'' (Gateway WS + HTTP)
- ''gatewayTls=1'' (solo cuando TLS está habilitado)
- ''gatewayTlsSha256=<sha256>'' (solo cuando TLS está habilitado y fingerprint está disponible)
- ''canvasPort=18793'' (puerto host de canvas predeterminado; sirve ''/__openclaw__/canvas/'')
- ''cliPath=<path>'' (opcional; ruta absoluta a un entrypoint o binario ''openclaw'' ejecutable)
- ''tailnetDns=<magicdns>'' (pista opcional; auto-detectado cuando Tailscale está disponible)
Deshabilitar/override:
- ''OPENCLAW_DISABLE_BONJOUR=1'' deshabilita publicidad.
- ''gateway.bind'' en ''~/.openclaw/openclaw.json'' controla el modo de vinculación del Gateway.
- ''OPENCLAW_SSH_PORT'' sobrescribe el puerto SSH anunciado en TXT (predeterminado 22).
- ''OPENCLAW_TAILNET_DNS'' publica una pista ''tailnetDns'' (MagicDNS).
- ''OPENCLAW_CLI_PATH'' sobrescribe la ruta CLI anunciada.
#
2) Tailnet (cross-network)
Para configuraciones estilo Londres/Viena, Bonjour no ayudará. El objetivo "directo" recomendado es:
- Nombre Tailscale MagicDNS (preferido) o una IP de tailnet estable.
Si el gateway puede detectar que está ejecutándose bajo Tailscale, publica ''tailnetDns'' como una pista opcional para clientes (incluyendo beacons de área amplia).
#
3) Objetivo Manual / SSH
Cuando no hay ruta directa (o directo está deshabilitado), los clientes siempre pueden conectar via SSH reenviando el puerto gateway de loopback.
Ver ''Acceso remoto''.
Selección de transporte (política de cliente)
Comportamiento recomendado del cliente:
1. Si un endpoint directo emparejado está configurado y alcanzable, úsalo.
2. Si no, si Bonjour encuentra un gateway en LAN, ofrece una elección "Usar este gateway" de un toque y guárdalo como el endpoint directo.
3. Si no, si un DNS/IP de tailnet está configurado, intenta directo.
4. Si no, recurre a SSH.
Emparejamiento + auth (transporte directo)
El gateway es la fuente de verdad para admisión de nodos/clientes.
- Las solicitudes de emparejamiento se crean/aprueban/rechazan en el gateway (ver ''Emparejamiento Gateway'').
- El gateway aplica:
- auth (token / par de claves)
- scopes/ACLs (el gateway no es un proxy crudo a cada método)
- límites de tasa
Responsabilidades por componente
- Gateway: anuncia beacons de descubrimiento, posee 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 fallback.
- Nodos iOS/Android: navegan Bonjour como conveniencia y conectan al Gateway WS emparejado.