Remote OpenClaw (macOS ⇄ Remote-Host)

Mit diesem Workflow kannst du die macOS-App als vollständige Fernsteuerung für ein OpenClaw Gateway nutzen, das auf einem anderen Host (Desktop/Server) läuft. Das ist die Remote over SSH-Funktion der App. Alle Features – Health Checks, Voice Wake Forwarding und Web Chat – nutzen die gleiche Remote-SSH-Konfiguration aus Settings → General.

Modi

  • Local (this Mac): Alles läuft auf dem Laptop. Kein SSH beteiligt.
  • Remote over SSH (Standard): OpenClaw-Befehle werden auf dem Remote-Host ausgeführt. Die Mac-App öffnet eine SSH-Verbindung mit -o BatchMode plus deinem gewählten Identity-File/Key und einem lokalen Port-Forward.
  • Remote direct (ws/wss): Kein SSH-Tunnel. Die Mac-App verbindet sich direkt mit der Gateway-URL (z. B. über Tailscale Serve oder einen öffentlichen HTTPS-Reverse-Proxy).

Remote-Transporte

Der Remote-Modus unterstützt zwei Transporte:

  • SSH tunnel (Standard): Nutzt ssh -N -L ..., um den Gateway-Port auf localhost weiterzuleiten. Das Gateway sieht die Node-IP als 127.0.0.1, weil der Tunnel über Loopback läuft.
  • Direct (ws/wss): Verbindet sich direkt mit der Gateway-URL. Das Gateway sieht die echte Client-IP.

Voraussetzungen auf dem Remote-Host

  1. Installiere Node + pnpm und baue/installiere die OpenClaw CLI (pnpm install && pnpm build && pnpm link --global).
  2. Stelle sicher, dass openclaw im PATH für nicht-interaktive Shells liegt (erstelle bei Bedarf einen Symlink nach /usr/local/bin oder /opt/homebrew/bin).
  3. Aktiviere SSH mit Key-Authentifizierung. Wir empfehlen Tailscale-IPs für stabile Erreichbarkeit außerhalb des LANs.

macOS-App-Setup

  1. Öffne Settings → General.
  2. Unter OpenClaw runs wählst du Remote over SSH und konfigurierst:
    • Transport: SSH tunnel oder Direct (ws/wss).
    • SSH target: user@host (optional :port).
      • Wenn das Gateway im gleichen LAN ist und Bonjour nutzt, kannst du es aus der Liste der entdeckten Geräte auswählen, um dieses Feld automatisch auszufüllen.
    • Gateway URL (nur bei Direct): wss://gateway.example.ts.net (oder ws://... für lokal/LAN).
    • Identity file (erweitert): Pfad zu deinem Key.
    • Project root (erweitert): Remote-Checkout-Pfad für Befehle.
    • CLI path (erweitert): optionaler Pfad zu einem ausführbaren openclaw-Entrypoint/Binary (wird automatisch ausgefüllt, wenn verfügbar).
  3. Klicke auf Test remote. Bei Erfolg läuft openclaw status --json auf dem Remote-Host korrekt. Fehler bedeuten meist PATH/CLI-Probleme; Exit-Code 127 heißt, dass die CLI remote nicht gefunden wurde.
  4. Health Checks und Web Chat laufen jetzt automatisch über diesen SSH-Tunnel.

Web Chat

  • SSH tunnel: Web Chat verbindet sich mit dem Gateway über den weitergeleiteten WebSocket-Control-Port (Standard: 18789).
  • Direct (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 die gleichen TCC-Freigaben wie lokal (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Führe das Onboarding auf dieser Maschine aus, um sie einmalig zu erteilen.
  • Nodes teilen ihren Berechtigungsstatus über node.list / node.describe mit, damit Agents wissen, was verfügbar ist.

Sicherheitshinweise

  • Bevorzuge Loopback-Binds auf dem Remote-Host und verbinde dich über SSH oder Tailscale.
  • Wenn du das Gateway an ein Nicht-Loopback-Interface bindest, aktiviere Token/Passwort-Authentifizierung.
  • Siehe Security und Tailscale.

WhatsApp-Login-Flow (remote)

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

Troubleshooting

  • exit 127 / not found: openclaw ist nicht im PATH für Non-Login-Shells. Füge es zu /etc/paths, deiner Shell-RC hinzu oder erstelle einen Symlink nach /usr/local/bin//opt/homebrew/bin.
  • Health probe failed: Prüfe die SSH-Erreichbarkeit, den PATH und ob Baileys eingeloggt ist (openclaw status --json).
  • Web Chat stuck: Bestätige, dass das Gateway auf dem Remote-Host läuft und der weitergeleitete Port mit dem Gateway-WS-Port übereinstimmt; die UI braucht eine funktionierende WS-Verbindung.
  • Node IP shows 127.0.0.1: Das ist normal beim SSH-Tunnel. Wechsle den Transport zu Direct (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-Sound”-Schalter in der App mehr; Aufrufer wählen pro Anfrage einen Sound (oder keinen).