Remote OpenClaw (macOS ⇄ Remote-Host)

Dieser Flow ermöglicht es der macOS-App, als vollständige Fernsteuerung für ein OpenClaw-Gateway zu dienen, das auf einem anderen Host (Desktop/Server) läuft. Es ist das Remote über SSH-Feature (Remote Run) der App. Alle Funktionen — Health-Checks, Voice Wake-Weiterleitung und Web-Chat — verwenden dieselbe Remote-SSH-Konfiguration aus Einstellungen → Allgemein.

Modi

Lokal (dieser Mac): Alles läuft auf dem Laptop. Kein SSH beteiligt.
Remote über SSH (Standard): OpenClaw-Befehle werden auf dem Remote-Host ausgeführt. Die Mac-App öffnet eine SSH-Verbindung mit -o BatchMode plus deiner gewählten Identität/Schlüssel und einer lokalen Port-Weiterleitung.
Remote direkt (ws/wss): Kein SSH-Tunnel. Die Mac-App verbindet sich direkt mit der Gateway-URL (zum Beispiel via Tailscale Serve oder einen öffentlichen HTTPS-Reverse-Proxy).

Remote-Transporte

Der Remote-Modus unterstützt zwei Transporte:

SSH-Tunnel (Standard): Verwendet ssh -N -L ... um den Gateway-Port auf localhost weiterzuleiten. Das Gateway sieht die Node-IP als 127.0.0.1, da der Tunnel Loopback ist.
Direkt (ws/wss): Verbindet sich direkt mit der Gateway-URL. Das Gateway sieht die echte Client-IP.

Voraussetzungen auf dem Remote-Host

Node + pnpm installieren und die OpenClaw-CLI bauen/installieren (pnpm install && pnpm build && pnpm link --global).
Stelle sicher, dass openclaw im PATH für nicht-interaktive Shells ist (Symlink nach /usr/local/bin oder /opt/homebrew/bin falls nötig).
SSH mit Key-Auth öffnen. Wir empfehlen Tailscale-IPs für stabile Erreichbarkeit außerhalb des LANs.

macOS-App einrichten

Öffne Einstellungen → Allgemein.
Unter OpenClaw runs wähle Remote über SSH und setze:
- Transport: SSH-Tunnel oder Direkt (ws/wss).
- SSH-Ziel: user@host (optional :port).
  - Falls das Gateway im selben LAN ist und Bonjour bewirbt, wähle es aus der entdeckten Liste, um dieses Feld automatisch auszufüllen.
- Gateway-URL (nur Direkt): wss://gateway.example.ts.net (oder ws://... für lokal/LAN).
- Identity-Datei (erweitert): Pfad zu deinem Schlüssel.
- Projekt-Root (erweitert): Remote-Checkout-Pfad für Befehle.
- CLI-Pfad (erweitert): optionaler Pfad zu einem ausführbaren openclaw-Entrypoint/Binary (automatisch ausgefüllt wenn beworben).
Klicke auf Remote testen. Erfolg bedeutet, dass openclaw status --json auf dem Remote korrekt läuft. Fehler bedeuten meist PATH/CLI-Probleme; Exit-Code 127 heißt, die CLI wurde remote nicht gefunden.
Health-Checks und Web-Chat laufen jetzt automatisch über diesen SSH-Tunnel.

Web-Chat

SSH-Tunnel: Web-Chat verbindet sich über den weitergeleiteten WebSocket-Control-Port mit dem Gateway (Standard 18789).
Direkt (ws/wss): Web-Chat verbindet sich direkt mit der konfigurierten Gateway-URL.
Es gibt keinen separaten WebChat-HTTP-Server mehr.

Berechtigungen

Der Remote-Host braucht dieselben TCC-Genehmigungen wie lokal (Automation, Bedienungshilfen, Bildschirmaufnahme, Mikrofon, Spracherkennung, Benachrichtigungen). Führe das Onboarding auf diesem Rechner aus, um sie einmalig zu erteilen.
Nodes bewerben ihren Berechtigungsstatus via node.list / node.describe, damit Agenten wissen, was verfügbar ist.

Sicherheitshinweise

Bevorzuge Loopback-Bindings auf dem Remote-Host und verbinde dich via SSH oder Tailscale.
SSH-Tunneling nutzt strikte Host-Key-Prüfung; vertraue dem Host-Key zuerst, damit er in ~/.ssh/known_hosts existiert.
Wenn du das Gateway an ein Nicht-Loopback-Interface bindest, verlange Token/Passwort-Auth.
Siehe Sicherheit und Tailscale.

Führe openclaw channels login --verbose auf dem Remote-Host aus. Scanne den QR mit WhatsApp auf deinem Handy.
Führe Login erneut auf diesem Host aus, wenn die Auth abläuft. Der Health-Check zeigt Link-Probleme an.

Fehlerbehebung

Exit 127 / not found: openclaw ist nicht im PATH für Nicht-Login-Shells. Füge es zu /etc/paths, deiner Shell-RC hinzu, oder verlinke es nach /usr/local/bin//opt/homebrew/bin.
Health-Probe fehlgeschlagen: Prüfe SSH-Erreichbarkeit, PATH und ob Baileys eingeloggt ist (openclaw status --json).
Web-Chat hängt: Bestätige, dass das Gateway auf dem Remote-Host läuft und der weitergeleitete Port dem Gateway-WS-Port entspricht; die UI benötigt eine gesunde WS-Verbindung.
Node-IP zeigt 127.0.0.1: Das ist beim SSH-Tunnel erwartet. Wechsle Transport zu Direkt (ws/wss), wenn das Gateway die echte Client-IP sehen soll.
Voice Wake: Trigger-Phrasen werden im Remote-Modus automatisch weitergeleitet; kein separater Forwarder nötig.

Benachrichtigungstöne

Wähle Töne pro Benachrichtigung aus Skripten mit openclaw und node.invoke, z. B.:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Es gibt keinen globalen „Standard-Ton”-Toggle in der App mehr; Aufrufer wählen einen Ton (oder keinen) pro Anfrage.