​

Remote-Zugriff (SSH, Tunnel und Tailnets)

• Für Operatoren (Sie / die macOS-App): SSH-Tunneling ist der universelle Fallback.
• Für Nodes (iOS/Android und zukünftige Geräte): Verbindung zum Gateway-WebSocket herstellen (LAN/Tailnet oder bei Bedarf SSH-Tunnel).

​

Die Grundidee

• Das Gateway WebSocket bindet auf Loopback an Ihren konfigurierten Port (standardmäßig 18789).
• Für die Remote-Nutzung leiten Sie diesen Loopback-Port über SSH weiter (oder verwenden ein Tailnet/VPN und benötigen weniger Tunneling).

​

Gängige VPN-/Tailnet-Setups (wo der Agent lebt)

​

1) Immer aktives Gateway in Ihrem Tailnet (VPS oder Heimserver)

• Beste UX: gateway.bind: "loopback" beibehalten und Tailscale Serve für die Control UI verwenden.
• Fallback: Loopback beibehalten + SSH-Tunnel von jeder Maschine, die Zugriff benötigt.
• Beispiele: exe.dev (einfache VM) oder Hetzner (VPS für Produktion).

​

2) Heim-Desktop führt das Gateway aus, Laptop ist die Remote-Steuerung

• Verwenden Sie den Modus Remote over SSH der macOS-App (Einstellungen → Allgemein → „OpenClaw runs“).
• Die App öffnet und verwaltet den Tunnel, sodass WebChat + Integritätsprüfungen „einfach funktionieren“.

​

3) Laptop führt das Gateway aus, Remote-Zugriff von anderen Maschinen

• SSH-Tunnel zum Laptop von anderen Maschinen aus, oder
• Tailscale Serve für die Control UI und das Gateway nur auf Loopback belassen.

​

Befehlsfluss (was wo ausgeführt wird)

• Eine Telegram-Nachricht trifft beim Gateway ein.
• Das Gateway führt den Agenten aus und entscheidet, ob ein Node-Tool aufgerufen werden soll.
• Das Gateway ruft den Node über das Gateway WebSocket (node.* RPC) auf.
• Der Node gibt das Ergebnis zurück; das Gateway antwortet zurück an Telegram.

• Nodes führen den Gateway-Dienst nicht aus. Es sollte nur ein Gateway pro Host laufen, außer Sie führen absichtlich isolierte Profile aus (siehe Multiple gateways).
• Der „node mode“ der macOS-App ist nur ein Node-Client über das Gateway WebSocket.

​

SSH-Tunnel (CLI + Tools)

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

• openclaw health und openclaw status --deep erreichen jetzt das entfernte Gateway über ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe und openclaw gateway call können bei Bedarf ebenfalls die weitergeleitete URL über --url ansprechen.

​

Standardwerte für CLI-Remote

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

​

Vorrang von Anmeldedaten

• Explizite Anmeldedaten (--token, --password oder Tool-gatewayToken) haben auf Call-Pfaden, die explizite Auth akzeptieren, immer Vorrang.
• Sicherheit bei URL-Überschreibungen:
  • CLI-URL-Überschreibungen (--url) verwenden niemals implizite Konfigurations-/Umgebungs-Anmeldedaten wieder.
  • URL-Überschreibungen per Env (OPENCLAW_GATEWAY_URL) dürfen nur Env-Anmeldedaten verwenden (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standardwerte im lokalen Modus:
  • Token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (der Remote-Fallback gilt nur, wenn die lokale Auth-Token-Eingabe nicht gesetzt ist)
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (der Remote-Fallback gilt nur, wenn die lokale Auth-Passwort-Eingabe nicht gesetzt ist)
• Standardwerte im Remote-Modus:
  • Token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Ausnahme im lokalen Modus von Node-host: gateway.remote.token / gateway.remote.password werden ignoriert.
• Prüfungen von Remote probe/status für Tokens sind standardmäßig strikt: Sie verwenden nur gateway.remote.token (kein lokaler Token-Fallback), wenn der Remote-Modus angesprochen wird.
• Gateway-Env-Überschreibungen verwenden nur OPENCLAW_GATEWAY_*.

​

Chat-UI über SSH

• Leiten Sie 18789 über SSH weiter (siehe oben) und verbinden Sie Clients dann mit ws://127.0.0.1:18789.
• Unter macOS sollten Sie den Modus „Remote over SSH“ der App bevorzugen, der den Tunnel automatisch verwaltet.

​

macOS-App „Remote over SSH“

​

Sicherheitsregeln (remote/VPN)

• Loopback + SSH/Tailscale Serve ist der sicherste Standard (keine öffentliche Exposition).
• Unverschlüsseltes ws:// ist standardmäßig nur auf Loopback erlaubt. Für vertrauenswürdige private Netzwerke setzen Sie OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 im Client-Prozess als Break-Glass.
• Nicht-Loopback-Bindings (lan/tailnet/custom oder auto, wenn Loopback nicht verfügbar ist) müssen Gateway-Auth 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 selbst die Server-Auth.
• Lokale Call-Pfade können gateway.remote.* nur als Fallback verwenden, wenn gateway.auth.* nicht gesetzt ist.
• Wenn gateway.auth.token / gateway.auth.password explizit über SecretRef konfiguriert und nicht aufgelöst werden, schlägt die Auflösung fail-closed fehl (kein Remote-Fallback, der dies verdeckt).
• gateway.remote.tlsFingerprint pinnt das entfernte TLS-Zertifikat bei Verwendung von wss://.
• Tailscale Serve kann den Datenverkehr von Control UI/WebSocket über Identitäts-Header authentifizieren, wenn gateway.auth.allowTailscale: true; HTTP-API-Endpunkte verwenden diese Tailscale-Header-Auth nicht, sondern folgen dem normalen HTTP-Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Setzen Sie dies auf false, wenn Sie überall Shared-Secret-Auth möchten.
• Trusted-proxy-Auth ist nur für Nicht-Loopback-Setups mit identitätsbewusstem Proxy gedacht. Reverse-Proxys auf demselben Host über Loopback erfüllen gateway.auth.mode: "trusted-proxy" nicht.
• Behandeln Sie Browser-Steuerung wie Operatorzugriff: nur Tailnet + bewusstes Node-Pairing.

​

macOS: persistenter SSH-Tunnel über LaunchAgent

​

Schritt 1: SSH-Konfiguration hinzufügen

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

​

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

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

​

Schritt 3: das Gateway-Token konfigurieren

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

​

Schritt 4: den LaunchAgent erstellen

<?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: den LaunchAgent laden

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

​

Fehlerbehebung

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel