OpenClaw macOS-IPC-Architektur

Aktuelles Modell: Ein lokaler Unix-Socket verbindet den Node-Host-Service mit der macOS-App für Exec-Genehmigungen + system.run. Eine openclaw-mac-Debug-CLI existiert für Discovery/Connect-Checks; Agent-Aktionen laufen weiterhin über den Gateway-WebSocket und node.invoke. UI-Automatisierung nutzt PeekabooBridge.

Ziele

• Eine einzige GUI-App-Instanz, die alle TCC-relevanten Aufgaben besitzt (Benachrichtigungen, Bildschirmaufnahme, Mikrofon, Spracherkennung, AppleScript).
• Eine kleine Oberfläche für Automatisierung: Gateway + Node-Befehle, plus PeekabooBridge für UI-Automatisierung.
• Vorhersagbare Berechtigungen: immer dieselbe signierte Bundle-ID, gestartet über launchd, damit TCC-Zusagen bestehen bleiben.

So funktioniert es

Gateway + Node-Transport

• Die App betreibt das Gateway (lokaler Modus) und verbindet sich als Node damit.
• Agent-Aktionen werden via node.invoke ausgeführt (z. B. system.run, system.notify, canvas.*).

Node-Service + App-IPC

• Ein Headless-Node-Host-Service verbindet sich mit dem Gateway-WebSocket.
• system.run-Anfragen werden über einen lokalen Unix-Socket an die macOS-App weitergeleitet.
• Die App führt den Exec im UI-Kontext aus, fragt bei Bedarf und gibt die Ausgabe zurück.

Diagramm (SCI):

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

PeekabooBridge (UI-Automatisierung)

• UI-Automatisierung nutzt einen separaten UNIX-Socket namens bridge.sock und das PeekabooBridge-JSON-Protokoll.
• Host-Präferenzreihenfolge (clientseitig): Peekaboo.app → Claude.app → OpenClaw.app → lokale Ausführung.
• Sicherheit: Bridge-Hosts verlangen eine erlaubte TeamID; DEBUG-only Same-UID-Escape-Hatch wird durch PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 geschützt (Peekaboo-Konvention).
• Siehe: PeekabooBridge-Nutzung für Details.

Betriebsabläufe

• Neustart/Rebuild: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
  • Beendet bestehende Instanzen
  • Swift-Build + Paketierung
  • Schreibt/Bootstrapt/Kickstartet den LaunchAgent
• Einzelinstanz: Die App beendet sich sofort, wenn eine andere Instanz mit derselben Bundle-ID läuft.

Härtungshinweise

• Bevorzuge TeamID-Match für alle privilegierten Oberflächen.
• PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (nur DEBUG) kann Same-UID-Aufrufer für lokale Entwicklung erlauben.
• Alle Kommunikation bleibt nur lokal; keine Netzwerk-Sockets werden exponiert.
• TCC-Prompts stammen nur vom GUI-App-Bundle; halte die signierte Bundle-ID über Rebuilds hinweg stabil.
• IPC-Härtung: Socket-Modus 0600, Token, Peer-UID-Prüfungen, HMAC-Challenge/Response, kurze TTL.