Bonjour Discovery & DNS

+15 Mana ✨
OpenClaw Bonjour Discovery(DOCUMENTATION)

Introduction

OpenClaw supports automatic service discovery via Bonjour (mDNS) on local networks and DNS-based discovery for wide-area networks. The openclaw dns setup command configures CoreDNS integration with Tailscale for seamless gateway discovery across your infrastructure.

Key Concepts

  • Bonjour (mDNS): A zero-configuration networking protocol that lets devices discover OpenClaw gateways on the local network without manual configuration.
  • DNS Discovery: Using DNS records to locate gateways across networks, enabling wide-area discovery.
  • CoreDNS: A flexible DNS server that integrates with Tailscale for gateway discovery across your tailnet.
  • Service Registration: Gateways automatically register themselves for discovery when Bonjour is enabled.

Real World Context

A developer has three machines on their home network, each running a specialized OpenClaw gateway. Instead of remembering IP addresses and ports, they enable Bonjour discovery. Their TUI client automatically discovers all three gateways and presents them in a selection menu.

Deep Dive

Enable Bonjour discovery in the gateway configuration:

json
{
  "discovery": {
    "bonjour": {
      "enabled": true,
      "name": "Production Gateway",
      "metadata": {
        "environment": "production",
        "team": "engineering"
      }
    }
  }
}

With Bonjour enabled, the gateway broadcasts its presence on the local network. Any OpenClaw client (TUI, nodes, web) can discover it automatically.

For cross-network discovery, set up DNS with Tailscale:

bash
# Set up DNS discovery
openclaw dns setup --provider tailscale

# This configures CoreDNS to serve records like:
# gateway-prod.openclaw.ts.net -> 100.64.x.x:18789
# gateway-dev.openclaw.ts.net  -> 100.64.x.y:18790

The openclaw dns setup command configures CoreDNS to register gateway instances as DNS records within your Tailscale network. Clients resolve gateway addresses via DNS without manual IP management.

Clients discover gateways using the OpenClaw discovery protocol:

bash
# Discover gateways on the local network
openclaw discover

# Output:
# Found 2 gateways:
#   Production Gateway (192.168.1.100:18789) [production, engineering]
#   Dev Gateway (192.168.1.101:18790) [development, engineering]

The discover command uses Bonjour to find local gateways and DNS to find remote ones.

Common Pitfalls

  1. Bonjour blocked by network firewall — Corporate networks often block mDNS traffic (port 5353). Bonjour discovery will not work on these networks.
  2. DNS records becoming stale — If a gateway goes offline without deregistering, DNS records may point to an unreachable host. Use TTLs to mitigate.

Best Practices

  1. Use Bonjour for local, DNS for remote — Bonjour is perfect for same-network discovery. Use DNS for cross-network access.
  2. Include metadata in Bonjour registration — Tags like environment and team help clients filter gateways.

Summary

  • Bonjour enables zero-configuration gateway discovery on local networks
  • DNS integration with CoreDNS and Tailscale enables wide-area discovery
  • openclaw dns setup configures DNS records for your gateways automatically
  • Clients use openclaw discover to find available gateways
  • Use Bonjour for local networks and DNS for cross-network discovery
✓ Completed