Setting Up Bonjour and mDNS Discovery in OpenClaw

I have spent too much time manually typing IP addresses just to get two devices on the same network to talk to each other. It is a common frustration: you know the service is running, but your client just can’t find it. Local discovery should feel automatic.

In OpenClaw, we use Bonjour (mDNS / DNS-SD) to handle this. It is a LAN-only convenience that helps your nodes find an active Gateway without you needing to hunt for WebSocket endpoints. It is best-effort, meaning it does not replace your SSH or Tailscale setup, but it makes the daily connection much smoother.

What You’ll Need

• An active OpenClaw Gateway.
• A Tailscale account (if you need discovery across different networks).
• A machine running macOS, iOS, or Android to act as a node.

Quick Start

If you are on the same physical LAN, Bonjour usually just works. If you want to use discovery over a Tailnet where multicast mDNS cannot reach, follow these steps to set up Wide-Area Bonjour.

1. Configure the Gateway

Edit your ~/.openclaw/openclaw.json to enable wide-area publishing and bind to your Tailnet.

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

2. Set Up the DNS Server

Run the following command on your gateway host to install and configure CoreDNS.

openclaw dns setup --apply

This sets up a server listening on port 53 of your Tailscale interface. It serves a domain like openclaw.internal. using records stored in ~/.openclaw/dns/.

3. Update Tailscale Settings

Go to your Tailscale admin console and perform these two actions:

• Add a nameserver pointing to your gateway host’s Tailnet IP (UDP/TCP 53).
• Enable Split DNS for your chosen discovery domain (e.g., openclaw.internal.).

4. Verify the Connection

You can check if the records are visible from another machine on your Tailnet:

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

Troubleshooting

Sometimes discovery fails even when the service is running. Here are the common issues I see:

• Bonjour doesn’t cross networks: mDNS is for local segments. If you are not on the same LAN, you must use the Tailscale method described above or stick to SSH.
• Multicast is blocked: Some public or corporate Wi-Fi networks disable mDNS entirely.
• Browse works but resolve fails: This often happens if your machine name has emojis or complex punctuation. Try simplifying your hostname and restarting the Gateway.
• Interface churn: On macOS, results might drop temporarily when the machine wakes from sleep. Usually, a quick retry fixes it.

If you need to dig deeper on macOS, use the built-in dns-sd tool to browse for instances:

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

On iOS, you can find specific logs under Settings → Gateway → Advanced → Discovery Logs.

Still having trouble getting your nodes to see the Gateway? Reach out to the AI Setup Assistant.

What’s Next

• Discovery Policy: Learn how OpenClaw selects transports.
• Gateway Pairing: How to approve and pair your discovered nodes.