Descubrimiento y transportes

Descubrimiento y transportes

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

1. Control remoto del operador: la aplicación de la barra de menús de macOS que controla una puerta de enlace que se ejecuta en otro lugar.
2. Emparejamiento de nodos: iOS/Android (y nodos futuros) encuentran una puerta de enlace y se emparejan de forma segura.

El objetivo de diseño es mantener todo el descubrimiento/publicidad de red en el Node Gateway (openclaw gateway) y mantener los clientes (aplicación Mac, iOS) como consumidores.

Términos

• Gateway: un único proceso de puerta de enlace de larga duración que posee el estado (sesiones, emparejamiento, registro de nodos) y ejecuta canales. La mayoría de las configuraciones utilizan uno por host; son posibles configuraciones de múltiples puertas de enlace aisladas.
• Gateway WS (plano de control): el punto final WebSocket en 127.0.0.1:18789 de forma predeterminada; se puede vincular a LAN/tailnet mediante gateway.bind.
• Transporte WS directo: un punto final de Gateway WS orientado a LAN/tailnet (sin SSH).
• Transporte SSH (alternativo): control remoto mediante el reenvío de 127.0.0.1:18789 a través de SSH.
• Puente TCP heredado (obsoleto/eliminado): transporte de nodo antiguo (ver Protocolo de puente); ya no se anuncia para el descubrimiento.

Detalles del protocolo:

• Protocolo de Gateway
• Protocolo de puente (heredado)

Por qué mantenemos tanto “direct” como SSH

• WS directo es la mejor experiencia de usuario en la misma red y dentro de una tailnet:
  • descubrimiento automático en LAN mediante Bonjour
  • tokens de emparejamiento + ACLs propiedad de la puerta de enlace
  • no requiere acceso al shell; la superficie del protocolo puede permanecer cerrada y auditable
• SSH sigue siendo la alternativa universal:
  • funciona en cualquier lugar donde tenga acceso SSH (incluso a través de redes no relacionadas)
  • sobrevive a problemas de multidifusión/mDNS
  • no requiere nuevos puertos de entrada además de SSH

Entradas de descubrimiento (cómo saben los clientes dónde está la puerta de enlace)

1) Bonjour / mDNS (solo LAN)

Bonjour es de mejor esfuerzo y no cruza redes. Solo se usa por conveniencia de “misma LAN”.

Dirección de destino:

• La puerta de enlace anuncia su punto final WS a través de Bonjour.
• Los clientes exploran y muestran una lista de “elegir una puerta de enlace”, y luego almacenan el punto de conexión elegido.

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

Detalles de la baliza de servicio

• Tipos de servicio:
  • _openclaw-gw._tcp (baliza de transporte de puerta de enlace)
• Claves TXT (no secretas):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (nombre de visualización configurado por el operador)
  • lanHost=<hostname>.local
  • sshPort=22 (o lo 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=<port> (puerto del host del lienzo; actualmente el mismo que gatewayPort cuando el host del lienzo está habilitado)
  • cliPath=<path> (opcional; ruta absoluta a un punto de entrada openclaw ejecutable o binario)
  • tailnetDns=<magicdns> (sugerencia opcional; autodetectado cuando Tailscale está disponible)

Notas de seguridad:

• Los registros TXT de Bonjour/mDNS están sin autenticar. Los clientes deben tratar los valores TXT solo como sugerencias de UX.
• El enrutamiento (host/puerto) debe preferir el punto de conexión del servicio resuelto (SRV + A/AAAA) sobre los lanHost, tailnetDns o gatewayPort proporcionados por TXT.
• El anclaje TLS nunca debe permitir un gatewayTlsSha256 anunciado para anular un anclaje previamente almacenado.
• Los nodos iOS/Android deben tratar las conexiones directas basadas en descubrimiento como solo TLS y requieren una confirmación explícita de “confiar en esta huella digital” antes de almacenar un anclaje por primera vez (verificación fuera de banda).

Deshabilitar/sobrescribir:

• OPENCLAW_DISABLE_BONJOUR=1 deshabilita la publicidad.
• 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 es 22).
• OPENCLAW_TAILNET_DNS publica una sugerencia tailnetDns (MagicDNS).
• OPENCLAW_CLI_PATH sobrescribe la ruta del 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 la puerta de enlace puede detectar que se está ejecutando bajo Tailscale, publica tailnetDns como sugerencia opcional para los clientes (incluidos los balizas de área amplia).

La aplicación de macOS ahora prefiere los nombres MagicDNS sobre las IPs de Tailscale sin procesar para el descubrimiento de la puerta de enlace. Esto mejora la confiabilidad cuando las IPs de la tailnet cambian (por ejemplo, después de reiniciar el nodo o la reasignación de CGNAT), ya que los nombres MagicDNS se resuelven a la IP actual automáticamente.

3) Objetivo Manual / SSH

Cuando no hay una ruta directa (o lo directo está deshabilitado), los clientes siempre pueden conectarse a través de SSH reenviando el puerto de la puerta de enlace de loopback.

Consulte Acceso remoto.

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

Comportamiento recomendado del cliente:

1. Si se configura y se puede alcanzar un punto final directo emparejado, úselo.
2. De lo contrario, si Bonjour encuentra una puerta de enlace en la LAN, ofrezca una elección de “Usar esta puerta de enlace” con un solo toque y guárdela como el punto final directo.
3. De lo contrario, si se configura un DNS/IP de tailnet, intente directamente.
4. De lo contrario, recurra a SSH.

Emparejamiento + autenticación (transporte directo)

La puerta de enlace es la fuente de verdad para la admisión de nodos/clientes.

• Las solicitudes de emparejamiento se crean/aprueban/rechazan en la puerta de enlace (consulte Emparejamiento de puerta de enlace).
• La puerta de enlace hace cumplir:
  • autenticación (token / par de claves)
  • ámbitos/ACL (la puerta de enlace no es un proxy sin procesar para cada método)
  • límites de velocidad

Responsabilidades por componente

• Gateway: anuncia balizas de descubrimiento, posee decisiones de emparejamiento y aloja el punto final WS.
• macOS app: le ayuda a elegir una puerta de enlace, muestra indicaciones de emparejamiento y usa SSH solo como respaldo.
• iOS/Android nodes: exploran Bonjour por conveniencia y se conectan al WS de la puerta de enlace emparejada.