Bonjour Discovery

OpenClaw uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or Tailnet-based connectivity.

If the node and gateway are on different networks, multicast mDNS won't cross the boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD** ("Wide‑Area Bonjour") over Tailscale.

High-level steps:

1. Run a DNS server on the gateway host (reachable over Tailnet).
2. Publish DNS-SD records for _openclaw-gw._tcp under a dedicated zone (example: openclaw.internal.).
3. Configure Tailscale **split DNS** so your chosen domain resolves via that DNS server for clients (including iOS).

OpenClaw supports any discovery domain; openclaw.internal. is just an example.

iOS/Android nodes browse both local. and your configured wide‑area domain.

openclaw dns setup --apply

This installs CoreDNS and configures it to:

• listen on port 53 only on the gateway's Tailscale interfaces
• ~/.openclaw/dns/<domain>.db to serve a chosen domain (e.g., openclaw.internal.)

Validate from a tailnet‑connected machine:

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

In the Tailscale admin console:

• Add a nameserver pointing at the gateway's tailnet IP (UDP/TCP 53).
• Add split DNS so your discovery domain uses that nameserver.

Once clients accept tailnet DNS, iOS nodes can browse _openclaw-gw._tcp in your discovery domain without multicast.

The Gateway WS port (default 18789) binds to loopback by default. For LAN/tailnet access, bind explicitly and keep auth enabled.

For tailnet-only setups:

• Set gateway.bind: "tailnet" in ~/.openclaw/openclaw.json.
• Restart the Gateway (or restart the macOS menubar app).

Only the Gateway advertises _openclaw-gw._tcp.

• _openclaw-gw._tcp — gateway transport beacon (used by macOS/iOS/Android nodes).

The Gateway advertises small non‑secret hints to make UI flows convenient:

• role=gateway
• <code>displayName=<friendly name>'</code>
• <code>lanHost=<hostname>.local</code>
• <code>gatewayPort=<port>'</code> (Gateway WS + HTTP)
• gatewayTls=1 (only when TLS is enabled)
• <code>gatewayTlsSha256=<sha256>'</code> (only when TLS is enabled and fingerprint is available)
• <code>canvasPort=<port>'</code> (only when the canvas host is enabled; default <code>18793</code>)
• <code>sshPort=<port>'</code> (defaults to 22 when not overridden)
• transport=gateway
• <code>cliPath=<path>'</code> (optional; absolute path to a runnable <code>openclaw</code> entrypoint)
• <code>tailnetDns=<magicdns>'</code> (optional hint when Tailnet is available)

Useful built-in tools:

Browse instances:

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

Resolve an instance (replace <instance>):

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

If browsing works but resolving fails, you're usually hitting a LAN policy or mDNS resolver issue.

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 ...

The iOS node uses NWBrowser to discover _openclaw-gw._tcp.

To capture logs:

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

The log includes browser state transitions and result-set changes.

• 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.

Bonjour/DNS-SD often escapes bytes in service instance names as decimal \DDD sequences (e.g. spaces become \032).

• This is normal at the protocol level.
• UIs should decode for display (iOS uses BonjourEscapes.decode).

• OPENCLAW_DISABLE_BONJOUR=1 disables advertising.
• gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
• OPENCLAW_SSH_PORT overrides the SSH port advertised in TXT.
• OPENCLAW_TAILNET_DNS publishes a MagicDNS hint in TXT.
• OPENCLAW_CLI_PATH overrides the advertised CLI path.

• Discovery policy and transport selection: [Discovery](/gateway/discovery)
• Node pairing + approvals: [Gateway pairing](/gateway/pairing)