Fernzugriff (SSH, Tunnel, Tailnets)

Dieses Repo unterstützt „Remote über SSH“, indem ein einzelner Gateway (der Master) auf einem dedizierten Host (Desktop/Server) läuft und Clients sich damit verbinden.

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

Grundidee

• Der Gateway-WebSocket bindet an Loopback auf Ihrem konfigurierten Port (Standard 18789).
• Für Fernnutzung leiten Sie diesen Loopback-Port über SSH weiter (oder nutzen Tailnet/VPN und tunneln weniger).

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

Der Gateway-Host ist „wo der Agent lebt“. Er besitzt Sitzungen, Auth-Profile, Kanäle und State. Ihr Laptop/Desktop (und Nodes) verbinden sich mit diesem Host.

1) Dauerhaft laufender Gateway in Ihrem Tailnet (VPS oder Heimserver)

Gateway auf einem dauerhaft erreichbaren Host betreiben und über Tailscale oder SSH erreichen.

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

Ideal, wenn Ihr Laptop oft schläft, der Agent aber dauerhaft laufen soll.

2) Heim-Desktop betreibt den Gateway, Laptop ist Fernsteuerung

Der Laptop betreibt den Agenten nicht. Er verbindet sich remote:

• Remote über SSH-Modus der macOS-App nutzen (Einstellungen → Allgemein → „OpenClaw läuft“).
• Die App öffnet und verwaltet den Tunnel, WebChat + Health-Checks „funktionieren einfach“.

Runbook: macOS-Fernzugriff.

3) Laptop betreibt den Gateway, Fernzugriff von anderen Rechnern

Gateway lokal halten, aber sicher exponieren:

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

Anleitung: Tailscale und Web-Überblick.

Befehlsfluss (was wo läuft)

Ein Gateway-Dienst besitzt State + Kanäle. Nodes sind Peripherie. Ablauf-Beispiel (Telegram → Node):

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

Hinweise:

• Nodes betreiben keinen Gateway-Dienst. Pro Host sollte nur ein Gateway laufen, außer Sie betreiben bewusst isolierte Profile (siehe Mehrere Gateways).
• Der „Node-Modus“ der macOS-App ist nur ein Node-Client über den Gateway-WebSocket.

SSH-Tunnel (CLI + Tools)

Lokalen Tunnel zum Remote-Gateway-WS anlegen:

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

Mit aktivem Tunnel:

• openclaw health und openclaw status --deep erreichen den Remote-Gateway über ws://127.0.0.1:18789.
• openclaw gateway {status,health,send,agent,call} können bei Bedarf über --url die weitergeleitete URL ansprechen.

Hinweis: 18789 durch Ihren konfigurierten gateway.port (oder --port/CLAWDBOT_GATEWAY_PORT) ersetzen.

CLI-Remote-Standards

Sie können ein Remote-Ziel dauerhaft setzen, damit CLI-Befehle es standardmäßig nutzen:

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

Bei nur-Loopback-Gateway die URL bei ws://127.0.0.1:18789 lassen und zuerst den SSH-Tunnel öffnen.

Chat-UI über SSH

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

• Port 18789 über SSH weiterleiten (siehe oben), dann Clients mit ws://127.0.0.1:18789 verbinden.
• Unter macOS den „Remote über SSH“-Modus der App bevorzugen, der den Tunnel automatisch verwaltet.

macOS-App „Remote über SSH“

Die macOS-Menüleisten-App kann dasselbe Setup End-to-End steuern (Remote-Status-Checks, WebChat, Voice-Wake-Weiterleitung). Runbook: macOS-Fernzugriff.

Sicherheitsregeln (Remote/VPN)

Kurz: Gateway nur auf Loopback lassen, außer Sie brauchen bewusst einen Bind.

• Loopback + SSH/Tailscale Serve ist der sicherste Standard (keine öffentliche Exposition).
• Nicht-Loopback-Binds (lan/tailnet/custom oder auto, wenn Loopback nicht verfügbar) müssen Auth-Token/Passwörter nutzen.
• gateway.remote.token ist nur für Remote-CLI-Aufrufe—er aktiviert keine lokale Auth.
• gateway.remote.tlsFingerprint pinnt das Remote-TLS-Zertifikat bei Nutzung von wss://.
• Tailscale Serve kann sich über Identity-Header authentifizieren, wenn gateway.auth.allowTailscale: true. Auf false setzen, wenn Sie Token/Passwörter wollen.
• Browser-Steuerung wie Operator-Zugriff behandeln: nur Tailnet + bewusstes Node-Pairing.

Vertiefung: Sicherheit.