Skip to main content

​
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.