OpenClaw Bonjour Discovery Explained

Bonjour discovery is the part of OpenClaw that tries to make gateway discovery feel almost automatic, especially on local networks. The docs are careful not to oversell it. It is a convenience layer built on mDNS and DNS-SD, with an optional wide-area DNS-SD story for Tailnet-style deployments.

What it is

At the simplest level, the gateway advertises an _openclaw-gw._tcp service so clients can find it. On a healthy LAN, that makes setup pleasantly easy. When the network is broader than one multicast domain, the docs allow the same discovery concept to be published through a configured wide-area DNS-SD domain.

How it works

The bundled bonjour plugin handles LAN advertising by default. Clients browse, resolve an endpoint, then connect through the normal gateway auth and transport surfaces. Discovery metadata is intentionally limited and non-secret.

• LAN multicast advertising is the default and works only as a same-network convenience layer.
• Wide-area DNS-SD over Tailscale preserves the same discovery feel across networks when multicast cannot cross the boundary.
• TXT fields such as host hints or TLS hints improve UX but are not authoritative routing data.
• In detected containers, Bonjour may auto-disable because Docker bridge networks often do not pass mDNS usefully.

Why operators care

Operators care because discovery problems often masquerade as pairing or transport problems. Knowing what Bonjour is responsible for and what it is not responsible for helps you choose the next debugging move correctly. It also keeps you from confusing a missing beacon with a broken gateway.

Boundaries that matter

Discovery does not authenticate the gateway, does not replace TLS, does not substitute for SSH, and does not promise cross-network success. The docs say all of that more politely, but that is the core. Bonjour is an onboarding and convenience feature, not your security model.

Rollout approach

For relying on Bonjour discovery without over-trusting it, keep the first pass small: one owner, one environment, one visible test, and one rollback path. OpenClaw features get powerful once they touch real chats or devices, so a short rehearsal is usually safer than a giant configuration sprint.

Common mistake

The common mistake is thinking “I discovered it” means “I can trust it.” The docs go out of their way to say otherwise, and that restraint is a good thing.

Maintenance rhythm

Write down the exact command, config path, auth assumption, and verification step you used. A short runbook note is cheaper than rediscovering the same behavior during an outage. If your environment changes from bare host to Docker, WSL, or another segmented network, revisit discovery assumptions before blaming the client.

Safety checks

Use discovery to reduce friction, then fall back to normal disciplined connectivity when discovery is absent. That mindset keeps Bonjour useful instead of fragile.

How to tell you understand it

You understand Bonjour discovery when you can explain why a node may browse successfully on LAN, fail across networks, and still be perfectly healthy once you switch to a secure direct route.

One operator-friendly test is to explain the feature without product fluff: what owns it, what permissions gate it, and which fallback keeps it predictable when the happy path disappears.

That framing matters because OpenClaw features usually look magical only from far away. Up close, the dependable ones have a clear owner, a bounded trust surface, and a boring recovery path when the network, model, device, or auth layer stops cooperating. If you can describe those three pieces from the docs, you usually understand the feature well enough to operate it without superstition.

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.