Descubrimiento Bonjour / mDNS

OpenClaw usa Bonjour (mDNS / DNS-SD) como una conveniencia solo para LAN para descubrir un Gateway activo (endpoint WebSocket). Funciona con el 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, mDNS multicast no cruzará la frontera. Puedes mantener la misma experiencia de descubrimiento cambiando a DNS-SD unicast (“Bonjour de área amplia”) sobre Tailscale.

Pasos generales:

Ejecuta un servidor DNS en el host del gateway (accesible por Tailnet).
Publica registros DNS-SD para _openclaw-gw._tcp bajo una zona dedicada (ejemplo: openclaw.internal.).
Configura el DNS dividido de Tailscale para que tu dominio elegido resuelva a través de ese servidor DNS para los clientes (incluyendo iOS).

OpenClaw soporta cualquier dominio de descubrimiento; openclaw.internal. es solo un ejemplo. Los nodos iOS/Android navegan tanto local. como tu dominio de área amplia configurado.

Configuración del Gateway (recomendada)

{
  gateway: { bind: "tailnet" }, // solo tailnet (recomendado)
  discovery: { wideArea: { enabled: true } }, // habilita publicación DNS-SD de área amplia
}

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 tu dominio elegido (ejemplo: openclaw.internal.) desde ~/.openclaw/dns/<domain>.db

Valida desde una máquina conectada a la tailnet:

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

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 acepten el DNS de tailnet, los nodos iOS pueden navegar _openclaw-gw._tcp en tu dominio de descubrimiento sin multicast.

Seguridad del listener del Gateway (recomendada)

El puerto WS del Gateway (por defecto 18789) se enlaza a loopback por defecto. Para acceso LAN/tailnet, enlaza explícitamente y mantén la autenticación habilitada.

Para configuraciones solo tailnet:

Configura gateway.bind: "tailnet" en ~/.openclaw/openclaw.json.
Reinicia el Gateway (o reinicia la app de barra de menú de macOS).

Qué se anuncia

Solo el Gateway anuncia _openclaw-gw._tcp.

Tipos de servicio

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

Claves TXT (indicaciones no secretas)

El Gateway anuncia pequeñas indicaciones no secretas para hacer convenientes los flujos de UI:

role=gateway
displayName=<nombre amigable>
lanHost=<hostname>.local
gatewayPort=<puerto> (Gateway WS + HTTP)
gatewayTls=1 (solo cuando TLS está habilitado)
gatewayTlsSha256=<sha256> (solo cuando TLS está habilitado y la huella digital está disponible)
canvasPort=<puerto> (solo cuando el host canvas está habilitado; actualmente el mismo que gatewayPort)
sshPort=<puerto> (por defecto 22 cuando no se modifica)
transport=gateway
cliPath=<ruta> (opcional; ruta absoluta a un punto de entrada ejecutable openclaw)
tailnetDns=<magicdns> (indicación opcional cuando Tailnet está disponible)

Notas de seguridad:

Los registros TXT de Bonjour/mDNS son no autenticados. Los clientes no deben tratar los TXT como enrutamiento autoritativo.
Los clientes deben enrutar usando el endpoint de servicio resuelto (SRV + A/AAAA). Trata lanHost, tailnetDns, gatewayPort y gatewayTlsSha256 solo como indicaciones.
El pinning TLS nunca debe permitir que un gatewayTlsSha256 anunciado sobrescriba un pin previamente almacenado.
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 por primera vez.

Depuración en macOS

Herramientas integradas útiles:

Explorar instancias:
```
dns-sd -B _openclaw-gw._tcp local.
```

Resolver una instancia (reemplaza <instance>):

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

Si la exploración funciona pero la resolución falla, generalmente es un problema de política de LAN o del resolver mDNS.

Depuración en los logs del Gateway

El Gateway escribe un archivo de log rotativo (impreso al inicio como gateway log file: ...). Busca líneas bonjour:, especialmente:

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

Depuración en nodo iOS

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

Para capturar logs:

Ajustes → Gateway → Avanzado → Discovery Debug Logs
Ajustes → Gateway → Avanzado → Discovery Logs → reproducir → Copiar

El log incluye transiciones de estado del browser y cambios en el conjunto de resultados.

Modos de fallo comunes

Bonjour no cruza redes: usa Tailnet o SSH.
Multicast bloqueado: algunas redes Wi-Fi desactivan mDNS.
Suspensión / cambio de interfaz: macOS puede descartar temporalmente resultados mDNS; reintenta.
La exploración funciona pero la resolución falla: mantén los nombres de máquina simples (evita emojis o puntuación), luego reinicia el Gateway. El nombre de instancia del servicio deriva del nombre del host, así que nombres demasiado complejos pueden confundir algunos resolvers.

Nombres de instancia escapados (`\032`)

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

Esto es normal a nivel de protocolo.
Las UIs deben decodificar para mostrar (iOS usa BonjourEscapes.decode).

Desactivación / configuración

OPENCLAW_DISABLE_BONJOUR=1 desactiva el anuncio (legacy: OPENCLAW_DISABLE_BONJOUR).
gateway.bind en ~/.openclaw/openclaw.json controla el modo de enlace del Gateway.
OPENCLAW_SSH_PORT modifica el puerto SSH anunciado en TXT (legacy: OPENCLAW_SSH_PORT).
OPENCLAW_TAILNET_DNS publica una indicación MagicDNS en TXT (legacy: OPENCLAW_TAILNET_DNS).
OPENCLAW_CLI_PATH modifica la ruta CLI anunciada (legacy: OPENCLAW_CLI_PATH).

Documentación relacionada

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