Spaces:
Paused
Paused
| summary: "macOS IPC architecture for OpenClaw app, gateway node transport, and PeekabooBridge" | |
| read_when: | |
| - Editing IPC contracts or menu bar app IPC | |
| title: "macOS IPC" | |
| # OpenClaw macOS IPC architecture | |
| **Current model:** a local Unix socket connects the **node host service** to the **macOS app** for exec approvals + `system.run`. A `openclaw-mac` debug CLI exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge. | |
| ## Goals | |
| - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript). | |
| - A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation. | |
| - Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick. | |
| ## How it works | |
| ### Gateway + node transport | |
| - The app runs the Gateway (local mode) and connects to it as a node. | |
| - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`). | |
| ### Node service + app IPC | |
| - A headless node host service connects to the Gateway WebSocket. | |
| - `system.run` requests are forwarded to the macOS app over a local Unix socket. | |
| - The app performs the exec in UI context, prompts if needed, and returns output. | |
| Diagram (SCI): | |
| ``` | |
| Agent -> Gateway -> Node Service (WS) | |
| | IPC (UDS + token + HMAC + TTL) | |
| v | |
| Mac App (UI + TCC + system.run) | |
| ``` | |
| ### PeekabooBridge (UI automation) | |
| - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol. | |
| - Host preference order (client-side): Peekaboo.app → Claude.app → OpenClaw.app → local execution. | |
| - Security: bridge hosts require an allowed TeamID; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention). | |
| - See: [PeekabooBridge usage](/platforms/mac/peekaboo) for details. | |
| ## Operational flows | |
| - Restart/rebuild: `SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh` | |
| - Kills existing instances | |
| - Swift build + package | |
| - Writes/bootstraps/kickstarts the LaunchAgent | |
| - Single instance: app exits early if another instance with the same bundle ID is running. | |
| ## Hardening notes | |
| - Prefer requiring a TeamID match for all privileged surfaces. | |
| - PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development. | |
| - All communication remains local-only; no network sockets are exposed. | |
| - TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds. | |
| - IPC hardening: socket mode `0600`, token, peer-UID checks, HMAC challenge/response, short TTL. | |