Remote-Zugriff auf dein Gateway: SSH, Tunnel und Tailnets

Kennst du das? Dein Setup läuft perfekt auf deinem Rechner zu Hause, aber sobald du unterwegs bist, verlierst du den Zugriff. Es ist frustrierend, wenn man technische Hürden überwinden muss, nur um kurz den Status zu prüfen oder eine Nachricht zu senden.

Den Fernzugriff sicher und stabil einzurichten, kann nerven. In diesem Guide zeige ich dir, wie du dein Gateway über SSH oder Tailscale erreichst, ohne die Sicherheit zu opfern oder dich in komplexen Konfigurationen zu verlieren.

Fernzugriff (SSH, Tunnel und Tailnets)

Dieses Repo unterstützt „Remote over SSH“, indem ein einzelnes Gateway (der Master) auf einem dedizierten Host (Desktop/Server) läuft und Clients damit verbunden werden.

• Für Operator (dich / die macOS App): SSH-Tunneling ist die universelle Lösung, wenn nichts anderes geht.
• Für Nodes (iOS/Android und zukünftige Geräte): Verbinde dich mit dem Gateway WebSocket (LAN/Tailnet oder SSH-Tunnel, je nach Bedarf).

Die Kernidee

• Der Gateway WebSocket bindet sich an den loopback auf deinem konfigurierten Port (Standard ist 18789).
• Für die Remote-Nutzung leitest du diesen Loopback-Port über SSH weiter (oder nutzt ein Tailnet/VPN und tunnelst weniger).

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

Betrachte den Gateway-Host als den Ort, „wo der Agent lebt“. Er besitzt die Sessions, Auth-Profile, Kanäle und den State. Dein Laptop/Desktop (und die Nodes) verbinden sich mit diesem Host.

1) Always-on Gateway in deinem Tailnet (VPS oder Home-Server)

Lass das Gateway auf einem permanent verfügbaren Host laufen und erreiche es über Tailscale oder SSH.

• Beste UX: Behalte gateway.bind: "loopback" bei und nutze Tailscale Serve für das Control UI.
• Fallback: Nutze Loopback + SSH-Tunnel von jedem Rechner aus, der Zugriff benötigt.
• Beispiele: exe.dev (einfache VM) oder Hetzner (Produktions-VPS).

Das ist ideal, wenn dein Laptop oft im Ruhezustand ist, du den Agent aber immer online haben willst.

2) Home-Desktop lässt das Gateway laufen, Laptop ist die Fernsteuerung

Der Laptop lässt den Agent nicht laufen. Er verbindet sich remote:

• Nutze den Remote over SSH Modus der macOS App (Settings → General → „OpenClaw runs“).
• Die App öffnet und verwaltet den Tunnel, sodass WebChat + Health-Checks einfach funktionieren.

Runbook: macOS Remote-Zugriff.

3) Laptop lässt das Gateway laufen, Fernzugriff von anderen Geräten

Behalte das Gateway lokal, aber gib es sicher frei:

• SSH-Tunnel zum Laptop von anderen Geräten aus, oder
• Tailscale Serve für das Control UI nutzen und das Gateway auf Loopback-only lassen.

Guide: Tailscale und Web-Übersicht.

Befehlsfluss (was wo läuft)

Ein Gateway-Service besitzt State + Kanäle. Nodes sind Peripheriegeräte.

Beispiel für den Fluss (Telegram → Node):

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

Hinweise:

• Nodes lassen den Gateway-Service nicht laufen. Es sollte nur ein Gateway pro Host laufen, außer du betreibst absichtlich isolierte Profile (siehe Multiple Gateways).
• Der „Node-Modus“ der macOS App ist nur ein Node-Client über den Gateway WebSocket.

SSH-Tunnel (CLI + Tools)

Erstelle einen lokalen Tunnel zum entfernten Gateway WS:

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

Wenn der Tunnel steht:

• openclaw health und openclaw status --deep erreichen nun das Remote-Gateway über ws://127.0.0.1:18789.
• openclaw gateway {status,health,send,agent,call} kann bei Bedarf auch die weitergeleitete URL über --url ansteuern.

Hinweis: Ersetze 18789 durch deinen konfigurierten gateway.port (oder --port/OPENCLAW_GATEWAY_PORT). Hinweis: Wenn du --url übergibst, nutzt die CLI keine Standard-Zugangsdaten aus der Config oder Umgebungsvariablen. Gib --token oder --password explizit an. Fehlende explizite Zugangsdaten führen zu einem Fehler.

CLI-Remote-Standardwerte

Du kannst ein Remote-Ziel dauerhaft speichern, damit CLI-Befehle es standardmäßig nutzen:

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

Wenn das Gateway auf Loopback-only steht, lass die URL auf ws://127.0.0.1:18789 und öffne zuerst den SSH-Tunnel.

Priorität der Zugangsdaten

Die Auflösung der Gateway-Zugangsdaten folgt einem gemeinsamen Vertrag über Call/Probe/Status-Pfade und die Discord-Freigabe-Überwachung. Der Node-Host nutzt denselben Basisvertrag mit einer Ausnahme für den Local-Mode (er ignoriert absichtlich gateway.remote.*):

• Explizite Zugangsdaten (--token, --password oder Tool gatewayToken) gewinnen immer bei Pfaden, die explizite Authentifizierung akzeptieren.
• Sicherheit bei URL-Overrides:
  • CLI URL-Overrides (--url) verwenden niemals implizite Config/Env-Zugangsdaten.
  • Env URL-Overrides (OPENCLAW_GATEWAY_URL) dürfen nur Env-Zugangsdaten nutzen (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Standardwerte im Local-Mode:
  • Token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (Remote-Fallback greift nur, wenn der lokale Auth-Token nicht gesetzt ist).
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (Remote-Fallback greift nur, wenn das lokale Auth-Passwort nicht gesetzt ist).
• Standardwerte im Remote-Mode:
  • Token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • Passwort: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Node-Host Local-Mode Ausnahme: gateway.remote.token / gateway.remote.password werden ignoriert.
• Remote Probe/Status Token-Checks sind standardmäßig streng: Sie nutzen nur gateway.remote.token (kein lokaler Token-Fallback), wenn der Remote-Mode anvisiert wird.
• Gateway Env-Overrides nutzen ausschließlich OPENCLAW_GATEWAY_*.

Chat-UI über SSH

WebChat nutzt keinen separaten HTTP-Port mehr. Das SwiftUI Chat-UI verbindet sich direkt mit dem Gateway WebSocket.

• Leite 18789 über SSH weiter (siehe oben) und verbinde Clients dann mit ws://127.0.0.1:18789.
• Bevorzuge auf macOS den „Remote over SSH“ Modus der App, der den Tunnel automatisch verwaltet.

macOS App „Remote over SSH“

Die macOS Menüleisten-App kann dasselbe Setup komplett steuern (Remote-Status-Checks, WebChat und Voice Wake Forwarding).

Runbook: macOS Remote-Zugriff.

Sicherheitsregeln (Remote/VPN)

Kurzfassung: Lass das Gateway auf Loopback-only, außer du bist sicher, dass du ein Bind benötigst.

• Loopback + SSH/Tailscale Serve ist der sicherste Standard (keine öffentliche Erreichbarkeit).
• Unverschlüsseltes ws:// ist standardmäßig nur für Loopback vorgesehen. Für vertrauenswürdige private Netzwerke setze OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 im Client-Prozess als Notlösung.
• Non-loopback Binds (lan/tailnet/custom oder auto, wenn Loopback nicht verfügbar ist) müssen Auth-Token/Passwörter verwenden.
• gateway.remote.token / .password sind Quellen für Client-Zugangsdaten. Sie konfigurieren nicht selbstständig die Server-Authentifizierung.
• Lokale Call-Pfade können gateway.remote.* nur als Fallback nutzen, wenn gateway.auth.* nicht gesetzt ist.
• Wenn gateway.auth.token / gateway.auth.password explizit über SecretRef konfiguriert und nicht aufgelöst werden kann, schlägt die Auflösung fehl (kein Maskieren durch Remote-Fallback).
• gateway.remote.tlsFingerprint pinnt das Remote-TLS-Zertifikat bei der Nutzung von wss://.
• Tailscale Serve kann Control UI/WebSocket-Traffic über Identity-Header authentifizieren, wenn gateway.auth.allowTailscale: true gesetzt ist; HTTP-API-Endpunkte erfordern weiterhin Token/Passwort-Authentifizierung. Dieser tokenlose Fluss setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Setze dies auf false, wenn du überall Token/Passwörter willst.
• Behandle die Browser-Steuerung wie Operator-Zugriff: Nur über Tailnet + bewusste Node-Kopplung.

Deep Dive: Sicherheit.

macOS: Permanenter SSH-Tunnel via LaunchAgent

Für macOS-Clients, die sich mit einem Remote-Gateway verbinden, ist der einfachste Weg ein SSH LocalForward Eintrag in der Config zusammen mit einem LaunchAgent, der den Tunnel bei Neustarts oder Abstürzen aktiv hält.

Schritt 1: SSH-Config hinzufügen

Bearbeite ~/.ssh/config:

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

Ersetze <REMOTE_IP> und <REMOTE_USER> durch deine Werte.

Schritt 2: SSH-Key kopieren (einmalig)

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

Schritt 3: Gateway-Token konfigurieren

Speichere den Token in der Config, damit er über Neustarts hinweg erhalten bleibt:

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

Schritt 4: LaunchAgent erstellen

Speichere dies 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 startet automatisch beim Login, startet bei Abstürzen neu und hält den weitergeleiteten Port aktiv.

Hinweis: Falls du noch einen alten com.openclaw.ssh-tunnel LaunchAgent hast, entlade und lösche ihn.

Fehlerbehebung

Prüfe, ob der Tunnel läuft:

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

Tunnel neu starten:

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

Tunnel stoppen:

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

Config-Eintrag	Funktion
LocalForward 18789 127.0.0.1:18789	Leitet den lokalen Port 18789 an den Remote-Port 18789 weiter
ssh -N	SSH ohne Ausführung von Remote-Befehlen (nur Port-Forwarding)
KeepAlive	Startet den Tunnel automatisch neu, falls er abstürzt
RunAtLoad	Startet den Tunnel, wenn der LaunchAgent beim Login geladen wird

Nächste Schritte

• Sicherheit
• macOS Remote-Zugriff

AI Setup Assistant