How to Use OpenClaw Bonjour Discovery

Bonjour discovery is best thought of as a convenience layer, not a trust layer. When it is working, nodes and apps discover the gateway with almost no friction. When it is not, the docs give you a very sane fallback story: use direct URLs, SSH, Tailnet, or wide-area DNS-SD instead of fighting multicast forever.

When this is the right move

Use Bonjour on the same LAN when you want zero-friction gateway discovery for macOS, iOS, or Android nodes. Reach for wide-area DNS-SD when the node and gateway sit on different networks but still share a Tailnet. Disable or bypass Bonjour when Docker, WSL, or network policy makes multicast unreliable.

The practical workflow

A good discovery workflow keeps the mental model simple: verify local browse first, then widen the route only if the network genuinely requires it.

1. Browse the local discovery domain first so you know whether mDNS is basically healthy before changing anything else.
2. If you need cross-network discovery, use the documented wide-area DNS-SD approach over Tailscale instead of assuming multicast will cross boundaries.
3. Keep gateway binding explicit. The docs recommend tailnet-only binding for tailnet setups rather than vague mixed exposure.
4. In Docker or WSL, assume multicast may be the problem and consider direct routes or forced Bonjour disablement instead of endless retries.
5. Treat the discovered result as a hinting mechanism, then connect with normal auth and, where appropriate, TLS or SSH.

Grounded command or config pattern

These are the small commands and toggles worth remembering from the docs. They are enough to distinguish “discovery is broken” from “the gateway itself is broken.”

dns-sd -B _openclaw-gw._tcp local.
openclaw gateway discover --json
openclaw dns setup --apply
OPENCLAW_DISABLE_BONJOUR=1

The first two help you see what is being advertised. The DNS setup command supports wide-area discovery, and the environment override is the safest quick way to disable LAN multicast advertising for a deployment without editing plugin config.

Operator notes

The security note in the docs matters a lot: TXT values are unauthenticated hints. That means values like lanHost, tailnetDns, or gatewayTlsSha256 are there to improve UX, not to replace real endpoint resolution or trust decisions. This is exactly the right posture for discovery metadata.

Rollout approach

For using OpenClaw Bonjour discovery in a real network, start with one owner, one environment, and one reversible test. Prove the docs-grounded path works before you widen the blast radius.

Common mistake

The common mistake is treating discovery as a guarantee instead of a best-effort layer. When multicast is blocked, operators often keep poking the advertiser instead of switching to a route the docs already recommend, such as Tailnet or an explicit gateway URL.

Maintenance rhythm

Record the command, config path, auth assumption, and verification step in your runbook. For discovery-heavy setups, note whether the environment is normal host networking, Tailnet, Docker bridge, or something stranger. That one fact explains a lot of future behavior.

Safety checks

Do not expose the gateway just because discovery feels inconvenient. Discovery and access control are separate jobs. Keep auth on, prefer loopback plus SSH or Tailnet when possible, and remember that discovered hostnames are there to help you connect safely, not to lower your standards.

How to verify it worked

You are done when browsing returns the expected service, resolution points at the host you actually intended, and the subsequent authenticated connection succeeds. If local browse works but remote nodes still fail, that is your hint to inspect the transport route rather than Bonjour itself.

If verification feels ambiguous, stop there and tighten the setup before you automate more. A small clean proof beats a large confusing rollout.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.