Fernzugriff

OpenClaw führt einen Gateway (den Master) auf einem Host aus und verbindet jeden Client damit. Der Gateway verwaltet Sitzungen, Authentifizierungsprofile, Kanäle und Zustand; alles andere ist ein Client.

• Operatoren (Sie oder die macOS-App): Eine direkte LAN-/Tailnet-WebSocket-Verbindung ist am einfachsten, wenn der Gateway erreichbar ist; SSH-Tunneling ist die universelle Ausweichlösung.
• Nodes (iOS/Android und andere Geräte): Stellen eine Verbindung zum WebSocket des Gateways her (LAN/Tailnet oder SSH-Tunnel).

Das Grundprinzip

Der Gateway-WebSocket bindet standardmäßig auf Port 18789 (gateway.port) an Loopback. Für die Remote-Nutzung können Sie ihn entweder über Tailscale Serve bzw. eine vertrauenswürdige LAN-/Tailnet-Bindung verfügbar machen oder den Loopback-Port über SSH weiterleiten.

Topologieoptionen

Für dauerhaft aktive und Laptop-Einrichtungen sollten Sie vorzugsweise gateway.bind: "loopback" beibehalten und Tailscale Serve für die Control UI oder eine vertrauenswürdige LAN-/Tailnet-Bindung mit gateway.remote.transport: "direct" verwenden. Ein SSH-Tunnel ist die Ausweichlösung, die von jedem Computer aus funktioniert.

Befehlsablauf (was wo ausgeführt wird)

Ein Gateway verwaltet Zustand und Kanäle; Nodes sind Peripheriegeräte. Beispiel (eine Telegram-Nachricht wird an ein Node-Tool weitergeleitet):

1. Die Telegram-Nachricht trifft beim Gateway ein.
2. Der Gateway führt den Agent aus, der entscheidet, ob ein Node-Tool aufgerufen werden soll.
3. Der Gateway ruft den Node über den Gateway-WebSocket auf (node.invoke-RPC).
4. Der Node gibt das Ergebnis zurück; der Gateway antwortet über Telegram.

Nodes führen den Gateway-Dienst nicht aus. Pro Host sollte nur ein Gateway ausgeführt werden, sofern Sie nicht absichtlich isolierte Profile verwenden (siehe Mehrere Gateways). Der „Node-Modus“ der macOS-App ist lediglich ein Node-Client, der den Gateway-WebSocket verwendet.

SSH-Tunnel (CLI + Tools)

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Bei aktivem Tunnel erreichen openclaw health und openclaw status --deep den Remote-Gateway über ws://127.0.0.1:18789. openclaw gateway status, openclaw gateway health, openclaw gateway probe und openclaw gateway call können über --url ebenfalls eine weitergeleitete URL ansprechen.

Remote-Standardeinstellungen der CLI

Speichern Sie ein Remote-Ziel dauerhaft, damit CLI-Befehle es standardmäßig verwenden:

{  gateway: {    mode: "remote",    remote: {      url: "ws://127.0.0.1:18789",      token: "your-token",    },  },}

Wenn der Gateway ausschließlich an Loopback gebunden ist, behalten Sie für die URL ws://127.0.0.1:18789 bei und öffnen Sie zuerst den SSH-Tunnel. Beim SSH-Tunnel-Transport der macOS-App wird der erkannte Gateway-Hostname in gateway.remote.sshTarget eingetragen (user@host oder user@host:port); gateway.remote.url bleibt die lokale Tunnel-URL. Wenn sich der Remote-Port vom lokalen Port unterscheidet, legen Sie gateway.remote.remotePort fest.

Die Hostschlüsselüberprüfung ist standardmäßig strikt (gateway.remote.sshHostKeyPolicy: "strict"). Legen Sie den Wert auf "openssh" fest, um sie stattdessen an Ihre effektive OpenSSH-Konfiguration zu delegieren; prüfen Sie vor der Aktivierung Ihre benutzerspezifischen und systemweiten SSH-Einstellungen.

Verwenden Sie für einen Gateway, der bereits über ein vertrauenswürdiges LAN oder Tailnet erreichbar ist, den direkten Modus:

{  gateway: {    mode: "remote",    remote: {      transport: "direct",      url: "ws://192.168.0.202:18789",      token: "your-token",    },  },}

Rangfolge der Anmeldedaten

Die Auflösung der Gateway-Anmeldedaten folgt für Aufruf-, Prüf- und Statuspfade sowie die Überwachung von Discord-Ausführungsgenehmigungen einem gemeinsamen Vertrag. Der Node-Host verwendet denselben Vertrag mit einer Ausnahme im lokalen Modus (er ignoriert gateway.remote.*).

• Explizite Anmeldedaten (--token, --password oder gatewayToken eines Tools) haben auf Aufrufpfaden, die explizite Authentifizierung akzeptieren, immer Vorrang.
• Sicherheit bei URL-Überschreibungen:
  • CLI---url verwendet niemals implizite Anmeldedaten aus Konfiguration oder Umgebung erneut.
  • Umgebungsvariable OPENCLAW_GATEWAY_URL darf nur Umgebungs-Anmeldedaten verwenden (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standardeinstellungen des lokalen Modus:
  • Token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (Remote-Ausweichwert nur, wenn das lokale Token nicht gesetzt ist)
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (Remote-Ausweichwert nur, wenn das lokale Passwort nicht gesetzt ist)
• Standardeinstellungen des Remote-Modus:
  • Token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Ausnahme des lokalen Modus für Node-Hosts: gateway.remote.token / gateway.remote.password werden ignoriert.
• Token-Prüfungen für Remote-Prüfungen und -Status sind standardmäßig strikt: Beim Ansprechen des Remote-Modus verwenden sie ausschließlich gateway.remote.token (kein Rückgriff auf ein lokales Token).
• Umgebungsüberschreibungen des Gateways verwenden ausschließlich OPENCLAW_GATEWAY_*.

Remote-Zugriff auf die Chat-Benutzeroberfläche

WebChat besitzt keinen separaten HTTP-Port; die SwiftUI-Chat-Benutzeroberfläche stellt eine direkte Verbindung zum Gateway-WebSocket her.

• Leiten Sie 18789 über SSH weiter (siehe oben) und verbinden Sie die Clients anschließend mit ws://127.0.0.1:18789.
• Verbinden Sie Clients im direkten LAN-/Tailnet-Modus mit der konfigurierten privaten URL ws:// oder der sicheren URL wss://.
• Unter macOS verwaltet der Remote-Modus der App den ausgewählten Transport automatisch.

Remote-Modus der macOS-App

Die macOS-Menüleisten-App steuert dieselbe Einrichtung vollständig: Remote-Statusprüfungen, WebChat und die Weiterleitung von Voice Wake. Anleitung: macOS-Remote-Zugriff.

Sicherheitsregeln (Remote/VPN)

Lassen Sie den Gateway ausschließlich an Loopback gebunden, sofern Sie nicht sicher sind, dass Sie eine andere Bindung benötigen.

• Loopback + SSH/Tailscale Serve ist die sicherste Standardeinstellung (keine öffentliche Erreichbarkeit).
• Unverschlüsseltes ws:// wird für Loopback, private/LAN-Adressen (RFC 1918), Link-Local-Adressen, CGNAT sowie Hosts unter .local und .ts.net akzeptiert. Öffentliche Remote-Hosts müssen wss:// verwenden.
• Nicht-Loopback-Bindungen (lan/tailnet/custom oder auto, wenn Loopback nicht verfügbar ist) müssen eine Gateway-Authentifizierung verwenden: Token, Passwort oder einen identitätsbewussten Reverse-Proxy mit gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password sind Quellen für Client-Anmeldedaten; sie konfigurieren nicht eigenständig die Serverauthentifizierung.
• Lokale Aufrufpfade dürfen nur dann ersatzweise gateway.remote.* verwenden, wenn gateway.auth.* nicht gesetzt ist.
• Wenn gateway.auth.token / gateway.auth.password explizit über SecretRef konfiguriert ist und nicht aufgelöst werden kann, schlägt die Auflösung geschlossen fehl (keine Verschleierung durch einen Remote-Ausweichwert).
• gateway.remote.tlsFingerprint fixiert das Remote-TLS-Zertifikat für wss://, einschließlich des Operator-/Steuerungsverkehrs und des begleitenden Nodes im direkten macOS-Modus. Ohne gespeicherte Fixierung fixiert macOS das Zertifikat bei der ersten Verwendung erst, nachdem die normale Systemvertrauensprüfung bestanden wurde; Gateways mit selbst signierten Zertifikaten oder privater CA benötigen einen expliziten Fingerabdruck oder „Remote über SSH“.
• Tailscale Serve kann den Datenverkehr der Control UI und des WebSockets über Identitätsheader authentifizieren, wenn gateway.auth.allowTailscale: true. HTTP-API-Endpunkte verwenden diese Header-Authentifizierung nicht, sondern folgen dem normalen HTTP-Authentifizierungsmodus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass der Gateway-Host vertrauenswürdig ist; legen Sie den Wert auf false fest, um überall die Authentifizierung über ein gemeinsames Geheimnis zu verwenden.
• Die Trusted-Proxy-Authentifizierung erwartet standardmäßig einen identitätsbewussten Proxy außerhalb von Loopback. Loopback-Reverse-Proxys auf demselben Host erfordern ausdrücklich gateway.auth.trustedProxy.allowLoopback = true.
• Behandeln Sie die Browser-Steuerung wie Operatorzugriff: ausschließlich über das Tailnet und mit bewusster Node-Kopplung.

Ausführliche Informationen: Sicherheit.

macOS: persistenter SSH-Tunnel über LaunchAgent

Für macOS-Clients verwendet die einfachste persistente Einrichtung einen SSH-Konfigurationseintrag LocalForward sowie einen LaunchAgent, der den Tunnel über Neustarts und Abstürze hinweg aktiv hält.

Schritt 1: SSH-Konfiguration hinzufügen

Bearbeiten Sie ~/.ssh/config:

Host remote-gateway    HostName <REMOTE_IP>    User <REMOTE_USER>    LocalForward 18789 127.0.0.1:18789    IdentityFile ~/.ssh/id_rsa

Ersetzen Sie <REMOTE_IP> und <REMOTE_USER> durch Ihre Werte.

Schritt 2: SSH-Schlüssel kopieren (einmalig)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

Schritt 3: Gateway-Token konfigurieren

openclaw config set gateway.remote.token "<your-token>"

Verwenden Sie stattdessen gateway.remote.password, wenn der Remote-Gateway eine Passwortauthentifizierung verwendet. OPENCLAW_GATEWAY_TOKEN ist weiterhin als Überschreibung auf Shell-Ebene gültig, die dauerhafte Einrichtung des Remote-Clients erfolgt jedoch über gateway.remote.token / gateway.remote.password.

Schritt 4: LaunchAgent erstellen

Speichern Sie die Datei als ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>    <key>Label</key>    <string>ai.openclaw.ssh-tunnel</string>    <key>ProgramArguments</key>    <array>        <string>/usr/bin/ssh</string>        <string>-N</string>        <string>remote-gateway</string>    </array>    <key>KeepAlive</key>    <true/>    <key>RunAtLoad</key>    <true/></dict></plist>

Schritt 5: LaunchAgent laden

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

Der Tunnel wird bei der Anmeldung automatisch gestartet, nach einem Absturz neu gestartet und hält den weitergeleiteten Port verfügbar.

Fehlerbehebung

# Prüfen, ob der Tunnel ausgeführt wirdps aux | grep "ssh -N remote-gateway" | grep -v greplsof -i :18789 # Tunnel neu startenlaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Tunnel stoppenlaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

Verwandte Themen

• Tailscale
• Authentifizierung
• Einrichtung eines Remote-Gateways