Complete reference for openclaw dns, configuring DNS-SD for wide-area Gateway discovery via CoreDNS and Tailscale split DNS.
What does Openclaw DNS Solve?
By default, OpenClaw clients discover the Gateway using local multicast (mDNS / DNS-SD), which works fine on a LAN but breaks the moment clients are on different networks, a remote machine, a phone on cellular, or a device connecting over Tailscale.
The dns setup command prepares the configuration for wide-area discovery, and dns setup –apply goes further: it installs CoreDNS and wires it to your Tailscale interface so that any Tailnet-connected client can discover the Gateway by domain name regardless of physical network.
When to Use Each Command
Run openclaw dns setup (without –apply) first, it generates the zone file and prints what would be configured, letting you review before touching your system. Run openclaw dns setup –apply when you’re ready to actually install CoreDNS and activate the DNS configuration.
The –apply path requires sudo and is currently macOS only. Once applied, the final step is pointing your Tailscale split DNS setting at the gateway’s Tailnet IP, the command output tells you exactly which IP to use.
Commands
Two variants of dns setup, one previews the configuration, the other applies it.
| openclaw dns setup Prepares the DNS-SD configuration for wide-area discovery. Generates the zone file and prints configuration details without modifying your system. Use this to review what –apply would do before committing. |
| openclaw dns setup –apply Installs and configures CoreDNS on your system. Activates wide-area DNS-SD discovery over Tailscale. Requires sudo privileges, the command will prompt for your password. |
openclaw dns setup –apply is currently supported on macOS only. Running it on Linux or Windows is not currently supported. The preview command (dns setup without –apply) works on all platforms.
both variants
# Preview — generate config, print details, no system changes openclaw dns setup # Apply — install CoreDNS and activate (macOS, requires sudo) openclaw dns setup --apply
What –apply Actually Does
When you run openclaw dns setup --apply, OpenClaw installs CoreDNS and configures it with two specific behaviors.
Installation steps
- Installs CoreDNS on your system via the platform package manager. CoreDNS becomes the DNS resolver for the configured discovery domain on your machine.
- Configures CoreDNS to listen on port 53, exclusively on the gateway’s Tailscale interfaces, not on all network interfaces. This keeps the DNS server scoped to your Tailnet and avoids conflicts with your system’s existing DNS resolver.
- Serves your chosen discovery domain (for example, openclaw.internal) from the zone file generated at ~/openclaw/dns/<domain>.db. The zone file is created during the preview step and applied here.
How Discovery Works After Setup
After applying the DNS configuration, the discovery flow across different networks looks like this:
- Resolve
gateway.openclaw.internal: The client finds the IP via the Tailscale split DNS. - Establish Connection: The client attempts to shake hands with the Gateway.
- Verify Credentials: Once discovered, the client must present a valid token. If you find the Gateway but cannot connect, refer to our guide on Resolving Gateway Token Mismatch to ensure your client and server are using synchronized security credentials.
The final manual step after running --apply is pointing your Tailscale split DNS to the gateway’s Tailnet IP. The command output prints the exact IP to use.
The final manual step after running –apply is pointing your Tailscale split DNS to the gateway’s Tailnet IP. The command output prints the exact IP to use. Without this step, clients outside your local network won’t resolve the discovery domain.
CoreDNS only listens on the gateway’s Tailscale interfaces, not all network interfaces. If Tailscale is not running or the interface is down, DNS-SD discovery will not function, fall back to direct IP or local mDNS in that case.
