OpenClaw DNS - Setting Up Wide-Area Discovery for Distributed AI Agents

Once you're running more than one OpenClaw gateway - maybe one on your dev machine, one on a server, another in a different office - you hit a problem that everyone hits eventually: how do agents find each other?

Local discovery works fine when everything is on the same network. mDNS handles it. But the moment your gateways span multiple networks, subnets, or physical locations, mDNS falls over because it's designed for local broadcast traffic. You need something that works across wide-area networks.

OpenClaw solves this with DNS-based service discovery (DNS-SD) using CoreDNS and Tailscale. The openclaw dns command handles the setup, and while the concept sounds complicated, the actual process is fairly straightforward - at least on macOS where the tooling is most mature.

Why This Matters for Real Deployments

In a demo or prototype, running a single OpenClaw gateway on your laptop is fine. But production agent workflows tend to spread across machines quickly.

You might have a gateway on a GPU-equipped server handling model inference, another on a lightweight machine managing chat integrations, and a third running scheduled cron jobs. Maybe your team is split across Sydney and Melbourne offices, each with their own gateway serving local agents.

Without wide-area discovery, each gateway is an island. Agents can't route requests to the right gateway. You end up manually configuring endpoint URLs, which is brittle and annoying to maintain. Every time you add or move a gateway, you're updating configuration files everywhere.

DNS-SD fixes this by letting gateways register themselves in DNS and discover each other automatically. An agent says "I need a gateway that can handle this model" and the discovery system finds one, regardless of which network it's on.

The Components Involved

Three pieces work together for OpenClaw wide-area discovery:

Tailscale creates a private mesh network connecting your machines. Each machine gets a stable IP on the Tailscale network (a tailnet), and traffic between machines is encrypted and routed automatically. If you're not already using Tailscale for connecting your infrastructure, you should probably look into it - it removes a lot of networking headaches.

CoreDNS runs on one or more machines as a DNS server that hosts the discovery zone. When a gateway starts up, it registers itself in the DNS zone. When another gateway needs to discover peers, it queries DNS.

OpenClaw's DNS commands handle the glue between these two. They configure CoreDNS with the right zone files, populate the zone with your Tailscale IPs, and generate the configuration that tells OpenClaw where to look for peers.

Running the Setup

The openclaw dns setup command does most of the heavy lifting. Without the --apply flag, it's a planning tool - it shows you what it would do without changing anything.

openclaw dns setup

This outputs:

• The discovery domain that will be used (defaulting to whatever is in your openclaw.json config, or a sensible default)
• The zone file path where DNS records will live
• Your current Tailscale IPs
• The recommended openclaw.json discovery configuration
• The Split DNS settings you need to configure in Tailscale

Read through this output before applying anything. It's worth understanding what's going to be configured, especially the Tailscale Split DNS values. You'll need to set those in the Tailscale admin console so that DNS queries for your discovery domain get routed to your CoreDNS instance instead of the public internet.

If you want to specify a custom domain:

openclaw dns setup --domain openclaw.internal

The .internal TLD is a good choice here - it's reserved for private use and won't conflict with any public DNS records. Some teams use their company domain with an internal subdomain (like agents.internal.company.com), but .internal keeps things simpler.

When you're happy with the plan, apply it:

openclaw dns setup --apply

This requires sudo on macOS and currently only supports Homebrew-installed CoreDNS. It will:

1. Create or update the zone file with your gateway's Tailscale IP
2. Ensure the CoreDNS Corefile has the right import stanza for your discovery zone
3. Restart the CoreDNS Homebrew service

If CoreDNS isn't installed yet, install it first with brew install coredns. The --apply command expects it to be there.

Configuring Tailscale Split DNS

After running the setup, you need to tell Tailscale to route DNS queries for your discovery domain to your CoreDNS instance. The openclaw dns setup output will show you exactly what values to set.

In the Tailscale admin console, go to DNS settings and add a Split DNS entry:

• Domain: your discovery domain (e.g., openclaw.internal)
• Nameserver: the Tailscale IP of the machine running CoreDNS

This means that any machine on your tailnet, when it tries to resolve a hostname under openclaw.internal, will query your CoreDNS instance. All other DNS queries go to whatever nameservers you normally use.

One thing to watch out for: if you're running CoreDNS on a machine that goes to sleep or gets shut down, DNS resolution for your discovery domain will fail. For production setups, run CoreDNS on a machine that stays online - a server, a NAS, a cloud VM on your tailnet.

Updating the OpenClaw Configuration

The setup command outputs a recommended configuration block for openclaw.json. It looks something like this:

{
  "discovery": {
    "wideArea": {
      "domain": "openclaw.internal",
      "enabled": true
    }
  }
}

Add this to your openclaw.json on each gateway that should participate in wide-area discovery. Once configured, the gateway will register itself in DNS on startup and query DNS to find peers.

Multi-Machine Setups

For setups with multiple gateways on different machines, each machine needs:

1. Tailscale installed and connected to your tailnet
2. The OpenClaw discovery configuration in openclaw.json
3. Access to the Split DNS-configured nameserver

Only one machine needs to run CoreDNS. The others just need the Tailscale Split DNS setup pointing to it.

When a new gateway starts, it registers its Tailscale IP in the discovery zone. Other gateways can then discover it by querying DNS. When a gateway shuts down cleanly, it de-registers. The result is a dynamic directory of available gateways that updates automatically.

For teams with gateways in multiple Australian offices - say Sydney and Brisbane - this means agents in either location can discover and route to gateways in the other. A user in Brisbane can transparently use a model running on a GPU server in Sydney, with the routing handled by the discovery system.

What's Still macOS Only

As of now, the --apply flag only works on macOS with Homebrew CoreDNS. If you're running Linux, you'll need to manually configure CoreDNS and manage the zone file. The planning output from openclaw dns setup (without --apply) still works and shows you what to configure, but the automated installation and service management is macOS-specific.

For Linux setups, the manual process is:

1. Install CoreDNS through your package manager
2. Create the zone file at the path shown by openclaw dns setup
3. Add the import stanza to your Corefile
4. Configure your init system (systemd, etc.) to run CoreDNS
5. Set up Tailscale Split DNS as above

It's not difficult, but it's a few more steps. I expect the --apply flag will get Linux support eventually, but for now it's a manual job on non-macOS systems.

When You Don't Need This

If all your gateways are on the same local network, you probably don't need wide-area DNS discovery. Local mDNS discovery handles same-network scenarios without any extra configuration.

Similarly, if you're running a single gateway (even across multiple agents), this setup is overkill. DNS-SD is for multi-gateway deployments that span network boundaries.

The sweet spot for this feature is teams with 3-10 gateways spread across a few locations or a mix of local machines and cloud servers. That's where manual configuration becomes tedious enough that automated discovery pays for itself.

Getting Help With Distributed Agent Infrastructure

Setting up distributed AI agent networks is one of those tasks that's straightforward once you've done it but confusing the first time through. The networking concepts - DNS zones, split DNS, mesh networks - aren't things most application developers deal with regularly.

For teams building out agentic automation across multiple locations, we help design the infrastructure and get the initial setup running. We also provide managed AI services for organisations that want someone else handling the operational complexity of multi-gateway deployments.

The OpenClaw documentation on DNS setup covers the full command reference, and the gateway discovery docs go deeper into how discovery works at the protocol level. Between those and this guide, you should have enough to get a multi-machine setup running.