Bonjour / mDNS-Discovery

OpenClaw nutzt Bonjour (mDNS / DNS‑SD) als LAN-exklusive Komfortfunktion, um ein aktives Gateway (WebSocket-Endpoint) zu entdecken. Es funktioniert nach dem Best-Effort-Prinzip und ersetzt keine SSH- oder Tailnet-basierte Konnektivität.

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

Wenn sich Node und Gateway in verschiedenen Netzwerken befinden, kann Multicast-mDNS die Netzwerkgrenze nicht überwinden. Du kannst die gleiche Discovery-UX beibehalten, indem du auf Unicast DNS‑SD (“Wide‑Area Bonjour”) über Tailscale umsteigst.

Grobe Schritte:

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

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" }, // nur Tailnet (empfohlen)
  discovery: { wideArea: { enabled: true } }, // aktiviert Wide-Area DNS-SD Publishing
}

Einmalige DNS-Server-Einrichtung (Gateway-Host)

openclaw dns setup --apply

Das installiert CoreDNS und konfiguriert es so:

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

Validierung 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).
Konfiguriere Split DNS, damit deine Discovery-Domain diesen Nameserver verwendet.

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

Gateway-Listener-Sicherheit (empfohlen)

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

Für Tailnet-only-Setups:

Setze gateway.bind: "tailnet" in ~/.openclaw/openclaw.json.
Starte das Gateway neu (oder starte die macOS-Menüleisten-App neu).

Was sendet Beacons

Nur das Gateway sendet _openclaw-gw._tcp-Beacons.

Service-Typen

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

TXT-Schlüssel (nicht-geheime Hinweise)

Das Gateway sendet kleine, nicht-geheime Hinweise in Beacons, um UI-Abläufe bequemer zu gestalten:

role=gateway
displayName=<angezeigter 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; derzeit identisch mit gatewayPort)
sshPort=<port> (Standard 22, wenn nicht überschrieben)
transport=gateway
cliPath=<pfad> (optional; absoluter Pfad zu einem ausführbaren openclaw-Einstiegspunkt)
tailnetDns=<magicdns> (optionaler Hinweis, wenn Tailnet verfügbar ist)

Sicherheitshinweise:

Bonjour/mDNS-TXT-Records sind nicht authentifiziert. Clients dürfen TXT-Daten nicht als verbindliches Routing behandeln.
Clients sollten den aufgelösten Service-Endpoint (SRV + A/AAAA) für das Routing verwenden. Behandle lanHost, tailnetDns, gatewayPort und gatewayTlsSha256 nur als Hinweise.
TLS-Pinning darf niemals zulassen, dass ein gesendeter gatewayTlsSha256 einen zuvor gespeicherten Pin überschreibt.
iOS/Android-Nodes sollten Discovery-basierte Direktverbindungen als TLS-only behandeln und eine explizite Benutzerbestätigung erfordern, bevor einem erstmaligen Fingerprint vertraut wird.

Debugging unter 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

Das Gateway schreibt eine rollierende Logdatei (wird beim Start als gateway log file: ... ausgegeben). Suche nach bonjour:-Zeilen, insbesondere:

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

Debugging auf dem iOS-Node

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

Um Logs aufzuzeichnen:

Einstellungen → Gateway → Erweitert → Discovery Debug Logs
Einstellungen → Gateway → Erweitert → Discovery Logs → reproduzieren → Kopieren

Das Log enthält Browser-Zustandsübergänge und Ergebnissatz-Änderungen.

Häufige Fehlerquellen

Bonjour funktioniert nicht netzwerkübergreifend: Verwende Tailnet oder SSH.
Multicast blockiert: Einige WLAN-Netzwerke deaktivieren mDNS.
Sleep / Interface-Wechsel: macOS kann mDNS-Ergebnisse vorübergehend verlieren; erneut versuchen.
Suche funktioniert, aber Auflösung scheitert: Halte Maschinennamen einfach (vermeide Emojis oder Satzzeichen) und starte dann das Gateway neu. Der Service-Instance-Name leitet sich vom Hostnamen ab, sodass zu komplexe Namen manche Resolver verwirren können.

Escaped Instance-Namen (`\032`)

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

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

Deaktivierung / Konfiguration

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