OpenClaw macOS Companion: Gateway & Node-Steuerung einrichte

Kennst du das? Du willst ein Tool automatisieren, aber macOS blockt dich mit Berechtigungs-Popups ab oder Hintergrundprozesse verschwinden einfach im Nichts. Es ist frustrierend, wenn die Technik dir im Weg steht, anstatt dir zu helfen. Der OpenClaw macOS Companion löst genau diese Probleme und sorgt dafür, dass deine Agenten reibungslos mit deinem Mac interagieren können.

OpenClaw macOS Companion (Menüleiste + Gateway Broker)

Die macOS App ist der Begleiter in der Menüleiste für OpenClaw. Sie verwaltet Berechtigungen, steuert das lokale Gateway (via launchd oder manuell) und stellt dem Agenten macOS-Funktionen als Node zur Verfügung.

Was die App macht

Zeigt native Benachrichtigungen und den Status in der Menüleiste an.
Verwaltet TCC-Abfragen (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
Startet oder verbindet sich mit dem Gateway (lokal oder remote).
Stellt macOS-exklusive Tools bereit (Canvas, Camera, Screen Recording, system.run).
Startet den lokalen Node Host Service im Remote-Modus (launchd) und stoppt ihn im Local-Modus.
Hostet optional die PeekabooBridge für UI-Automatisierung.
Installiert auf Anfrage das globale CLI (openclaw) via npm/pnpm (Bun wird für die Gateway-Runtime nicht empfohlen).

Local vs. Remote Mode

Local (Standard): Die App verbindet sich mit einem laufenden lokalen Gateway, falls vorhanden. Ansonsten aktiviert sie den launchd-Dienst über openclaw gateway install.
Remote: Die App verbindet sich über SSH/Tailscale mit einem Gateway und startet niemals einen lokalen Prozess. Die App startet den lokalen Node Host Service, damit das Remote Gateway diesen Mac erreichen kann. Die App startet das Gateway nicht als Child-Prozess. Die Gateway-Suche bevorzugt jetzt Tailscale MagicDNS-Namen gegenüber rohen Tailnet-IPs, damit die Mac-App zuverlässiger reagiert, wenn sich Tailnet-IPs ändern.

Launchd Steuerung

Die App verwaltet einen LaunchAgent pro Benutzer mit dem Label ai.openclaw.gateway (oder ai.openclaw.<profile>, wenn --profile/OPENCLAW_PROFILE genutzt wird; alte com.openclaw.* Einträge werden weiterhin entfernt).

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

Ersetze das Label durch ai.openclaw.<profile>, wenn du ein benanntes Profil nutzt.

Falls der LaunchAgent nicht installiert ist, aktiviere ihn über die App oder führe openclaw gateway install aus.

Node Capabilities (mac)

Die macOS App präsentiert sich selbst als Node. Häufige Befehle sind:

Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
Camera: camera.snap, camera.clip
Screen: screen.record
System: system.run, system.notify

Der Node meldet eine permissions-Map, damit Agenten entscheiden können, was erlaubt ist.

Node Service + App IPC:

Wenn der Headless Node Host Service läuft (Remote-Modus), verbindet er sich als Node mit dem Gateway WS.
system.run wird in der macOS App (UI/TCC-Kontext) über einen lokalen Unix-Socket ausgeführt; Prompts und Output bleiben in der App.

Diagramm (SCI):

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

Exec Approvals (system.run)

system.run wird über Exec approvals in der macOS App gesteuert (Settings → Exec approvals). Sicherheitseinstellungen, Abfragen und die Allowlist werden lokal auf dem Mac gespeichert:

~/.openclaw/exec-approvals.json

Beispiel:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

Hinweise:

allowlist-Einträge sind Glob-Muster für aufgelöste Binärpfade.
Roher Shell-Befehlstext, der Shell-Steuerungs- oder Erweiterungssyntax enthält (&&, ||, ;, |, `, $, <, >, (, )), wird als Allowlist-Miss behandelt und erfordert eine explizite Genehmigung (oder das Hinzufügen der Shell-Binary zur Allowlist).
Die Auswahl von „Always Allow“ im Prompt fügt diesen Befehl zur Allowlist hinzu.
Umgebungsvariablen-Overrides für system.run werden gefiltert (entfernt PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) und dann mit der Umgebung der App zusammengeführt.
Für Shell-Wrapper (bash|sh|zsh ... -c/-lc) werden die angeforderten Umgebungs-Overrides auf eine kleine explizite Allowlist reduziert (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
Bei „Always Allow“-Entscheidungen im Allowlist-Modus speichern bekannte Dispatch-Wrapper (env, nice, nohup, stdbuf, timeout) die Pfade der inneren ausführbaren Dateien anstelle der Wrapper-Pfade. Wenn das Entpacken nicht sicher ist, wird kein Allowlist-Eintrag automatisch gespeichert.

Deep Links

Die App registriert das openclaw:// URL-Schema für lokale Aktionen.

`openclaw://agent`

Löst eine Gateway agent Anfrage aus.

open 'openclaw://agent?message=Hello%20from%20deep%20link'

Query-Parameter:

message (erforderlich)
sessionKey (optional)
thinking (optional)
deliver / to / channel (optional)
timeoutSeconds (optional)
key (optionaler Key für den Unattended Mode)

Sicherheit:

Ohne key bittet die App um Bestätigung.
Ohne key erzwingt die App ein kurzes Nachrichtenlimit für den Bestätigungs-Prompt und ignoriert deliver / to / channel.
Mit einem gültigen key erfolgt die Ausführung unbeaufsichtigt (gedacht für persönliche Automatisierungen).

Onboarding-Ablauf (typisch)

Installiere und starte OpenClaw.app.
Schließe die Berechtigungs-Checkliste ab (TCC-Prompts).
Stelle sicher, dass der Local-Modus aktiv ist und das Gateway läuft.
Installiere das CLI, wenn du Terminal-Zugriff möchtest.

Speicherort für State (macOS)

Vermeide es, dein OpenClaw State-Verzeichnis in iCloud oder andere Cloud-synchronisierte Ordner zu legen. Synchronisierte Pfade können Latenzen verursachen und führen gelegentlich zu Problemen bei Dateisperren oder Synchronisationskonflikten für Sessions und Zugangsdaten.

Nutze bevorzugt einen lokalen, nicht synchronisierten Pfad wie:

OPENCLAW_STATE_DIR=~/.openclaw

Wenn openclaw doctor State-Daten unter folgenden Pfaden erkennt:

~/Library/Mobile Documents/com~apple~CloudDocs/...
~/Library/CloudStorage/...

wird eine Warnung ausgegeben und empfohlen, zu einem lokalen Pfad zurückzukehren.

Build & Dev Workflow (nativ)

cd apps/macos && swift build
swift run OpenClaw (oder Xcode)
App paketieren: scripts/package-mac-app.sh

Gateway-Verbindung debuggen (macOS CLI)

Verwende das Debug-CLI, um denselben Gateway-WebSocket-Handshake und die Discovery-Logik zu testen, die auch die macOS App nutzt, ohne die App selbst zu starten.

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Optionen für Connect:

--url <ws://host:port>: Config überschreiben
--mode <local|remote>: Aus Config auflösen (Standard: Config oder local)
--probe: Einen frischen Health-Probe erzwingen
--timeout <ms>: Request-Timeout (Standard: 15000)
--json: Strukturierte Ausgabe für Diffs

Optionen für Discovery:

--include-local: Gateways einbeziehen, die sonst als „lokal“ gefiltert würden
--timeout <ms>: Zeitfenster für die Suche (Standard: 2000)
--json: Strukturierte Ausgabe für Diffs

Tipp: Vergleiche dies mit openclaw gateway discover --json, um zu sehen, ob sich die Discovery-Pipeline der macOS App (NWBrowser + tailnet DNS-SD Fallback) von der auf dns-sd basierenden Suche des Node CLI unterscheidet.

Remote-Verbindung (SSH Tunnels)

Wenn die macOS App im Remote-Modus läuft, öffnet sie einen SSH-Tunnel, damit lokale UI-Komponenten mit einem Remote Gateway kommunizieren können, als wäre es auf localhost.

Control Tunnel (Gateway WebSocket Port)

Zweck: Health-Checks, Status, Web Chat, Config und andere Aufrufe der Control-Plane.
Lokaler Port: Der Gateway-Port (Standard 18789), immer stabil.
Remote Port: Derselbe Gateway-Port auf dem Remote-Host.
Verhalten: Kein zufälliger lokaler Port; die App nutzt einen bestehenden gesunden Tunnel oder startet ihn bei Bedarf neu.
SSH-Struktur: ssh -N -L <local>:127.0.0.1:<remote> mit BatchMode + ExitOnForwardFailure + Keepalive-Optionen.
IP-Reporting: Der SSH-Tunnel nutzt Loopback, daher sieht das Gateway die Node-IP als 127.0.0.1. Nutze den Direct (ws/wss) Transport, wenn die echte Client-IP erscheinen soll (siehe macOS remote access).

Für die Einrichtung schau unter macOS remote access nach. Details zum Protokoll findest du unter Gateway protocol.

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.