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 sich damit verbinden.

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

Die Grundidee

  • Der Gateway WebSocket bindet sich an Loopback auf deinem konfigurierten Port (Standard: 18789).
  • Für 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 lebt)

Stell dir den Gateway-Host als “wo der Agent lebt” vor. Er verwaltet Sessions, Auth-Profile, Channels und State. Dein Laptop/Desktop (und Nodes) verbinden sich mit diesem Host.

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

Betreibe das Gateway auf einem dauerhaft laufenden Host und erreiche es via Tailscale oder SSH.

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

Das ist ideal, wenn dein Laptop oft schläft, du aber den Agent immer erreichbar haben willst.

2) Home-Desktop betreibt das Gateway, Laptop ist Fernsteuerung

Der Laptop führt den Agent nicht aus. 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 Fernzugriff.

3) Laptop betreibt das Gateway, Fernzugriff von anderen Rechnern

Behalte das Gateway lokal, aber exponiere es sicher:

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

Guide: Tailscale und Web-Übersicht.

Befehlsfluss (was läuft wo)

Ein Gateway-Service verwaltet State + Channels. Nodes sind Peripheriegeräte.

Beispiel-Flow (Telegram → Node):

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

Hinweise:

  • Nodes betreiben keinen Gateway-Service. Pro Host sollte nur ein Gateway laufen, es sei denn, du betreibst absichtlich isolierte Profile (siehe Mehrere 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 Remote Gateway WS:

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

Mit aktivem Tunnel:

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

Hinweis: Ersetze 18789 durch deinen konfigurierten gateway.port (oder --port/OPENCLAW_GATEWAY_PORT).

CLI Remote-Defaults

Du kannst ein Remote-Ziel 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 nur auf Loopback läuft, behalte die URL bei ws://127.0.0.1:18789 und öffne zuerst den SSH-Tunnel.

Chat UI über SSH

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

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

macOS-App “Remote over SSH”

Die macOS-Menüleisten-App kann das komplette Setup steuern (Remote-Status-Checks, WebChat und Voice Wake-Weiterleitung).

Runbook: macOS Fernzugriff.

Sicherheitsregeln (Remote/VPN)

Kurzfassung: Behalte das Gateway auf Loopback, es sei denn, du brauchst wirklich einen Bind.

  • Loopback + SSH/Tailscale Serve ist der sicherste Standard (keine öffentliche Exposition).
  • Non-Loopback-Binds (lan/tailnet/custom, oder auto wenn Loopback nicht verfügbar) müssen Auth-Tokens/Passwörter verwenden.
  • gateway.remote.token ist nur für Remote-CLI-Aufrufe — es aktiviert keine lokale Auth.
  • gateway.remote.tlsFingerprint pinnt das Remote-TLS-Zertifikat bei Verwendung von wss://.
  • Tailscale Serve kann via Identity-Header authentifizieren, wenn gateway.auth.allowTailscale: true. Setze es auf false, wenn du stattdessen Tokens/Passwörter willst.
  • Behandle Browser-Kontrolle wie Operator-Zugriff: nur Tailnet + bewusstes Node-Pairing.

Deep Dive: Sicherheit.