Discovery & Transports

OpenClaw hat zwei unterschiedliche Probleme, die auf den ersten Blick ähnlich aussehen:

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

Das Designziel ist, alle Netzwerk-Discovery/Advertising im Node Gateway (openclaw gateway) zu halten und Clients (Mac-App, iOS) als Konsumenten zu behandeln.

Begriffe

  • Gateway: Ein einzelner, dauerhaft laufender Gateway-Prozess, der den State verwaltet (Sessions, Pairing, Node-Registry) und Channels betreibt. Die meisten Setups nutzen ein Gateway 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.
  • Direct WS Transport: Ein LAN/Tailnet-seitiger Gateway-WS-Endpoint (ohne 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 nicht mehr für Discovery beworben.

Protokoll-Details:

Warum wir sowohl “Direct” als auch SSH behalten

  • Direct WS bietet die beste UX im selben Netzwerk und innerhalb eines Tailnets:
    • Auto-Discovery im LAN via Bonjour
    • Pairing-Tokens + ACLs werden vom Gateway verwaltet
    • Kein Shell-Zugriff nötig; die Protokoll-Oberfläche bleibt schlank und auditierbar
  • SSH bleibt der universelle Fallback:
    • Funktioniert überall, wo du SSH-Zugriff 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 funktioniert nicht netzwerkübergreifend. Es wird nur für die Bequemlichkeit im “selben LAN” verwendet.

Zielrichtung:

  • Das Gateway bewirbt seinen WS-Endpoint via Bonjour.
  • Clients durchsuchen und zeigen eine “Gateway auswählen”-Liste, dann speichern sie den gewählten Endpoint.

Troubleshooting und Beacon-Details: Bonjour.

Service-Beacon-Details

  • Service-Typen:
    • _openclaw-gw._tcp (Gateway-Transport-Beacon)
  • TXT-Keys (nicht geheim):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (oder was auch immer beworben wird)
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (nur wenn TLS aktiviert ist)
    • gatewayTlsSha256=<sha256> (nur wenn TLS aktiviert ist und ein Fingerprint verfügbar ist)
    • canvasPort=18793 (Standard-Canvas-Host-Port; liefert /__openclaw__/canvas/)
    • cliPath=<path> (optional; absoluter Pfad zu einem ausführbaren openclaw-Einstiegspunkt oder Binary)
    • tailnetDns=<magicdns> (optionaler Hinweis; wird automatisch erkannt, wenn Tailscale verfügbar ist)

Deaktivieren/Überschreiben:

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

2) Tailnet (netzwerkübergreifend)

Für London/Vienna-Style-Setups hilft Bonjour nicht. Das empfohlene “Direct”-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 es keine direkte Route gibt (oder Direct deaktiviert ist), können Clients sich immer via SSH verbinden, indem sie den Loopback-Gateway-Port weiterleiten.

Siehe Remote-Zugriff.

Transport-Auswahl (Client-Policy)

Empfohlenes Client-Verhalten:

  1. Wenn ein gekoppelter Direct-Endpoint konfiguriert und erreichbar ist, nutze ihn.
  2. Andernfalls, wenn Bonjour ein Gateway im LAN findet, biete eine “Dieses Gateway verwenden”-Auswahl mit einem Tap an und speichere es als Direct-Endpoint.
  3. Andernfalls, wenn eine Tailnet-DNS/IP konfiguriert ist, versuche Direct.
  4. Andernfalls, falle auf SSH zurück.

Pairing + Auth (Direct Transport)

Das Gateway ist die Quelle der Wahrheit für Node/Client-Zulassung.

  • Pairing-Anfragen werden im Gateway erstellt/genehmigt/abgelehnt (siehe Gateway Pairing).
  • Das Gateway erzwingt:
    • Auth (Token / Keypair)
    • Scopes/ACLs (das Gateway ist kein roher Proxy für jede Methode)
    • Rate Limits

Verantwortlichkeiten nach Komponente

  • Gateway: Bewirbt Discovery-Beacons, trifft Pairing-Entscheidungen und hostet den WS-Endpoint.
  • macOS-App: Hilft dir bei der Gateway-Auswahl, zeigt Pairing-Prompts und nutzt SSH nur als Fallback.
  • iOS/Android-Nodes: Durchsuchen Bonjour als Komfortfunktion und verbinden sich mit dem gekoppelten Gateway WS.