OpenClaw macOS IPC-Architektur

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

Ziele

  • Eine einzelne GUI-App-Instanz, die alle TCC-relevanten Aufgaben übernimmt (Benachrichtigungen, Bildschirmaufnahme, Mikrofon, Sprache, AppleScript).
  • Eine kleine Oberfläche für Automatisierung: Gateway + Node-Befehle, plus PeekabooBridge für UI-Automatisierung.
  • Vorhersehbare Berechtigungen: immer dieselbe signierte Bundle-ID, gestartet von launchd, damit TCC-Freigaben erhalten bleiben.

So funktioniert es

Gateway + Node Transport

  • Die App führt den Gateway (lokaler Modus) aus und verbindet sich als Node damit.
  • Agent-Aktionen werden über 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 die Ausführung im UI-Kontext durch, fragt bei Bedarf nach 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 (Client-seitig): Peekaboo.app → Claude.app → OpenClaw.app → lokale Ausführung.
  • Sicherheit: Bridge-Hosts benötigen 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 + Package
    • Schreibt/bootstrapped/kickstartet den LaunchAgent
  • Einzelinstanz: Die App beendet sich frühzeitig, wenn eine andere Instanz mit derselben Bundle-ID läuft.

Härtungshinweise

  • Bevorzuge die Anforderung eines TeamID-Matches für alle privilegierten Oberflächen.
  • PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) kann same-UID Caller für lokale Entwicklung erlauben.
  • Alle Kommunikation bleibt 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-Checks, HMAC Challenge/Response, kurze TTL.