> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Descoberta Bonjour

# Descoberta Bonjour / mDNS

O OpenClaw usa Bonjour (mDNS / DNS‑SD) como uma **conveniência apenas para LAN** para descobrir
um Gateway ativo (endpoint WebSocket). É de melhor esforço e **não** substitui SSH nem
conectividade baseada em Tailnet.

## Bonjour de área ampla (DNS‑SD unicast) sobre Tailscale

Se o nó e o gateway estiverem em redes diferentes, o mDNS multicast não atravessa a
fronteira. Você pode manter a mesma UX de descoberta mudando para **DNS‑SD unicast**
("Bonjour de Área Ampla") sobre o Tailscale.

Passos em alto nível:

1. Execute um servidor DNS no host do gateway (acessível pela Tailnet).
2. Publique registros DNS‑SD para `_openclaw-gw._tcp` sob uma zona dedicada
   (exemplo: `openclaw.internal.`).
3. Configure **DNS dividido** do Tailscale para que o domínio escolhido resolva por esse
   servidor DNS para os clientes (incluindo iOS).

O OpenClaw oferece suporte a qualquer domínio de descoberta; `openclaw.internal.` é apenas um exemplo.
Nós iOS/Android navegam tanto por `local.` quanto pelo domínio de área ampla configurado.

### Configuração do Gateway (recomendado)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}
```

### Configuração única do servidor DNS (host do gateway)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw dns setup --apply
```

Isso instala o CoreDNS e o configura para:

* escutar na porta 53 apenas nas interfaces Tailscale do gateway
* servir o domínio escolhido (exemplo: `openclaw.internal.`) a partir de `~/.openclaw/dns/<domain>.db`

Valide a partir de uma máquina conectada à tailnet:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
```

### Configurações de DNS do Tailscale

No console de administração do Tailscale:

* Adicione um servidor de nomes apontando para o IP da tailnet do gateway (UDP/TCP 53).
* Adicione DNS dividido para que o domínio de descoberta use esse servidor de nomes.

Depois que os clientes aceitarem o DNS da tailnet, nós iOS podem navegar por
`_openclaw-gw._tcp` no seu domínio de descoberta sem multicast.

### Segurança do listener do Gateway (recomendado)

A porta WS do Gateway (padrão `18789`) vincula-se ao loopback por padrão. Para acesso
LAN/tailnet, faça o bind explicitamente e mantenha a autenticação habilitada.

Para configurações somente de tailnet:

* Defina `gateway.bind: "tailnet"` em `~/.openclaw/openclaw.json`.
* Reinicie o Gateway (ou reinicie o app de menubar do macOS).

## O que anuncia

Apenas o Gateway anuncia `_openclaw-gw._tcp`.

## Tipos de serviço

* `_openclaw-gw._tcp` — beacon de transporte do gateway (usado por nós macOS/iOS/Android).

## Chaves TXT (dicas não secretas)

O Gateway anuncia pequenas dicas não secretas para tornar os fluxos de UI convenientes:

* `role=gateway`
* `displayName=<friendly name>`
* `lanHost=<hostname>.local`
* `gatewayPort=<port>` (Gateway WS + HTTP)
* `gatewayTls=1` (apenas quando TLS está habilitado)
* `gatewayTlsSha256=<sha256>` (apenas quando TLS está habilitado e a impressão digital está disponível)
* `canvasPort=<port>` (apenas quando o host do canvas está habilitado; padrão `18793`)
* `sshPort=<port>` (padrão 22 quando não sobrescrito)
* `transport=gateway`
* `cliPath=<path>` (opcional; caminho absoluto para um entrypoint executável `openclaw`)
* `tailnetDns=<magicdns>` (dica opcional quando a Tailnet está disponível)

Notas de segurança:

* Registros TXT do Bonjour/mDNS são **não autenticados**. Os clientes não devem tratar o TXT como roteamento autoritativo.
* Os clientes devem rotear usando o endpoint de serviço resolvido (SRV + A/AAAA). Trate `lanHost`, `tailnetDns`, `gatewayPort` e `gatewayTlsSha256` apenas como sugestões.
* O TLS pinning nunca deve permitir que um `gatewayTlsSha256` anunciado substitua um pin previamente armazenado.
* Nós iOS/Android devem tratar conexões diretas baseadas em descoberta como **somente TLS** e exigir confirmação explícita do usuário antes de confiar em uma impressão digital vista pela primeira vez.

## Depuração no macOS

Ferramentas internas úteis:

* Procurar instâncias:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  dns-sd -B _openclaw-gw._tcp local.
  ```

* Resolver uma instância (substitua `<instance>`):

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  dns-sd -L "<instance>" _openclaw-gw._tcp local.
  ```

Se a navegação funciona mas a resolução falha, geralmente você está esbarrando em uma
política de LAN ou em um problema do resolvedor mDNS.

## Depuração nos logs do Gateway

O Gateway grava um arquivo de log rotativo (impresso na inicialização como
`gateway log file: ...`). Procure por linhas `bonjour:`, especialmente:

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

## Depuração no nó iOS

O nó iOS usa `NWBrowser` para descobrir `_openclaw-gw._tcp`.

Para capturar logs:

* Ajustes → Gateway → Avançado → **Logs de depuração de descoberta**
* Ajustes → Gateway → Avançado → **Logs de descoberta** → reproduzir → **Copiar**

O log inclui transições de estado do navegador e alterações no conjunto de resultados.

## Modos de falha comuns

* **Bonjour não cruza redes**: use Tailnet ou SSH.
* **Multicast bloqueado**: algumas redes Wi‑Fi desativam mDNS.
* **Suspensão / troca de interfaces**: o macOS pode derrubar temporariamente resultados mDNS; tente novamente.
* **Navegar funciona mas resolver falha**: mantenha nomes de máquina simples (evite emojis ou
  pontuação) e reinicie o Gateway. O nome da instância do serviço deriva do nome do host, então
  nomes excessivamente complexos podem confundir alguns resolvedores.

## Nomes de instância escapados (`\032`)

O Bonjour/DNS‑SD frequentemente escapa bytes em nomes de instância de serviço como sequências
decimais `\DDD` (por exemplo, espaços viram `\032`).

* Isso é normal no nível do protocolo.
* UIs devem decodificar para exibição (o iOS usa `BonjourEscapes.decode`).

## Desativação / configuração

* `OPENCLAW_DISABLE_BONJOUR=1` desativa a divulgação (legado: `OPENCLAW_DISABLE_BONJOUR`).
* `gateway.bind` em `~/.openclaw/openclaw.json` controla o modo de bind do Gateway.
* `OPENCLAW_SSH_PORT` sobrescreve a porta SSH anunciada no TXT (legado: `OPENCLAW_SSH_PORT`).
* `OPENCLAW_TAILNET_DNS` publica uma dica de MagicDNS no TXT (legado: `OPENCLAW_TAILNET_DNS`).
* `OPENCLAW_CLI_PATH` sobrescreve o caminho da CLI anunciada (legado: `OPENCLAW_CLI_PATH`).

## Documentos relacionados

* Política de descoberta e seleção de transporte: [Discovery](/gateway/discovery)
* Pareamento de nós + aprovações: [Gateway pairing](/gateway/pairing)