Bonjour / mDNS Discovery

OpenClaw nutzt Bonjour (mDNS / DNS-SD) als praktische LAN-Funktion, um einen aktiven Gateway (WebSocket-Endpunkt) zu finden. Das funktioniert nach dem Best-Effort-Prinzip und ersetzt nicht SSH oder Tailnet-basierte Verbindungen.

Wide-Area Bonjour (Unicast DNS-SD) über Tailscale

Wenn Node und Gateway in verschiedenen Netzwerken sind, funktioniert Multicast-mDNS nicht netzwerkübergreifend. Du kannst die gleiche Discovery-UX behalten, indem du auf Unicast DNS-SD (“Wide-Area Bonjour”) über Tailscale umsteigst.

Grobe Schritte:

  1. Starte einen DNS-Server auf dem Gateway-Host (erreichbar über Tailnet).
  2. Veröffentliche DNS-SD-Records für _openclaw-gw._tcp unter einer eigenen Zone (Beispiel: openclaw.internal.).
  3. Konfiguriere Tailscale Split DNS, damit deine gewählte Domain über diesen DNS-Server aufgelöst wird (auch für iOS-Clients).

OpenClaw unterstützt jede Discovery-Domain; openclaw.internal. ist nur ein Beispiel. iOS/Android-Nodes durchsuchen sowohl local. als auch deine konfigurierte Wide-Area-Domain.

Gateway-Konfiguration (empfohlen)

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

Einmalige DNS-Server-Einrichtung (Gateway-Host)

openclaw dns setup --apply

Das installiert CoreDNS und konfiguriert es so:

  • Lauscht auf Port 53 nur auf den Tailscale-Interfaces des Gateways
  • Stellt deine gewählte Domain (Beispiel: openclaw.internal.) aus ~/.openclaw/dns/<domain>.db bereit

Teste von einem Tailnet-verbundenen Rechner:

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

Tailscale DNS-Einstellungen

In der Tailscale Admin-Konsole:

  • Füge einen Nameserver hinzu, der auf die Tailnet-IP des Gateways zeigt (UDP/TCP 53).
  • Richte Split DNS ein, damit deine Discovery-Domain diesen Nameserver verwendet.

Sobald Clients das Tailnet-DNS akzeptieren, können iOS-Nodes _openclaw-gw._tcp in deiner Discovery-Domain ohne Multicast durchsuchen.

Gateway-Listener-Sicherheit (empfohlen)

Der Gateway-WS-Port (Standard 18789) bindet standardmäßig nur an Loopback. Für LAN/Tailnet-Zugriff binde explizit und lass die Authentifizierung aktiviert.

Für reine Tailnet-Setups:

  • Setze gateway.bind: "tailnet" in ~/.openclaw/openclaw.json.
  • Starte den Gateway neu (oder starte die macOS-Menubar-App neu).

Was wird angekündigt

Nur der Gateway kündigt _openclaw-gw._tcp an.

Service-Typen

  • _openclaw-gw._tcp — Gateway-Transport-Beacon (wird von macOS/iOS/Android-Nodes verwendet).

TXT-Keys (nicht-geheime Hinweise)

Der Gateway kündigt kleine, nicht-geheime Hinweise an, um UI-Abläufe zu vereinfachen:

  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (Gateway WS + HTTP)
  • gatewayTls=1 (nur wenn TLS aktiviert ist)
  • gatewayTlsSha256=<sha256> (nur wenn TLS aktiviert ist und ein Fingerprint verfügbar ist)
  • canvasPort=<port> (nur wenn der Canvas-Host aktiviert ist; Standard 18793)
  • sshPort=<port> (Standard 22, wenn nicht überschrieben)
  • transport=gateway
  • cliPath=<path> (optional; absoluter Pfad zu einem ausführbaren openclaw-Einstiegspunkt)
  • tailnetDns=<magicdns> (optionaler Hinweis, wenn Tailnet verfügbar ist)

Debugging auf macOS

Nützliche eingebaute Tools:

  • Instanzen durchsuchen: 
    dns-sd -B _openclaw-gw._tcp local.
  • Eine Instanz auflösen (ersetze <instance>): 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.

Wenn das Durchsuchen funktioniert, aber das Auflösen fehlschlägt, liegt es meist an einer LAN-Policy oder einem mDNS-Resolver-Problem.

Debugging in Gateway-Logs

Der Gateway schreibt eine rotierende Log-Datei (wird beim Start als gateway log file: ... ausgegeben). Schau nach bonjour:-Zeilen, besonders:

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

Debugging auf iOS-Node

Der iOS-Node verwendet NWBrowser, um _openclaw-gw._tcp zu finden.

So erfasst du Logs:

  • Settings → Gateway → Advanced → Discovery Debug Logs
  • Settings → Gateway → Advanced → Discovery Logs → reproduzieren → Copy

Das Log enthält Browser-Statusübergänge und Änderungen der Ergebnismenge.

Typische Fehlerquellen

  • Bonjour funktioniert nicht netzwerkübergreifend: Nutze Tailnet oder SSH.
  • Multicast blockiert: Manche WLAN-Netzwerke deaktivieren mDNS.
  • Sleep / Interface-Wechsel: macOS kann mDNS-Ergebnisse vorübergehend verlieren; einfach nochmal versuchen.
  • Durchsuchen funktioniert, aber Auflösen nicht: Halte Rechnernamen einfach (vermeide Emojis oder Sonderzeichen), dann starte den Gateway neu. Der Service-Instanzname leitet sich vom Hostnamen ab, daher können zu komplexe Namen manche Resolver verwirren.

Escaped Instance Names (\032)

Bonjour/DNS-SD escaped Bytes in Service-Instanznamen oft als dezimale \DDD-Sequenzen (z.B. werden Leerzeichen zu \032).

  • Das ist auf Protokollebene normal.
  • UIs sollten das für die Anzeige dekodieren (iOS verwendet BonjourEscapes.decode).

Deaktivieren / Konfiguration

  • OPENCLAW_DISABLE_BONJOUR=1 deaktiviert das Advertising (Legacy: OPENCLAW_DISABLE_BONJOUR).
  • gateway.bind in ~/.openclaw/openclaw.json steuert den Gateway-Bind-Modus.
  • OPENCLAW_SSH_PORT überschreibt den im TXT angekündigten SSH-Port (Legacy: OPENCLAW_SSH_PORT).
  • OPENCLAW_TAILNET_DNS veröffentlicht einen MagicDNS-Hinweis im TXT (Legacy: OPENCLAW_TAILNET_DNS).
  • OPENCLAW_CLI_PATH überschreibt den angekündigten CLI-Pfad (Legacy: OPENCLAW_CLI_PATH).

Verwandte Dokumentation