Configura OpenClaw: Guía de descubrimiento y transporte

¿Alguna vez has intentado conectar dispositivos en una red local y has terminado peleando con direcciones IP que cambian o firewalls que no cooperan? Es frustrante cuando la tecnología, en lugar de ayudarte, se convierte en un obstáculo para tu flujo de trabajo diario.

OpenClaw maneja el descubrimiento de red de forma que tú no tengas que preocuparte por los detalles técnicos. Aquí te explico cómo funciona el sistema para que tus nodos y gateways se encuentren siempre, sin importar dónde estén.

Términos

• Gateway: un proceso único de larga duración que gestiona el estado (sesiones, emparejamiento, registro de nodos) y ejecuta canales. La mayoría de las configuraciones usan uno por host; es posible tener configuraciones multi-gateway aisladas.
• Gateway WS (control plane): el endpoint WebSocket en 127.0.0.1:18789 por defecto; puede vincularse a LAN/tailnet mediante gateway.bind.
• Direct WS transport: un endpoint Gateway WS orientado a LAN/tailnet (sin SSH).
• SSH transport (fallback): control remoto mediante el reenvío de 127.0.0.1:18789 sobre SSH.
• Legacy TCP bridge (deprecated/removed): transporte de nodo antiguo (ver Bridge protocol); ya no se anuncia para el descubrimiento.

Protocolos detallados:

• Gateway protocol
• Bridge protocol (legacy)

Por qué mantenemos tanto “direct” como SSH

• Direct WS ofrece la mejor experiencia de usuario en la misma red y dentro de una tailnet:
  • Cuenta con auto-descubrimiento en LAN vía Bonjour y tokens de emparejamiento con ACLs gestionadas por el gateway.
  • No requiere acceso a la shell, lo que permite que la superficie del protocolo se mantenga reducida y sea fácil de auditar.
• SSH sigue siendo la alternativa universal:
  • Funciona en cualquier lugar donde tengas acceso SSH (incluso en redes no relacionadas) y sobrevive a problemas de multicast/mDNS.
  • No requiere abrir nuevos puertos de entrada además del propio SSH.

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

1) Bonjour / mDNS (solo LAN)

Bonjour funciona según el principio de “mejor esfuerzo” y no cruza redes distintas. Solo se usa para mayor comodidad en la misma LAN.

Dirección del objetivo:

• El gateway anuncia su endpoint WS a través de Bonjour.
• Los clientes buscan y muestran una lista para “elegir un gateway”, y luego guardan el endpoint seleccionado.

Detalles de balizas y solución de problemas: Bonjour.

Detalles de la baliza del servicio

• Tipos de servicio:
  • _openclaw-gw._tcp (baliza de transporte del gateway)
• Claves TXT (no secretas):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (nombre visible configurado por el operador)
  • 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 está disponible)
  • canvasPort=<port> (puerto del host del canvas; actualmente el mismo que gatewayPort cuando el host del canvas está habilitado)
  • cliPath=<path> (opcional; ruta absoluta a un binario o punto de entrada openclaw ejecutable)
  • tailnetDns=<magicdns> (pista opcional; detectada automáticamente cuando Tailscale está disponible)

Notas de seguridad:

• Los registros TXT de Bonjour/mDNS no están autenticados. Los clientes deben tratar los valores TXT solo como pistas para la interfaz de usuario.
• El enrutamiento (host/puerto) debe preferir el endpoint del servicio resuelto (SRV + A/AAAA) sobre los valores lanHost, tailnetDns o gatewayPort proporcionados en el TXT.
• El anclaje de TLS (pinning) nunca debe permitir que un gatewayTlsSha256 anunciado sobrescriba un pin guardado previamente.
• Los nodos de 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” antes de guardar 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 vinculación del Gateway.
• OPENCLAW_SSH_PORT sobrescribe el puerto SSH anunciado en el TXT (por defecto es 22).
• OPENCLAW_TAILNET_DNS publica una pista de tailnetDns (MagicDNS).
• OPENCLAW_CLI_PATH sobrescribe la ruta de la CLI anunciada.

2) Tailnet (entre redes)

Para configuraciones que conectan distintas ubicaciones, Bonjour no servirá. El objetivo “directo” recomendado es:

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

Si el gateway detecta que se está ejecutando bajo Tailscale, publica tailnetDns como una pista opcional para los clientes (incluyendo balizas de área amplia).

La app de macOS ahora prefiere los nombres MagicDNS sobre las IPs puras de Tailscale para el descubrimiento del gateway. Esto mejora la fiabilidad cuando las IPs de la tailnet cambian (por ejemplo, tras reiniciar un nodo), ya que los nombres MagicDNS resuelven la IP actual automáticamente.

3) Objetivo manual / SSH

Cuando no hay una ruta directa (o la conexión directa está desactivada), los clientes siempre pueden conectarse vía SSH reenviando el puerto del gateway local.

Ver Remote access.

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

Comportamiento recomendado del cliente:

1. Si un endpoint directo emparejado está configurado y es alcanzable, úsalo.
2. Si no, si Bonjour encuentra un gateway en la LAN, ofrece la opción “Usar este gateway” con un toque y guárdalo como endpoint directo.
3. Si no, si hay una IP o DNS de tailnet configurada, intenta la conexión directa.
4. Como última opción, usa SSH.

Emparejamiento + autenticación (transporte directo)

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

• Las solicitudes de emparejamiento se crean, aprueban o rechazan en el gateway (ver Gateway pairing).
• El gateway aplica:
  • Autenticación (token / par de claves).
  • Ámbitos/ACLs (el gateway no es un proxy abierto a todos los métodos).
  • Límites de tasa (rate limits).

Responsabilidades por componente

• Gateway (Anuncio y Emparejamiento): anuncia las balizas de descubrimiento y toma las decisiones de emparejamiento.
• Gateway (Hosting): aloja el endpoint WS.
• App de macOS: te ayuda a elegir un gateway, muestra avisos de emparejamiento y usa SSH solo como alternativa.
• Nodos iOS/Android: buscan en Bonjour por conveniencia y se conectan al Gateway WS emparejado.

Siguientes pasos

• Protocolo del Gateway
• Acceso remoto
• Protocolo Bridge (legado)
• Configuración de Bonjour

AI Setup Assistant