macOS IPC Architektur in OpenClaw verstehen

Du kennst das Problem: Du baust ein Tool für macOS, das Systembefehle oder UI-Aktionen automatisieren soll, aber die TCC-Berechtigungen (Transparency, Consent, and Control) machen dir ständig einen Strich durch die Rechnung. Entweder verliert dein CLI-Tool nach jedem Update den Zugriff auf das Mikrofon oder die Bildschirmaufnahme, oder die Berechtigungsdialoge tauchen gar nicht erst auf, weil der Prozesskontext falsch ist.

Um dieses Chaos zu vermeiden, nutzt OpenClaw eine Architektur, die alle sicherheitskritischen Aufgaben in einer einzigen, signierten GUI-App bündelt. Hier erfährst du, wie das IPC-System (Inter-Process Communication) dahinter funktioniert und wie du es für deine Entwicklung nutzt.

Voraussetzungen

• Eine gültige Apple Developer ID für die Signierung (SIGN_IDENTITY)
• macOS Umgebung für die Ausführung der Swift-Builds

Schnellstart

In weniger als 5 Minuten hast du die lokale Umgebung für die macOS-Entwicklung bereit. Der wichtigste Schritt ist das korrekte Signieren, damit die TCC-Berechtigungen erhalten bleiben.

1. Setze deine SIGN_IDENTITY als Umgebungsvariable.
2. Führe das Restart-Skript aus, um bestehende Instanzen zu beenden und die App neu zu bauen.
3. Das Skript erstellt den LaunchAgent und startet die App automatisch.
4. Prüfe die Verbindung über das openclaw-mac debug CLI.

SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh

How it works

Das System basiert auf einer strikten Trennung zwischen dem Node-Service (der die Logik steuert) und der macOS-App (die die Aktionen ausführt).

Gateway + node transport

Die macOS-App startet intern einen lokalen Gateway. Sie verbindet sich selbst als Node mit diesem Gateway. Agent-Aktionen werden über node.invoke abgewickelt, zum Beispiel für system.run, system.notify oder canvas.* Operationen.

Node service + app IPC

Ein headless Node-Host-Service verbindet sich per WebSocket mit dem Gateway. Wenn ein system.run Request reinkommt, wird dieser über einen lokalen Unix socket an die macOS-App weitergeleitet. Die App führt den Befehl im UI-Kontext aus, zeigt bei Bedarf TCC-Prompts an und gibt den Output zurück.

Die Kommunikation ist durch mehrere Layer abgesichert:

• Socket-Berechtigungen sind auf 0600 gesetzt.
• Token-basierte Authentifizierung und HMAC Challenge/Response.
• Peer-UID Checks und kurze TTL (Time-to-Live) für Anfragen.

PeekabooBridge für UI-Automation

Für UI-Automation nutzt OpenClaw einen separaten Unix socket namens bridge.sock. Dieser folgt dem PeekabooBridge JSON-Protokoll. Die Client-Logik sucht dabei in einer festen Reihenfolge nach einem Host: Peekaboo.app → Claude.app → OpenClaw.app → lokale Ausführung.

Fehlerbehebung

TCC-Berechtigungen werden nicht erkannt

Das passiert meistens, wenn die Bundle ID oder die Signatur nicht stabil ist. Stelle sicher, dass du immer dieselbe SIGN_IDENTITY verwendest. Die App bricht den Start zudem frühzeitig ab, wenn bereits eine andere Instanz mit derselben Bundle ID läuft.

Zugriff auf den Socket verweigert

Standardmäßig erfordern alle privilegierten Schnittstellen einen TeamID-Match. Wenn du lokal entwickelst und unsignierte Clients testen musst, kannst du diesen Check im DEBUG-Modus umgehen:

# Nur für lokale Entwicklung verwenden
export PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1

AI Setup Assistant

Nächste Schritte

• PeekabooBridge usage
• Gateway Konfiguration