Skip to main content
O OpenClaw pode usar o Bonjour (mDNS/DNS-SD) para descobrir um gateway ativo (endpoint WebSocket). A busca multicast local. é uma conveniência exclusiva da LAN: o Plugin bonjour incluído é responsável pela publicidade na LAN, iniciando automaticamente em hosts macOS e sendo opcional no Linux, Windows e em implantações de gateway em contêineres. O mesmo beacon também pode ser publicado por meio de um domínio DNS-SD de longa distância configurado para descoberta entre redes. A descoberta funciona em regime de melhor esforço e não substitui a conectividade baseada em SSH ou Tailnet.

​
Bonjour de longa distância (DNS-SD unicast) pelo Tailscale

Se o Node e o gateway estiverem em redes diferentes, o mDNS multicast não poderá atravessar o limite entre elas. Mantenha a mesma experiência de descoberta alternando para DNS-SD unicast (“Bonjour de longa distância”) pelo Tailscale:
  1. Execute um servidor DNS no host do gateway, acessível pela Tailnet.
  2. Publique registros DNS-SD para _openclaw-gw._tcp em uma zona dedicada (exemplo: openclaw.internal.).
  3. Configure o DNS dividido do Tailscale para que o domínio escolhido seja resolvido por esse servidor DNS para os clientes, incluindo o iOS.
O openclaw.internal. acima é apenas um exemplo — o OpenClaw aceita qualquer domínio de descoberta. Os Nodes iOS/Android buscam tanto em local. quanto no domínio de longa distância configurado.

​
Configuração do Gateway

discovery.wideArea.domain também aceita a variável de ambiente OPENCLAW_WIDE_AREA_DOMAIN como alternativa quando não está definido.

​
Configuração única do servidor DNS (host do gateway, somente macOS)

Esse comando é exclusivo do macOS e requer o Homebrew e uma conexão ativa com o Tailscale. Ele instala o CoreDNS (brew install coredns) e o configura para:
  • escutar na porta 53 somente nas interfaces Tailscale do gateway
  • servir o domínio escolhido (exemplo: openclaw.internal.) a partir de ~/.openclaw/dns/<domain>.db
Primeiro, execute sem --apply para visualizar o plano (domínio, caminho do arquivo de zona, IP da Tailnet detectado e configuração recomendada) sem instalar nada. Valide em uma máquina conectada à Tailnet:

​
Configurações de DNS do Tailscale

No console de administração do Tailscale:
  • Adicione um servidor de nomes que aponte para o IP da Tailnet do gateway (UDP/TCP 53).
  • Adicione o DNS dividido para que seu domínio de descoberta use esse servidor de nomes.
Depois que os clientes aceitarem o DNS da Tailnet, os Nodes iOS e a descoberta pela CLI poderão buscar _openclaw-gw._tcp no domínio de descoberta sem multicast.

​
Segurança do listener do Gateway

Por padrão, a porta WS do gateway (18789) é vinculada à interface de loopback. Para acesso por LAN/Tailnet, configure explicitamente o vínculo e mantenha a autenticação ativada. Para configurações exclusivas da Tailnet, defina gateway.bind: "tailnet" em ~/.openclaw/openclaw.json e reinicie o gateway (ou o aplicativo da barra de menus do macOS).

​
O que é anunciado

Somente o gateway anuncia _openclaw-gw._tcp. A publicidade multicast na LAN vem do Plugin bonjour incluído quando ele está ativado; a publicação de DNS-SD de longa distância continua sob responsabilidade do gateway.

​
Tipos de serviço

  • _openclaw-gw._tcp - beacon de transporte do gateway, usado pelos Nodes macOS/iOS/Android.

​
Chaves TXT (dicas não confidenciais)

Observações de segurança:
  • Os registros TXT do Bonjour/mDNS não são autenticados. Os clientes não devem tratar os dados TXT como roteamento autoritativo.
  • Os clientes devem fazer o roteamento usando o endpoint de serviço resolvido (SRV + A/AAAA). Trate lanHost, tailnetDns, gatewayPort e gatewayTlsSha256 apenas como dicas.
  • O direcionamento automático por SSH também deve usar o host de serviço resolvido, não dicas somente de TXT.
  • A fixação de TLS nunca deve permitir que um gatewayTlsSha256 anunciado substitua uma fixação armazenada anteriormente.
  • Os Nodes iOS/Android devem tratar conexões diretas baseadas em descoberta como exclusivas de TLS e exigir confirmação explícita do usuário antes de confiar em uma impressão digital pela primeira vez.

​
Depuração no macOS

Ferramentas integradas:
Se a busca funcionar, mas a resolução falhar, geralmente o problema está em uma política da LAN ou no resolvedor mDNS.

​
Depuração nos logs do Gateway

O gateway grava um arquivo de log rotativo (exibido na inicialização como gateway log file: ...). Procure linhas com bonjour:, especialmente:
  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
O OpenClaw inicia cada serviço Bonjour uma vez e deixa a sondagem, as novas tentativas, a resolução de conflitos de nome e a republicação após mudanças de interface a cargo do respondente mDNS. Isso evita tentativas de publicação sobrepostas durante alterações normais da rede. Mensagens internas repetidas de autossondagem são suprimidas para impedir que inundem o log do gateway. Quando vários gateways OpenClaw anunciam a partir do mesmo host, o Bonjour pode acrescentar sufixos como (2) ou (3) para manter os nomes das instâncias de serviço exclusivos. Esses sufixos são parte normal da resolução de conflitos e não indicam supervisão OCM duplicada. O Bonjour usa o nome de host do sistema para o host .local anunciado quando ele é um rótulo DNS válido. Se o nome de host do sistema contiver espaços, sublinhados ou outro caractere inválido para rótulos DNS, o OpenClaw usará openclaw.local como alternativa. Defina OPENCLAW_MDNS_HOSTNAME=<name> antes de iniciar o gateway quando precisar de um rótulo de host explícito.

​
Depuração no Node iOS

O Node iOS usa NWBrowser para descobrir _openclaw-gw._tcp. Para capturar logs: Settings -> Gateway -> Advanced -> Discovery Debug Logs e, em seguida, Settings -> Gateway -> Advanced -> Discovery Logs -> reproduza o problema -> Copy. O log inclui transições de estado do navegador e alterações no conjunto de resultados.

​
Quando ativar o Bonjour

O Bonjour inicia automaticamente quando o gateway é iniciado com uma configuração vazia em hosts macOS, pois o aplicativo local e os Nodes iOS/Android próximos normalmente dependem da descoberta na mesma LAN. Ative-o explicitamente quando a descoberta automática na mesma LAN for útil no Linux, Windows ou em outro host que não seja macOS:
Quando ativado, o Bonjour usa discovery.mdns.mode para decidir quantos metadados TXT publicar; o mesmo modo controla dicas TXT opcionais nos registros DNS-SD de longa distância. Modos:

​
Quando desativar o Bonjour

Mantenha o Bonjour desativado quando a publicidade multicast na LAN for desnecessária, indisponível ou prejudicial — casos comuns incluem servidores que não sejam macOS, redes bridge do Docker, WSL ou uma política de rede que descarte multicast mDNS. O gateway continua acessível pela URL publicada, por SSH, Tailnet ou DNS-SD de longa distância; somente a descoberta automática na LAN fica indisponível. Use a substituição por variável de ambiente para problemas específicos da implantação (é segura para imagens do Docker, arquivos de serviço, scripts de inicialização e depuração pontual — ela desaparece quando o ambiente deixa de existir):
Use a configuração do Plugin quando quiser desativar intencionalmente o Plugin de descoberta na LAN incluído nessa configuração do OpenClaw:

​
Armadilhas do Docker

O Plugin Bonjour incluído desativa automaticamente a publicidade multicast na LAN em contêineres detectados quando OPENCLAW_DISABLE_BONJOUR não está definido. Em geral, as redes bridge do Docker não encaminham multicast mDNS (224.0.0.251:5353) entre o contêiner e a LAN, portanto anunciar a partir do contêiner raramente faz a descoberta funcionar. Armadilhas:
  • O Bonjour inicia automaticamente em hosts macOS e é opcional nos demais. Mantê-lo desativado não interrompe o gateway — apenas ignora a publicidade multicast na LAN.
  • Desativar o Bonjour não altera gateway.bind; o Docker continua usando OPENCLAW_GATEWAY_BIND=lan por padrão para que a porta publicada do host funcione.
  • Desativar o Bonjour não desativa o DNS-SD de longa distância. Use a descoberta de longa distância ou a Tailnet quando o gateway e o Node não estiverem na mesma LAN.
  • Reutilizar o mesmo OPENCLAW_CONFIG_DIR fora do Docker não mantém a política de desativação automática do contêiner.
  • Defina OPENCLAW_DISABLE_BONJOUR=0 somente para redes do host, macvlan ou outra rede na qual se saiba que o multicast mDNS passa; defina-o como 1 para forçar a desativação.

​
Solução de problemas com o Bonjour desativado

Se um Node deixar de descobrir automaticamente o gateway após a configuração do Docker:
  1. Confirme se o gateway está em modo automático, forçadamente ativado ou forçadamente desativado:
  2. Confirme se o próprio gateway está acessível pela porta publicada:
  3. Use um destino direto quando o Bonjour estiver desativado:
    • UI de controle ou ferramentas locais: http://127.0.0.1:18789
    • Clientes da LAN: http://<gateway-host>:18789
    • Clientes entre redes: MagicDNS da Tailnet, IP da Tailnet, túnel SSH ou DNS-SD de longa distância
  4. Se o Plugin Bonjour tiver sido ativado intencionalmente no Docker e a publicidade tiver sido forçada com OPENCLAW_DISABLE_BONJOUR=0, teste o multicast a partir do host:
    Se a busca não retornar resultados ou se os logs do Gateway mostrarem falhas repetidas de sondagem do ciao, restaure OPENCLAW_DISABLE_BONJOUR=1 e use uma rota direta ou pela Tailnet.

​
Modos de falha comuns

  • O Bonjour não atravessa redes: use Tailnet ou SSH.
  • Multicast bloqueado: algumas redes Wi-Fi desativam o mDNS.
  • Anunciante travado em sondagem/anúncio: hosts com multicast bloqueado, bridges de contêineres, WSL ou mudanças frequentes de interface podem deixar o respondente em um estado não anunciado. O Gateway permanece disponível por rotas diretas, SSH, Tailnet ou DNS-SD de longa distância; desative o Bonjour da LAN com discovery.mdns.mode: "off" ou OPENCLAW_DISABLE_BONJOUR=1 quando o multicast não estiver disponível.
  • Rede bridge do Docker: o Bonjour é desativado automaticamente nos contêineres detectados. Defina OPENCLAW_DISABLE_BONJOUR=0 apenas para host, macvlan ou outra rede compatível com mDNS.
  • Suspensão/mudanças frequentes de interface: o macOS pode interromper temporariamente os resultados de mDNS; tente novamente.
  • A busca funciona, mas a resolução falha: mantenha os nomes das máquinas simples (evite emojis ou pontuação) e reinicie o Gateway. O nome da instância de serviço é derivado do nome do host, portanto nomes excessivamente complexos podem confundir alguns resolvedores.

​
Nomes de instâncias com escape (\032)

O Bonjour/DNS-SD frequentemente aplica escape aos bytes nos nomes das instâncias de serviço como sequências decimais \DDD (espaços se tornam \032). Isso é normal no nível do protocolo; as interfaces devem decodificá-las para exibição (o iOS usa BonjourEscapes.decode).

​
Ativação / desativação / configuração

Por padrão, os hosts macOS iniciam automaticamente o Plugin integrado de descoberta de LAN. Quando o Plugin Bonjour está ativado e OPENCLAW_DISABLE_BONJOUR não está definido, o Bonjour anuncia em hosts normais e é desativado automaticamente dentro dos contêineres detectados (Docker, máquinas Fly.io e ambientes de execução de contêineres comuns).

​
Documentação relacionada