Command Overview
The openclaw dns command manages OpenClaw's service discovery feature. In multi-node deployments, service discovery lets Gateway nodes automatically find each other without manually configuring addresses.
View Service Discovery Status
openclaw dns status
DNS Service Discovery:
Mode: mDNS (local network)
Status: Active
This node: gateway-1 (192.168.1.10:3000)
Discovered nodes:
gateway-2 192.168.1.11:3000 ● Online 2ms
gateway-3 192.168.1.12:3000 ● Online 3ms
Enable Service Discovery
mDNS Mode (LAN)
Suitable for multi-node deployments within the same network:
openclaw dns enable --mode mdns
Configuration:
{
"dns": {
"enabled": true,
"mode": "mdns",
"serviceName": "openclaw",
"port": 3000,
"metadata": {
"version": "1.2.3",
"role": "primary"
}
}
}
DNS-SD Mode
DNS-based service discovery, suitable for cross-network deployments:
{
"dns": {
"enabled": true,
"mode": "dns-sd",
"domain": "openclaw.local",
"registryUrl": "https://registry.example.com"
}
}
Consul Mode
Use HashiCorp Consul for service discovery:
{
"dns": {
"enabled": true,
"mode": "consul",
"consulUrl": "http://consul.example.com:8500",
"serviceName": "openclaw-gateway",
"healthCheckInterval": "10s"
}
}
Register and Deregister
# Manually register the current node
openclaw dns register
# Deregister the current node
openclaw dns deregister
# Register with metadata
openclaw dns register --meta role=primary --meta region=us-east
Discover Other Nodes
# List all discovered nodes
openclaw dns discover
Discovered OpenClaw Nodes:
Name Address Port Role Region Status
────────────────────────────────────────────────────────────────
gateway-1 192.168.1.10 3000 primary us-east ● Online
gateway-2 192.168.1.11 3000 replica us-east ● Online
gateway-3 10.0.0.5 3000 replica eu-west ● Online
Load Balancer Integration
Service discovery can automatically update load balancer backend lists:
{
"dns": {
"loadBalancer": {
"enabled": true,
"strategy": "round-robin",
"healthCheck": {
"interval": 10000,
"timeout": 5000,
"unhealthyThreshold": 3
}
}
}
}
Event Monitoring
# Watch for node change events
openclaw dns watch
Watching for node changes...
[10:30:01] NODE_JOIN gateway-4 192.168.1.13:3000
[10:35:22] NODE_LEAVE gateway-2 192.168.1.11:3000
[10:35:25] NODE_JOIN gateway-2 192.168.1.11:3000 (reconnected)
Auto Configuration Sync
Automatically sync configuration when new nodes are discovered:
{
"dns": {
"autoSync": {
"enabled": true,
"syncConfig": true,
"syncSecrets": false,
"primaryNode": "gateway-1"
}
}
}
Diagnostics
openclaw dns diagnose
DNS Discovery Diagnostics:
✓ mDNS service running
✓ Port 5353 available
✓ Network interface: eth0 (192.168.1.10)
✓ Multicast enabled
✓ 2 nodes discovered
✓ All nodes healthy
Security Configuration
{
"dns": {
"security": {
"requireAuth": true,
"authToken": "{{DNS_AUTH_TOKEN}}",
"encryptTraffic": true,
"allowedNetworks": ["192.168.1.0/24", "10.0.0.0/8"]
}
}
}
Disable Service Discovery
openclaw dns disable
Summary
openclaw dns provides automated service discovery for multi-node deployments. Whether using mDNS on a local network or Consul for cross-network integration, it allows multiple Gateway nodes to discover each other and work together, significantly reducing operational complexity in distributed deployments.