Discovery & Transporte

OpenClaw hat zwei verschiedene Probleme, die sich oberflächlich ähneln:

  1. Operator-Fernsteuerung: Die macOS-Menüleisten-App steuert ein Gateway, das anderswo läuft.
  2. Node-Pairing: iOS/Android (und zukünftige Nodes) finden ein Gateway und koppeln sich sicher.

Das Designziel ist, die gesamte Netzwerk-Discovery/Werbung im Node-Gateway (openclaw gateway) zu halten und Clients (Mac-App, iOS) als Konsumenten zu verwenden.

Begriffe

  • Gateway: Ein einzelner lang laufender Gateway-Prozess, der den State verwaltet (Sessions, Pairing, Node-Registry) und Kanäle betreibt. Die meisten Setups verwenden eins pro Host; isolierte Multi-Gateway-Setups sind möglich.
  • Gateway WS (Control Plane): Der WebSocket-Endpoint auf 127.0.0.1:18789 standardmäßig; kann über gateway.bind an LAN/Tailnet gebunden werden.
  • Direkter WS-Transport: Ein LAN-/Tailnet-seitiger Gateway-WS-Endpoint (kein SSH).
  • SSH-Transport (Fallback): Fernsteuerung durch Weiterleitung von 127.0.0.1:18789 über SSH.
  • Legacy TCP Bridge (veraltet/entfernt): Älterer Node-Transport (siehe Bridge-Protokoll); wird für Discovery nicht mehr beworben.

Protokolldetails:

Warum es “direkt” und SSH gibt

  • Direkter WS bietet die beste UX im selben Netzwerk und innerhalb eines Tailnets:
    • Auto-Discovery im LAN via Bonjour
    • Pairing-Token + ACLs werden vom Gateway verwaltet
    • Kein Shell-Zugang erforderlich; die Protokolloberfläche bleibt schlank und auditierbar
  • SSH bleibt der universelle Fallback:
    • Funktioniert überall, wo du SSH-Zugang hast (auch über unverbundene Netzwerke hinweg)
    • Übersteht Multicast/mDNS-Probleme
    • Benötigt keine neuen eingehenden Ports außer SSH

Discovery-Eingaben (wie Clients das Gateway finden)

1) Bonjour / mDNS (nur LAN)

Bonjour arbeitet nach dem Best-Effort-Prinzip und überwindet keine Netzwerkgrenzen. Es wird nur für die “gleiches LAN”-Komfortfunktion verwendet.

Zielrichtung:

  • Das Gateway kündigt seinen WS-Endpoint via Bonjour an.
  • Clients suchen und zeigen eine “Gateway auswählen”-Liste, dann speichern sie den gewählten Endpoint.

Fehlersuche und Beacon-Details: Bonjour.

Service-Beacon-Details

  • Service-Typen:
    • _openclaw-gw._tcp (Gateway-Transport-Beacon)
  • TXT-Schlüssel (nicht-geheim):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (oder was angekündigt wird)
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (nur wenn TLS aktiviert)
    • gatewayTlsSha256=<sha256> (nur wenn TLS aktiviert und Fingerprint verfügbar)
    • canvasPort=<port> (Canvas-Host-Port; derzeit identisch mit gatewayPort, wenn der Canvas-Host aktiviert ist)
    • cliPath=<pfad> (optional; absoluter Pfad zu einem ausführbaren openclaw-Einstiegspunkt oder Binary)
    • tailnetDns=<magicdns> (optionaler Hinweis; automatisch erkannt, wenn Tailscale verfügbar)

Sicherheitshinweise:

  • Bonjour/mDNS-TXT-Records sind nicht authentifiziert. Clients müssen TXT-Werte nur als UX-Hinweise behandeln.
  • Routing (Host/Port) sollte den aufgelösten Service-Endpoint (SRV + A/AAAA) gegenüber TXT-bereitgestelltem lanHost, tailnetDns oder gatewayPort bevorzugen.
  • TLS-Pinning darf niemals zulassen, dass ein angekündigter gatewayTlsSha256 einen zuvor gespeicherten Pin überschreibt.
  • iOS/Android-Nodes sollten Discovery-basierte Direktverbindungen als TLS-only behandeln und eine explizite “Diesem Fingerprint vertrauen”-Bestätigung erfordern, bevor ein erstmaliger Pin gespeichert wird (Out-of-Band-Verifizierung).

Deaktivierung/Override:

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

2) Tailnet (netzwerkübergreifend)

Für London/Wien-artige Setups hilft Bonjour nicht weiter. Das empfohlene “direkte” Ziel ist:

  • Tailscale MagicDNS-Name (bevorzugt) oder eine stabile Tailnet-IP.

Wenn das Gateway erkennt, dass es unter Tailscale läuft, veröffentlicht es tailnetDns als optionalen Hinweis für Clients (einschließlich Wide-Area-Beacons).

3) Manuell / SSH-Ziel

Wenn kein direkter Weg existiert (oder direkt deaktiviert ist), können sich Clients immer per SSH verbinden, indem sie den Loopback-Gateway-Port weiterleiten.

Siehe Remote-Zugang.

Transport-Auswahl (Client-Policy)

Empfohlenes Client-Verhalten:

  1. Wenn ein gepairter Direkt-Endpoint konfiguriert und erreichbar ist, verwende ihn.
  2. Andernfalls: Wenn Bonjour ein Gateway im LAN findet, biete eine Ein-Tipp-Auswahl “Dieses Gateway verwenden” an und speichere es als Direkt-Endpoint.
  3. Andernfalls: Wenn ein Tailnet-DNS/IP konfiguriert ist, versuche direkt.
  4. Andernfalls: Falle auf SSH zurück.

Pairing + Auth (direkter Transport)

Das Gateway ist die Single Source of Truth für Node-/Client-Zulassung.

  • Pairing-Anfragen werden im Gateway erstellt/genehmigt/abgelehnt (siehe Gateway-Pairing).
  • Das Gateway erzwingt:
    • Auth (Token / Schlüsselpaar)
    • Scopes/ACLs (das Gateway ist kein offener Proxy für alle Methoden)
    • Rate Limits

Verantwortlichkeiten nach Komponente

  • Gateway: Sendet Discovery-Beacons, trifft Pairing-Entscheidungen und hostet den WS-Endpoint.
  • macOS-App: Hilft bei der Gateway-Auswahl, zeigt Pairing-Aufforderungen und verwendet SSH nur als Fallback.
  • iOS/Android-Nodes: Durchsuchen Bonjour als Komfortfunktion und verbinden sich mit dem gepaarten Gateway-WS.
arrow_back
Zurück
Pairing
Weiter
Bonjour
arrow_forward