> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bonjour-Erkennung

# Bonjour / mDNS-Erkennung

OpenClaw verwendet Bonjour (mDNS / DNS‑SD) als **reine LAN‑Komfortfunktion**, um
einen aktiven Gateway (WebSocket-Endpunkt) zu erkennen. Dies ist Best‑Effort und
ersetzt **nicht** SSH oder Tailnet‑basierte Konnektivität.

## Weitbereichs‑Bonjour (Unicast DNS‑SD) über Tailscale

Wenn sich Node und Gateway in unterschiedlichen Netzwerken befinden, überschreitet
multicast‑mDNS die Netzwerkgrenze nicht. Sie können die gleiche Discovery‑UX beibehalten,
indem Sie auf **Unicast DNS‑SD** („Wide‑Area Bonjour“) über Tailscale umstellen.

Hochwertige Schritte:

1. Betreiben Sie einen DNS‑Server auf dem Gateway‑Host (über das Tailnet erreichbar).
2. Veröffentlichen Sie DNS‑SD‑Records für `_openclaw-gw._tcp` unter einer dedizierten Zone
   (Beispiel: `openclaw.internal.`).
3. Konfigurieren Sie Tailscale **Split DNS**, sodass Ihre 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 Ihre konfigurierte
Weitbereichs‑Domain.

### Gateway‑Konfiguration (empfohlen)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}
```

### Einmalige DNS‑Server‑Einrichtung (Gateway‑Host)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw dns setup --apply
```

Dies installiert CoreDNS und konfiguriert es so, dass:

* auf Port 53 nur auf den Tailscale‑Interfaces des Gateways gelauscht wird
* Ihre gewählte Domain (Beispiel: `openclaw.internal.`) aus `~/.openclaw/dns/<domain>.db` bedient wird

Validieren Sie dies von einer mit dem Tailnet verbundenen Maschine:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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ügen Sie einen Nameserver hinzu, der auf die Tailnet‑IP des Gateways zeigt (UDP/TCP 53).
* Fügen Sie Split DNS hinzu, sodass Ihre Discovery‑Domain diesen Nameserver verwendet.

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

### Sicherheit des Gateway‑Listeners (empfohlen)

Der Gateway‑WS‑Port (Standard `18789`) bindet standardmäßig an Loopback. Für
LAN-/Tailnet‑Zugriff binden Sie explizit und lassen die Authentifizierung aktiviert.

Für reine Tailnet‑Setups:

* Setzen Sie `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json`.
* Starten Sie den Gateway neu (oder starten Sie die macOS‑Menüleisten‑App neu).

## Was werbt

Nur der Gateway annonciert `_openclaw-gw._tcp`.

## Servicetypen

* `_openclaw-gw._tcp` — Gateway‑Transport‑Beacon (verwendet von macOS/iOS/Android‑Nodes).

## TXT‑Schlüssel (nicht‑geheime Hinweise)

Der Gateway annonciert kleine, nicht‑geheime Hinweise, 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 Fingerabdruck verfügbar ist)
* `canvasPort=<port>` (nur wenn der Canvas‑Host aktiviert ist; Standard `18793`)
* `sshPort=<port>` (Standard ist 22, wenn nicht überschrieben)
* `transport=gateway`
* `cliPath=<path>` (optional; absoluter Pfad zu einem ausführbaren `openclaw`‑Entrypoint)
* `tailnetDns=<magicdns>` (optionaler Hinweis, wenn Tailnet verfügbar ist)

Sicherheitshinweise:

* Bonjour/mDNS-TXT-Records sind **nicht authentifiziert**. Clients dürfen TXT nicht als maßgebliches Routing behandeln.
* Clients sollten über den aufgelösten Service-Endpunkt (SRV + A/AAAA) routen. `lanHost`, `tailnetDns`, `gatewayPort` und `gatewayTlsSha256` nur als Hinweise behandeln.
* TLS-Pinning darf niemals zulassen, dass ein beworbenes `gatewayTlsSha256` einen zuvor gespeicherten Pin überschreibt.
* iOS/Android-Knoten sollten discovery-basierte Direktverbindungen ausschließlich als **TLS-only** behandeln und vor dem Vertrauen eines erstmaligen Fingerabdrucks eine ausdrückliche Benutzerbestätigung verlangen.

## Debugging unter macOS

Nützliche integrierte Werkzeuge:

* Instanzen durchsuchen:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  dns-sd -B _openclaw-gw._tcp local.
  ```

* Eine Instanz auflösen (ersetzen Sie `<instance>`):

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  dns-sd -L "<instance>" _openclaw-gw._tcp local.
  ```

Wenn das Durchsuchen funktioniert, das Auflösen jedoch fehlschlägt, liegt in der Regel
eine LAN‑Richtlinie oder ein mDNS‑Resolver‑Problem vor.

## Debugging in Gateway‑Logs

Der Gateway schreibt eine rotierende Logdatei (beim Start ausgegeben als
`gateway log file: ...`). Achten Sie auf `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 erkennen.

So erfassen Sie Logs:

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

Das Log enthält Zustandsübergänge des Browsers und Änderungen der Ergebnismenge.

## Häufige Fehlermodi

* **Bonjour überschreitet keine Netzwerke**: Verwenden Sie Tailnet oder SSH.
* **Multicast blockiert**: Einige WLAN‑Netze deaktivieren mDNS.
* **Sleep / Interface‑Wechsel**: macOS kann mDNS‑Ergebnisse vorübergehend verwerfen; erneut versuchen.
* **Durchsuchen funktioniert, Auflösen schlägt fehl**: Halten Sie Rechnernamen einfach
  (vermeiden Sie Emojis oder Satzzeichen) und starten Sie anschließend den Gateway neu. Der Service‑Instanzname leitet sich vom Hostnamen ab; zu komplexe Namen können einige
  Resolver verwirren.

## Escaped Instanznamen (`\032`)

Bonjour/DNS‑SD escaped häufig Bytes in Service‑Instanznamen als dezimale
`\DDD`‑Sequenzen (z. B. werden Leerzeichen zu `\032`).

* Dies ist auf Protokollebene normal.
* UIs sollten zur Anzeige dekodieren (iOS verwendet `BonjourEscapes.decode`).

## Deaktivierung / Konfiguration

* `OPENCLAW_DISABLE_BONJOUR=1` deaktiviert die Ankündigung (Legacy: `OPENCLAW_DISABLE_BONJOUR`).
* `gateway.bind` in `~/.openclaw/openclaw.json` steuert den Bind‑Modus des Gateways.
* `OPENCLAW_SSH_PORT` überschreibt den in TXT annoncierten 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 annoncierten CLI‑Pfad (Legacy: `OPENCLAW_CLI_PATH`).

## Verwandte Dokumente

* Discovery‑Richtlinie und Transportauswahl: [Discovery](/gateway/discovery)
* Node‑Pairing + Genehmigungen: [Gateway pairing](/gateway/pairing)