Saltar al contenido principal

​
Descubrimiento Bonjour / mDNS

OpenClaw usa Bonjour (mDNS / DNS‑SD) como una conveniencia solo para LAN para descubrir un Gateway activo (endpoint WebSocket). Es de mejor esfuerzo y no reemplaza SSH ni la conectividad basada en Tailnet.

​
Bonjour de área amplia (DNS‑SD unicast) sobre Tailscale

Si el nodo y el gateway están en redes diferentes, el mDNS multicast no cruzará el límite. Puede mantener la misma UX de descubrimiento cambiando a DNS‑SD unicast (“Wide‑Area Bonjour”) sobre Tailscale. Pasos de alto nivel:
  1. Ejecute un servidor DNS en el host del Gateway (accesible por Tailnet).
  2. Publique registros DNS‑SD para _openclaw-gw._tcp bajo una zona dedicada (ejemplo: openclaw.internal.).
  3. Configure DNS dividido de Tailscale para que su dominio elegido se resuelva a través de ese servidor DNS para los clientes (incluido iOS).
OpenClaw admite cualquier dominio de descubrimiento; openclaw.internal. es solo un ejemplo. Los nodos iOS/Android exploran tanto local. como su dominio de área amplia configurado.

​
Configuración del Gateway (recomendado)

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

​
Configuración única del servidor DNS (host del Gateway)

openclaw dns setup --apply
Esto instala CoreDNS y lo configura para:
  • escuchar en el puerto 53 solo en las interfaces Tailscale del Gateway
  • servir su dominio elegido (ejemplo: openclaw.internal.) desde ~/.openclaw/dns/<domain>.db
Valide desde una máquina conectada a tailnet: 
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

​
Configuración de DNS en Tailscale

En la consola de administración de Tailscale:
  • Agregue un servidor de nombres que apunte a la IP de tailnet del Gateway (UDP/TCP 53).
  • Agregue DNS dividido para que su dominio de descubrimiento use ese servidor de nombres.
Una vez que los clientes acepten el DNS de tailnet, los nodos iOS pueden explorar _openclaw-gw._tcp en su dominio de descubrimiento sin multicast.

​
Seguridad del listener del Gateway (recomendado)

El puerto WS del Gateway (predeterminado 18789) se vincula a loopback de forma predeterminada. Para acceso por LAN/tailnet, vincúlelo explícitamente y mantenga la autenticación habilitada. Para configuraciones solo de tailnet:
  • Establezca gateway.bind: "tailnet" en ~/.openclaw/openclaw.json.
  • Reinicie el Gateway (o reinicie la app de la barra de menús de macOS).

​
Qué anuncia

Solo el Gateway anuncia _openclaw-gw._tcp.

​
Tipos de servicio

  • _openclaw-gw._tcp — baliza de transporte del gateway (usada por nodos macOS/iOS/Android).

​
Claves TXT (pistas no secretas)

El Gateway anuncia pequeñas pistas no secretas para facilitar los flujos de la UI:
  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (Gateway WS + HTTP)
  • gatewayTls=1 (solo cuando TLS está habilitado)
  • gatewayTlsSha256=<sha256> (solo cuando TLS está habilitado y la huella está disponible)
  • canvasPort=<port> (solo cuando el host del lienzo está habilitado; predeterminado 18793)
  • sshPort=<port> (predetermina a 22 cuando no se sobrescribe)
  • transport=gateway
  • cliPath=<path> (opcional; ruta absoluta a un punto de entrada openclaw ejecutable)
  • tailnetDns=<magicdns> (pista opcional cuando Tailnet está disponible)
Notas de seguridad:
  • Los registros TXT de Bonjour/mDNS son no autenticados. Los clientes no deben tratar TXT como enrutamiento autorizado.
  • Los clientes deben enrutar utilizando el endpoint de servicio resuelto (SRV + A/AAAA). Trata lanHost, tailnetDns, gatewayPort y gatewayTlsSha256 solo como indicaciones.
  • El TLS pinning nunca debe permitir que un gatewayTlsSha256 anunciado sobrescriba un pin almacenado previamente.
  • Los nodos iOS/Android deben tratar las conexiones directas basadas en descubrimiento como solo TLS y requerir confirmación explícita del usuario antes de confiar en una huella digital vista por primera vez.

​
Depuración en macOS

Herramientas integradas útiles:
  • Explorar instancias: 
    dns-sd -B _openclaw-gw._tcp local.
  • Resolver una instancia (reemplace <instance>): 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.
Si explorar funciona pero resolver falla, normalmente se trata de una política de LAN o un problema del resolvedor mDNS.

​
Depuración en los registros del Gateway

El Gateway escribe un archivo de registro rotativo (impreso al iniciar como gateway log file: ...). Busque líneas bonjour:, especialmente:
  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

​
Depuración en el nodo iOS

El nodo iOS usa NWBrowser para descubrir _openclaw-gw._tcp. Para capturar registros:
  • Configuración → Gateway → Avanzado → Registros de depuración de descubrimiento
  • Configuración → Gateway → Avanzado → Registros de descubrimiento → reproducir → Copiar
El registro incluye transiciones de estado del explorador y cambios del conjunto de resultados.

​
Modos de falla comunes

  • Bonjour no cruza redes: use Tailnet o SSH.
  • Multicast bloqueado: algunas redes Wi‑Fi deshabilitan mDNS.
  • Suspensión / cambios de interfaz: macOS puede soltar temporalmente resultados mDNS; reintente.
  • Explorar funciona pero resolver falla: mantenga los nombres de máquina simples (evite emojis o puntuación), luego reinicie el Gateway. El nombre de la instancia del servicio deriva del nombre del host, por lo que nombres excesivamente complejos pueden confundir a algunos resolvers.

​
Nombres de instancia escapados (\032)

Bonjour/DNS‑SD a menudo escapa bytes en los nombres de instancia del servicio como secuencias decimales \DDD (p. ej., los espacios se convierten en \032).
  • Esto es normal a nivel de protocolo.
  • Las UIs deben decodificar para la visualización (iOS usa BonjourEscapes.decode).

​
Deshabilitación / configuración

  • OPENCLAW_DISABLE_BONJOUR=1 deshabilita la publicación (legado: OPENCLAW_DISABLE_BONJOUR).
  • gateway.bind en ~/.openclaw/openclaw.json controla el modo de vinculación del Gateway.
  • OPENCLAW_SSH_PORT sobrescribe el puerto SSH anunciado en TXT (legado: OPENCLAW_SSH_PORT).
  • OPENCLAW_TAILNET_DNS publica una pista de MagicDNS en TXT (legado: OPENCLAW_TAILNET_DNS).
  • OPENCLAW_CLI_PATH sobrescribe la ruta de la CLI anunciada (legado: OPENCLAW_CLI_PATH).

​
Documentos relacionados

  • Política de descubrimiento y selección de transporte: Discovery
  • Emparejamiento de nodos + aprobaciones: Gateway pairing