Descubrimiento de Bonjour

OpenClaw puede utilizar Bonjour (mDNS / DNS-SD) para descubrir un Gateway activo (extremo WebSocket). La navegación multidifusión local. es una comodidad solo para LAN. El complemento bonjour incluido se encarga de la publicidad en LAN. Se inicia automáticamente en hosts macOS y es opcional en las implementaciones de Gateway en Linux, Windows y contenedores. Para el descubrimiento entre redes, la misma baliza también se puede publicar a través de un dominio DNS-SD de área amplia configurado. El descubrimiento sigue siendo mejor esfuerzo y no reemplaza la conectividad basada en SSH o Tailnet.

Bonjour de área amplia (Unicast DNS-SD) a través de Tailscale

Si el nodo y el gateway están en diferentes redes, el mDNS multidifusión no cruzará el límite. Puede mantener la misma experiencia de usuario de descubrimiento cambiando a DNS-SD unidifusión (“Bonjour de área amplia”) a través de Tailscale.

Pasos de alto nivel:

Ejecute un servidor DNS en el host del gateway (accesible a través de Tailnet).
Publique registros DNS-SD para _openclaw-gw._tcp bajo una zona dedicada (ejemplo: openclaw.internal.).
Configure el 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 de Tailscale

En la consola de administración de Tailscale:

Agregue un servidor de nombres que apunte a la IP 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 aceptan el DNS de tailnet, los nodos iOS y el descubrimiento CLI pueden explorar _openclaw-gw._tcp en su dominio de descubrimiento sin multidifusión.

Seguridad del listener del Gateway (recomendado)

El puerto WS del Gateway (por defecto 18789) se vincula a loopback por defecto. Para el acceso a LAN/tailnet, vincúlelo explícitamente y mantenga la autenticación habilitada.

Para configuraciones exclusivas de tailnet:

Establezca gateway.bind: "tailnet" en ~/.openclaw/openclaw.json.
Reinicie el Gateway (o reinicie la aplicación de la barra de menús de macOS).

Qué se anuncia

Solo el Gateway anuncia _openclaw-gw._tcp. La publicidad de multidifusión LAN es proporcionada por el complemento incluido bonjour cuando el complemento está habilitado; la publicación de DNS-SD de área amplia sigue siendo propiedad del Gateway.

Tipos de servicio

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

Claves TXT (sugerencias no secretas)

El Gateway anuncia pequeñas sugerencias no secretas para facilitar los flujos de la interfaz de usuario:

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 digital está disponible)
canvasPort=<port> (solo cuando el host del lienzo está habilitado; actualmente es el mismo que gatewayPort)
transport=gateway
tailnetDns=<magicdns> (solo modo mDNS completo, sugerencia opcional cuando Tailnet está disponible)
sshPort=<port> (solo modo completo; omitido en modos mínimo y desactivado)
cliPath=<path> (solo modo completo; omitido en modos mínimo y desactivado)

Notas de seguridad:

Los registros TXT de Bonjour/mDNS son sin autenticar. Los clientes no deben tratar TXT como un enrutamiento autoritativo.
Los clientes deben enrutar utilizando el punto final del servicio resuelto (SRV + A/AAAA). Trate lanHost, tailnetDns, gatewayPort y gatewayTlsSha256 solo como sugerencias.
El autodireccionamiento SSH también debe usar el host de servicio resuelto, no sugerencias solo de TXT.
El anclaje de TLS nunca debe permitir que un gatewayTlsSha256 anunciado anule un anclaje 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 por primera vez.

Depuración en macOS

Herramientas integradas útiles:

Explorar instancias:
Ventana de terminal
```
dns-sd -B _openclaw-gw._tcp local.
```
Resolver una instancia (reemplace <instance>):
Ventana de terminal
```
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```

Si la navegación funciona pero la resolución falla, generalmente se trata de una política de LAN o un problema con el solucionador mDNS.

Depuración en los registros del Gateway

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

bonjour: advertise failed ...
bonjour: suppressing ciao cancellation ...
bonjour: ... name conflict resolved / hostname conflict resolved
bonjour: watchdog detected non-announced service ...
bonjour: disabling advertiser after ... failed restarts ...

El perro guardián trata los estados probing, announcing y los cambios de nombre por conflictos recientes como estados en curso. Si el servicio nunca llega a announced, OpenClaw eventualmente recrea el anunciante y, tras fallos repetidos, deshabilita Bonjour para ese proceso de Gateway en lugar de anunciar infinitamente.

Bonjour usa el nombre de host del sistema para el host .local anunciado cuando es una etiqueta DNS válida. Si el nombre de host del sistema contiene espacios, guiones bajos u otro carácter no válido para etiquetas DNS, OpenClaw recurre a openclaw.local. Establezca OPENCLAW_MDNS_HOSTNAME=<name> antes de iniciar el Gateway cuando necesite una etiqueta de host explícita.

Depuración en el nodo iOS

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

Para capturar registros:

Ajustes → Gateway → Avanzado → Registros de depuración de descubrimiento
Ajustes → Gateway → Avanzado → Registros de descubrimiento → reproducir → Copiar

El registro incluye las transiciones de estado del navegador y los cambios en el conjunto de resultados.

Cuándo habilitar Bonjour

Bonjour se inicia automáticamente al iniciar el Gateway con configuración vacía en hosts macOS, ya que la aplicación local y los nodos cercanos de iOS/Android suelen depender del descubrimiento en la misma LAN.

Habilite Bonjour explícitamente cuando el autodescubrimiento en la misma LAN sea útil en Linux, Windows u otro host que no sea macOS:

openclaw plugins enable bonjour

Cuando está activado, Bonjour usa discovery.mdns.mode para decidir cuántos metadatos TXT publicar. El mismo modo controla las pistas TXT opcionales en los registros DNS-SD de área amplia. El modo predeterminado es minimal; use full solo cuando los clientes necesiten pistas cliPath o sshPort. Use off para suprimir el multicast de LAN sin cambiar la activación complementaria; el DNS-SD de área amplia aún puede publicar la baliza mínima de Gateway cuando discovery.wideArea.enabled es verdadero.

Cuándo deshabilitar Bonjour

Deje Bonjour deshabilitado cuando la publicidad multicast de LAN sea innecesaria, no disponible o dañina. Los casos comunes son servidores que no son macOS, redes de puente Docker, WSL, o una política de red que descarta el multicast mDNS. En esos entornos, el Gateway sigue siendo accesible a través de su URL publicada, SSH, Tailnet o DNS-SD de área amplia, pero el autodescubrimiento de LAN no es confiable.

Prefiera la anulación de entorno existente cuando el problema esté limitado al despliegue:

OPENCLAW_DISABLE_BONJOUR=1

Eso deshabilita la publicidad multidifusión de LAN sin cambiar la configuración del complemento. Es seguro para imágenes de Docker, archivos de servicio, scripts de inicio y depuración de un solo uso porque la configuración desaparece cuando lo hace el entorno.

Use la configuración del complemento cuando intencionalmente desee desactivar el complemento de descubrimiento de LAN incluido para esa configuración de OpenClaw:

openclaw plugins disable bonjour

Problemas de Docker

El complemento Bonjour incluido desactiva automáticamente la publicidad por multicast de LAN en los contenedores detectados cuando OPENCLAW_DISABLE_BONJOUR no está establecido. Las redes puente de Docker generalmente no reenvían el multicast mDNS (224.0.0.251:5353) entre el contenedor y la LAN, por lo que la publicidad desde el contenedor rara vez hace que el descubrimiento funcione.

Problemas importantes:

Bonjour se inicia automáticamente en los hosts de macOS y es opcional en otros lugares. Dejarlo deshabilitado no detiene el Gateway; solo omite la publicidad multidifusión de LAN.
Desactivar Bonjour no cambia gateway.bind; Docker aún usa por defecto OPENCLAW_GATEWAY_BIND=lan para que el puerto host publicado pueda funcionar.
Deshabilitar Bonjour no deshabilita DNS-SD de área amplia. Use el descubrimiento de área amplia o Tailnet cuando el Gateway y el nodo no estén en la misma LAN.
Reutilizar el mismo OPENCLAW_CONFIG_DIR fuera de Docker no persiste la política de desactivación automática del contenedor.
Establezca OPENCLAW_DISABLE_BONJOUR=0 solo para redes de host, macvlan u otra red donde se sepa que pasa el multicast mDNS; establézcalo en 1 para forzar la desactivación.

Solución de problemas de Bonjour deshabilitado

Si un nodo ya no descubre automáticamente el Gateway después de la configuración de Docker:

Confirme si el Gateway se está ejecutando en modo automático, forzado activado o forzado desactivado:
Ventana de terminal
```
docker compose config | grep OPENCLAW_DISABLE_BONJOUR
```
Confirme que el propio Gateway sea accesible a través del puerto publicado:
Ventana de terminal
```
curl -fsS http://127.0.0.1:18789/healthz
```
Use un objetivo directo cuando Bonjour esté deshabilitado:
- Interfaz de usuario de control o herramientas locales: http://127.0.0.1:18789
- Clientes de LAN: http://<gateway-host>:18789
- Clientes entre redes: MagicDNS de Tailnet, IP de Tailnet, túnel SSH o DNS-SD de área amplia
Si activó deliberadamente el complemento Bonjour en Docker y forzó la publicidad con OPENCLAW_DISABLE_BONJOUR=0, pruebe el multicast desde el host:
Ventana de terminal
```
dns-sd -B _openclaw-gw._tcp local.
```
Si la exploración está vacía o los registros de Gateway muestran cancelaciones repetidas del perro guardián ciao, restaure OPENCLAW_DISABLE_BONJOUR=1 y use una ruta directa o de Tailnet.

Modos de falla comunes

Bonjour no cruza redes: usa Tailnet o SSH.
Multicast bloqueado: algunas redes Wi-Fi deshabilitan mDNS.
El anunciador atascado en sondeo/anuncio: los hosts con multicast bloqueado, puentes de contenedores, WSL, o cambios en la interfaz pueden dejar al anunciador ciao en un estado de no anuncio. OpenClaw reintent unas pocas veces y luego deshabilita Bonjour para el proceso Gateway actual en lugar de reiniciar el anunciador para siempre.
Redes puente de Docker: Bonjour se desactiva automáticamente en los contenedores detectados. Establezca OPENCLAW_DISABLE_BONJOUR=0 solo para host, macvlan u otra red compatible con mDNS.
Suspensi / cambios de interfaz: macOS puede descartar temporalmente resultados mDNS; reintentar.
La exploracin funciona pero la resolucin falla: mantn los nombres de mquina simples (evita emojis o puntuacin), luego reinicia el Gateway. El nombre de la instancia del servicio deriva del nombre del host, por lo que nombres demasiado complejos pueden confundir a algunos resolvedores.

Nombres de instancia con escape (`\032`)

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

Esto es normal a nivel de protocolo.
Las interfaces de usuario deben decodificar para su visualización (iOS usa BonjourEscapes.decode).

Habilitar / deshabilitar / configuracin

Los hosts macOS inician automticamente el complemento de descubrimiento LAN incluido por defecto.
openclaw plugins enable bonjour habilita el complemento de descubrimiento de LAN incluido en los hosts donde no está habilitado de forma predeterminada.
openclaw plugins disable bonjour deshabilita la publicidad multidifusión de LAN al deshabilitar el complemento incluido.
OPENCLAW_DISABLE_BONJOUR=1 deshabilita la publicidad multidifusión de LAN sin cambiar la configuración del complemento; los valores verdaderos aceptados son 1, true, yes y on (legado: OPENCLAW_DISABLE_BONJOUR).
OPENCLAW_DISABLE_BONJOUR=0 fuerza la activación de la publicidad multidifusión de LAN, incluso dentro de contenedores detectados; los valores falsos aceptados son 0, false, no y off.
Cuando el complemento Bonjour está habilitado y OPENCLAW_DISABLE_BONJOUR no está configurado, Bonjour anuncia en hosts normales y se deshabilita automáticamente dentro de contenedores detectados.
gateway.bind en ~/.openclaw/openclaw.json controla el modo de enlace del Gateway.
OPENCLAW_SSH_PORT anula el puerto SSH cuando se anuncia sshPort (legado: OPENCLAW_SSH_PORT).
OPENCLAW_TAILNET_DNS publica una pista de MagicDNS en TXT cuando el modo completo mDNS está habilitado (legado: OPENCLAW_TAILNET_DNS).
OPENCLAW_CLI_PATH anula la ruta CLI anunciada (legado: OPENCLAW_CLI_PATH).

Documentos relacionados

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