OpenClaw Gateway konfigurieren: Discovery & SSH-Transport
Kennst du das? Du willst einfach nur, dass deine Geräte im Netzwerk miteinander kommunizieren, aber die Konfiguration fühlt sich an wie Raketenwissenschaft. Entweder blockiert eine Firewall den Zugriff oder die IP-Adresse hat sich mal wieder geändert, genau dann, wenn du sie brauchst.
OpenClaw löst dieses Problem durch ein intelligentes System für Discovery und Transports. Das Ziel ist simpel: Alles, was mit Netzwerk-Discovery zu tun hat, passiert im Node Gateway (openclaw gateway), während die Clients (macOS, iOS, Android) diese Informationen einfach nur konsumieren.
Discovery & Transports
Abschnitt betitelt „Discovery & Transports“OpenClaw hat zwei unterschiedliche Probleme, die oberflächlich betrachtet ähnlich aussehen:
- Operator Remote Control: Die macOS Menu Bar App steuert ein Gateway, das an einem anderen Ort läuft.
- Node Pairing: iOS/Android (und zukünftige Nodes) finden ein Gateway und koppeln sich sicher.
Das Design-Ziel ist es, die gesamte Netzwerk-Discovery im Node Gateway (openclaw gateway) zu belassen und Clients (macOS App, iOS) als Konsumenten zu behandeln.
Begriffe
Abschnitt betitelt „Begriffe“- Gateway: Ein einzelner, langlebiger Gateway-Prozess, der den State besitzt (Sessions, Pairing, Node-Registry) und Channels betreibt. Die meisten Setups nutzen eines pro Host; isolierte Multi-Gateway-Setups sind möglich.
- Gateway WS (Control Plane): Der WebSocket-Endpunkt, standardmäßig auf
127.0.0.1:18789; kann viagateway.bindan LAN/Tailnet gebunden werden. - Direct WS Transport: Ein zum LAN/Tailnet gerichteter Gateway WS Endpunkt (kein SSH).
- SSH Transport (Fallback): Fernsteuerung durch Forwarding von
127.0.0.1:18789über SSH. - Legacy TCP Bridge (veraltet/entfernt): Älterer Node-Transport (siehe Bridge protocol); wird nicht mehr für Discovery beworben.
Protokoll-Details:
Warum wir sowohl “direct” als auch SSH behalten
Abschnitt betitelt „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 direkt im Gateway
- Kein Shell-Zugriff erforderlich; die Protokoll-Oberfläche bleibt schmal und prüfbar
- SSH bleibt der universelle Fallback:
- Funktioniert überall, wo du SSH-Zugriff hast (auch über völlig fremde Netzwerke hinweg)
- Überlebt Multicast/mDNS-Probleme
- Erfordert außer SSH keine neuen eingehenden Ports
Discovery-Inputs (Wie Clients das Gateway finden)
Abschnitt betitelt „Discovery-Inputs (Wie Clients das Gateway finden)“1) Bonjour / mDNS (nur LAN)
Abschnitt betitelt „1) Bonjour / mDNS (nur LAN)“Bonjour ist ein Best-Effort-Ansatz und funktioniert nicht netzwerkübergreifend. Es wird nur für den Komfort im selben LAN genutzt.
Zielrichtung:
- Das Gateway bewirbt seinen WS-Endpunkt via Bonjour.
- Clients suchen danach und zeigen eine “Gateway auswählen”-Liste an, dann speichern sie den gewählten Endpunkt.
Fehlerbehebung und Beacon-Details: Bonjour.
Service beacon details
Abschnitt betitelt „Service beacon details“- Service types:
_openclaw-gw._tcp(gateway transport beacon)
- TXT keys (non-secret):
role=gatewaytransport=gatewaydisplayName=<friendly name>(operator-configured display name)lanHost=<hostname>.localsshPort=22(or whatever is advertised)gatewayPort=18789(Gateway WS + HTTP)gatewayTls=1(only when TLS is enabled)gatewayTlsSha256=<sha256>(only when TLS is enabled and fingerprint is available)canvasPort=<port>(canvas host port; currently the same asgatewayPortwhen the canvas host is enabled)cliPath=<path>(optional; absolute path to a runnableopenclawentrypoint or binary)tailnetDns=<magicdns>(optional hint; auto-detected when Tailscale is available)
Sicherheitshinweise:
- Bonjour/mDNS TXT-Records sind unauthentifiziert. Clients müssen TXT-Werte nur als UX-Hinweise behandeln.
- Routing (Host/Port) sollte den aufgelösten Service-Endpunkt (SRV + A/AAAA) gegenüber TXT-basierten Werten wie
lanHost,tailnetDnsodergatewayPortbevorzugen. - TLS-Pinning darf niemals zulassen, dass ein beworbener
gatewayTlsSha256einen zuvor gespeicherten Pin überschreibt. - iOS/Android Nodes sollten Discovery-basierte Direktverbindungen als TLS-only behandeln und eine explizite Bestätigung (“Diesem Fingerprint vertrauen”) verlangen, bevor ein Pin zum ersten Mal gespeichert wird (Out-of-Band-Verifizierung).
Deaktivieren/Überschreiben:
- OPENCLAW_DISABLE_BONJOUR=1 disables advertising.- gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.- OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).- OPENCLAW_TAILNET_DNS publishes a tailnetDns hint (MagicDNS).- OPENCLAW_CLI_PATH overrides the advertised CLI path.2) Tailnet (netzwerkübergreifend)
Abschnitt betitelt „2) Tailnet (netzwerkübergreifend)“Für Setups über verschiedene Standorte hinweg hilft Bonjour nicht weiter. 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).
Die macOS App bevorzugt jetzt MagicDNS-Namen gegenüber rohen Tailscale-IPs für die Gateway-Discovery. Das verbessert die Zuverlässigkeit, wenn sich Tailnet-IPs ändern (zum Beispiel nach Node-Restarts), da MagicDNS-Namen automatisch auf die aktuelle IP auflösen.
3) Manuelles / SSH-Ziel
Abschnitt betitelt „3) Manuelles / 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 forwarden.
Siehe Remote access.
Transport-Auswahl (Client-Policy)
Abschnitt betitelt „Transport-Auswahl (Client-Policy)“Empfohlenes Client-Verhalten:
- Wenn ein gepairter Direct-Endpunkt konfiguriert und erreichbar ist, nutze ihn.
- Andernfalls: Wenn Bonjour ein Gateway im LAN findet, biete eine “Dieses Gateway nutzen”-Option an und speichere es als Direct-Endpunkt.
- Andernfalls: Wenn eine Tailnet DNS/IP konfiguriert ist, versuche die Direktverbindung.
- Andernfalls: Nutze SSH als Fallback.
Pairing + Auth (Direct-Transport)
Abschnitt betitelt „Pairing + Auth (Direct-Transport)“Das Gateway ist die Source of Truth für die Zulassung von Nodes und Clients.
- Pairing-Anfragen werden im Gateway erstellt, genehmigt oder abgelehnt (siehe Gateway pairing).
- Das Gateway erzwingt:
- Auth (Token / Keypair)
- Scopes/ACLs (das Gateway ist kein roher Proxy für jede Methode)
- Rate Limits
Zuständigkeiten nach Komponente
Abschnitt betitelt „Zuständigkeiten nach Komponente“- Gateway: Bewirbt Discovery-Beacons, trifft Pairing-Entscheidungen und hostet den WS-Endpunkt.
- macOS App: Hilft dir bei der Auswahl eines Gateways, zeigt Pairing-Prompts und nutzt SSH nur als Fallback.
- iOS/Android Nodes: Suchen via Bonjour und verbinden sich mit dem gepairten Gateway WS.
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“OpenClaw Expert
Noch festgefahren?
Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.