​

OpenClaw macOS-Begleiter (Menüleiste + Gateway-Broker)

​

Was sie macht

• Zeigt native Benachrichtigungen und Status in der Menüleiste an.
• Verwaltet TCC-Aufforderungen (Benachrichtigungen, Bedienungshilfen, Bildschirmaufnahme, Mikrofon, Speech Recognition, Automation/AppleScript).
• Führt das Gateway aus oder verbindet sich damit (lokal oder remote).
• Stellt nur unter macOS verfügbare Tools bereit (Canvas, Kamera, Bildschirmaufnahme, system.run).
• Startet den lokalen Node-Host-Service im Remote-Modus (launchd) und stoppt ihn im Local-Modus.
• Hostet optional PeekabooBridge für UI-Automatisierung.
• Installiert auf Anfrage die globale CLI (openclaw) über npm, pnpm oder bun (die App bevorzugt npm, dann pnpm, dann bun; Node bleibt die empfohlene Gateway-Laufzeitumgebung).

​

Local- vs. Remote-Modus

• Local (Standard): Die App stellt eine Verbindung zu einem laufenden lokalen Gateway her, falls vorhanden; andernfalls aktiviert sie den launchd-Service ü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. Bei der Gateway-Erkennung werden jetzt Tailscale MagicDNS-Namen gegenüber rohen Tailnet-IP-Adressen bevorzugt, sodass sich die Mac-App zuverlässiger erholt, wenn sich Tailnet-IP-Adressen ändern.

​

Launchd-Steuerung

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

​

Node-Funktionen (mac)

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

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

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

​

Exec approvals (system.run)

~/.openclaw/exec-approvals.json

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

• allowlist-Einträge sind Glob-Muster für aufgelöste Binärpfade.
• Roher Shell-Befehlstext, der Shell-Steuer- oder Erweiterungssyntax enthält (&&, ||, ;, |, `, $, <, >, (, )), wird als Nichttreffer in der Allowlist behandelt und erfordert eine ausdrückliche Genehmigung (oder die Aufnahme der Shell-Binärdatei in die Allowlist).
• Die Auswahl von „Always Allow“ in der Aufforderung fügt diesen Befehl der Allowlist hinzu.
• Umgebungsüberschreibungen für system.run werden gefiltert (PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4 werden entfernt) und dann mit der Umgebung der App zusammengeführt.
• Für Shell-Wrapper (bash|sh|zsh ... -c/-lc) werden anfragebezogene Umgebungsüberschreibungen auf eine kleine explizite Allowlist reduziert (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Bei Immer-erlauben-Entscheidungen im Allowlist-Modus speichern bekannte Dispatch-Wrapper (env, nice, nohup, stdbuf, timeout) innere ausführbare Pfade statt Wrapper-Pfade. Wenn das Entpacken nicht sicher ist, wird kein Allowlist-Eintrag automatisch gespeichert.

​

Deep Links

​

openclaw://agent

• message (erforderlich)
• sessionKey (optional)
• thinking (optional)
• deliver / to / channel (optional)
• timeoutSeconds (optional)
• key (optional unbeaufsichtigter Modus-Schlüssel)

• Ohne key fordert die App eine Bestätigung an.
• Ohne key erzwingt die App ein kurzes Nachrichtenlimit für die Bestätigungsaufforderung und ignoriert deliver / to / channel.
• Mit einem gültigen key läuft die Ausführung unbeaufsichtigt (gedacht für persönliche Automatisierungen).

​

Onboarding-Ablauf (typisch)

1. Installieren und starten Sie OpenClaw.app.
2. Schließen Sie die Berechtigungs-Checkliste ab (TCC-Aufforderungen).
3. Stellen Sie sicher, dass der Local-Modus aktiv ist und das Gateway läuft.
4. Installieren Sie die CLI, wenn Sie Terminalzugriff möchten.

​

Platzierung des Statusverzeichnisses (macOS)

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

​

Build- und Entwicklungsablauf (nativ)

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

​

Gateway-Konnektivität debuggen (macOS-CLI)

• --url <ws://host:port>: Konfiguration überschreiben
• --mode <local|remote>: aus der Konfiguration auflösen (Standard: Konfiguration oder local)
• --probe: einen neuen Health-Check erzwingen
• --timeout <ms>: Anfrage-Timeout (Standard: 15000)
• --json: strukturierte Ausgabe zum Vergleichen

• --include-local: Gateways einschließen, die als „lokal“ herausgefiltert würden
• --timeout <ms>: Gesamtzeitfenster für die Erkennung (Standard: 2000)
• --json: strukturierte Ausgabe zum Vergleichen

​

Remote-Verbindungsverkabelung (SSH-Tunnel)

​

Kontrolltunnel (Gateway-WebSocket-Port)

• Zweck: Health-Checks, Status, Web Chat, Konfiguration und andere Control-Plane-Aufrufe.
• 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 verwendet einen vorhandenen gesunden Tunnel wieder oder startet ihn bei Bedarf neu.
• SSH-Form: ssh -N -L <local>:127.0.0.1:<remote> mit BatchMode + ExitOnForwardFailure + Keepalive-Optionen.
• IP-Berichterstattung: Der SSH-Tunnel verwendet Loopback, daher sieht das Gateway die Node- IP als 127.0.0.1. Verwenden Sie den Transport Direct (ws/wss), wenn die echte Client- IP angezeigt werden soll (siehe macOS-Remotezugriff).

​

Zugehörige Dokumentation

• Gateway-Runbook
• Gateway (macOS)
• macOS-Berechtigungen
• Canvas