adolf/docs/platforms/mac/xpc.md

summary, read_when, title

summary	read_when	title
macOS IPC architecture for OpenClaw app, gateway node transport, and PeekabooBridge	Editing IPC contracts or menu bar app IPC	macOS IPC

OpenClaw macOS IPC architecture

A local Unix socket connects the node host service to the macOS app for exec approvals and system.run. An openclaw-mac debug CLI (apps/macos/Sources/OpenClawMacCLI) 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 commands include canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, system.run, and system.notify.
• The node reports a permissions map so agents can see whether screen, camera, microphone, speech, automation, or accessibility access is available.

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 (ExecApprovalsSocket.swift).
• 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 (~/Library/Application Support/OpenClaw/<socket>) and the PeekabooBridge JSON protocol.
• Host preference order (client-side): Peekaboo.app -> Claude.app -> OpenClaw.app -> local execution.
• Security: bridge hosts require an allowlisted TeamID (the bundled PeekabooBridgeHostCoordinator allowlists a fixed team plus the app's own signing team); a DEBUG-only same-UID escape hatch is guarded by PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (Peekaboo convention).
• See: PeekabooBridge usage for details.

Operational flows

• Restart/rebuild: scripts/restart-mac.sh kills existing instances, rebuilds via Swift, repackages, and relaunches. It auto-detects an available signing identity and falls back to --no-sign if none is found; pass --sign to require signing (fails if no key is available) or --no-sign to force the unsigned path. SIGN_IDENTITY set in the environment is unset on the signed path, so scripts/codesign-mac-app.sh's own identity auto-detection picks the cert.
• Single instance: the app checks NSWorkspace.runningApplications for a duplicate bundle ID and exits if more than one instance is found (isDuplicateInstance() in MenuBar.swift).

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.
• Exec approvals socket hardening: file mode 0600, shared token, peer-UID check (getpeereid), HMAC-SHA256 challenge/response, and a short TTL on requests.

Related

• macOS app
• macOS IPC flow (Exec approvals)