OpenClawSkills
GitHub
Gateway / Operaciones • 5 min de lectura

Descubrimiento Bonjour

Descubrimiento Bonjour/mDNS + debugging (beacons del Gateway, clientes y modos de falla comunes)

OpenClaw usa Bonjour (mDNS / DNS‑SD) como una **conveniencia solo LAN** para descubrir un Gateway activo (endpoint WebSocket). Es best-effort y **no** reemplaza conectividad basada en SSH o Tailnet.

Tutorial.step

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

Si el nodo y gateway están en redes diferentes, mDNS multicast no cruzará el límite. Puedes mantener el mismo UX de descubrimiento cambiando a **DNS‑SD unicast** ("Bonjour de Área Amplia") sobre Tailscale.

Pasos de alto nivel:

  1. Ejecuta un servidor DNS en el host del gateway (alcanzable sobre Tailnet).
  2. Publica registros DNS-SD para _openclaw-gw._tcp bajo una zona dedicada (ejemplo: openclaw.internal.).
  3. Configura **split DNS** de Tailscale para que tu dominio elegido resuelva vía ese servidor DNS para clientes (incluyendo iOS).

OpenClaw soporta cualquier dominio de descubrimiento; openclaw.internal. es solo un ejemplo.

Nodos iOS/Android navegan tanto local. como tu dominio de área amplia configurado.

Tutorial.step

Config del Gateway (recomendado)

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

Configuración única del servidor DNS (host del gateway)

Bash
openclaw dns setup --apply

Esto instala CoreDNS y lo configura para:

  • escuchar en puerto 53 solo en las interfaces Tailscale del gateway
  • ~/.openclaw/dns/<dominio>.db para servir un dominio elegido (ej., openclaw.internal.)

ReferenceGatewayBonjourPage.steps.dnsSetup.p2

Bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
Tutorial.step

Configuración DNS de Tailscale

En la consola de administración de Tailscale:

  • Agrega un servidor de nombres apuntando a la IP tailnet del gateway (UDP/TCP 53).
  • Agrega DNS dividido para que tu dominio de descubrimiento use ese servidor de nombres.

Una vez que los clientes aceptan DNS tailnet, los nodos iOS pueden navegar _openclaw-gw._tcp en tu dominio de descubrimiento sin multicast.

Tutorial.step

Seguridad del listener del Gateway (recomendado)

El puerto WS del Gateway (predeterminado 18789) se vincula a loopback por defecto. Para acceso LAN/tailnet, vincula explícitamente y mantén auth habilitado.

Para configuraciones solo tailnet:

  • Establece gateway.bind: "tailnet" en ~/.openclaw/openclaw.json.
  • Reinicia el Gateway (o reinicia la app de menubar de macOS).
Tutorial.step

Qué anuncia

Solo el Gateway anuncia _openclaw-gw._tcp.

Tutorial.step

Tipos de servicio

  • _openclaw-gw._tcp — beacon de transporte del gateway (usado por nodos macOS/iOS/Android).
Tutorial.step

Claves TXT (hints no secretos)

El Gateway anuncia pequeños hints no secretos para hacer los flujos de UI convenientes:

  • role=gateway
  • <code>displayName=<nombre amigable>'</code>
  • <code>lanHost=<hostname>.local</code>
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.gatewayPort
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.gatewayTls
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.gatewayTlsSha256
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.canvasPort
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.sshPort
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.transport
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.cliPath
  • ReferenceGatewayBonjourPage.steps.txtKeys.items.tailnetDns
Tutorial.step

Debugging on macOS

Useful built-in tools:

Browse instances:

Bash
dns-sd -B _openclaw-gw._tcp local.

Resolve an instance (replace &lt;instance&gt;):

Bash
dns-sd -L "<instance>" _openclaw-gw._tcp local.

Si la navegación funciona pero la resolución falla, generalmente estás encontrando una política LAN o problema de resolvedor mDNS.

Tutorial.step

Debugging in Gateway logs

The Gateway writes a rolling log file (printed on startup as gateway log file: ...). Look for bonjour: lines, especially:

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...
Tutorial.step

Debugging on iOS node

El nodo iOS usa NWBrowser para descubrir _openclaw-gw._tcp.

To capture logs:

  • Settings → Gateway → Advanced → **Discovery Debug Logs**
  • Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**

El log incluye transiciones de estado del navegador y cambios del conjunto de resultados.

Tutorial.step

Modos de fallo comunes

  • Bonjour doesn't cross networks: use Tailnet or SSH.
  • Multicast blocked: some Wi-Fi networks disable mDNS.
  • Sleep / interface churn: macOS may temporarily drop mDNS results; retry.
  • Browse works but resolve fails: keep machine names simple (avoid emojis or punctuation), then restart the Gateway. The service instance name derives from the host name, so overly complex names can confuse some resolvers.
Tutorial.step

Nombres de instancia escapados (\032)

Bonjour/DNS-SD frecuentemente escapa bytes en nombres de instancia de servicio como secuencias decimales \DDD (ej. espacios se convierten en \032).

  • Esto es normal a nivel de protocolo.
  • Las UIs deben decodificar para visualización (iOS usa BonjourEscapes.decode).
Tutorial.step

Deshabilitar / configuración

  • OPENCLAW_DISABLE_BONJOUR=1 deshabilita advertising.
  • gateway.bind en ~/.openclaw/openclaw.json controla el modo de vinculación del Gateway.
  • OPENCLAW_SSH_PORT anula el puerto SSH anunciado en TXT.
  • OPENCLAW_TAILNET_DNS publica una pista MagicDNS en TXT.
  • OPENCLAW_CLI_PATH anula la ruta CLI anunciada.
Tutorial.step

Documentos relacionados

  • Política de descubrimiento y selección de transporte: [Descubrimiento](/gateway/discovery)
  • Emparejamiento de nodo + aprobaciones: [Emparejamiento del Gateway](/gateway/pairing)