PeekabooBridgeHostCoordinator, backed by the steipete/Peekaboo Swift package). This lets the peekaboo CLI drive UI automation while reusing the macOS app’s TCC permissions.
What this is (and is not)
- Host: OpenClaw.app can act as a PeekabooBridge host.
- Client: the
peekabooCLI (there is no separateopenclaw ui ...surface). - UI: visual overlays stay in Peekaboo.app; OpenClaw is a thin broker host.
Relationship to other desktop-control paths
OpenClaw has four desktop-control paths that intentionally stay separate:- PeekabooBridge host: OpenClaw.app hosts the local PeekabooBridge socket. The
peekabooCLI is the client and uses OpenClaw.app’s macOS permissions for screenshots, clicks, menus, dialogs, Dock actions, and window management. - Agent-driven computer use (
computer.act): the gateway agent’s built-incomputertool captures screenshots viascreen.snapshotand drives the pointer and keyboard through the dangerouscomputer.actnode command. A macOS node fulfillscomputer.actin-process using the embedded Peekaboo automation services this bridge exposes plus narrow CoreGraphics primitives, without going through the PeekabooBridge socket or thepeekabooCLI. See Computer use. - Codex Computer Use: the bundled
codexplugin checks and can install Codex’scomputer-useMCP plugin (extensions/codex/src/app-server/computer-use.ts), then lets Codex own native desktop-control tool calls during Codex-mode turns. OpenClaw does not proxy those actions through PeekabooBridge. - Direct
cua-driverMCP: OpenClaw can register TryCua’s upstreamcua-driver mcpserver as a normal MCP server, giving agents the CUA driver’s own schemas and pid/window/element-index workflow without routing through the Codex marketplace or the PeekabooBridge socket.
computer.act node command that any vision model can drive. Use Codex Computer Use when a Codex-mode agent should rely on Codex’s native plugin. Use direct cua-driver mcp to expose the CUA driver to any OpenClaw-managed runtime as a normal MCP server.
Enable the bridge
In the macOS app: Settings -> Enable Peekaboo Bridge. The toggle requires Allow Computer Control to be on, since both grant local UI automation; with Computer Control off the toggle is disabled and the host does not run. To drive Peekaboo without Computer Control, run Peekaboo’s own Mac app as the host instead. When enabled (and Computer Control is on), OpenClaw starts a local UNIX socket server at~/Library/Application Support/OpenClaw/<socket-name>. If disabled, the host stops and peekaboo falls back to other available hosts. The coordinator also maintains legacy socket symlinks (clawdbot, clawdis, moltbot under Application Support) pointing at the current socket for older peekaboo installs.
For a one-off unattended run, --attach-only --background-only suppresses automatic windows and GUI-owned Keychain
loading. The persistent elevation host is a managed-deployment path for OpenClaw Foundation release operators. Its
package command requires the Foundation signing identity and notarization credentials; OpenClaw does not currently
publish a general-download elevation archive. Install only a certified, source-addressed archive supplied by an
authorized release operator:
verify with the authenticated receipt digest before planning a cutover; the receipt then
selects the approved archive and verify revalidates the Foundation-signed app, notarization, staple, Gatekeeper result,
architectures, entitlements, and both source revisions. The portable installer is not covered by the app’s code
signature, so this explicit two-digest release-operator handoff remains part of the internal trust boundary.
The managed elevation workflow upgrades an already paired Mac. Its selected state and config must define an
app-readable direct remote Gateway route with string token or password auth, and the selected macOS node identity must
already be paired. migration-plan performs those checks without changing the app, process, LaunchAgent, state, or
Gateway. It recognizes the canonical CLI-managed ai.openclaw.node job and app-backed background LaunchAgents. If the
old app is running in background mode without a LaunchAgent, use --adopt-running-app instead of
--migrate-launch-agent and pass its state/config paths explicitly when they are not the defaults.
--elevation-host is implied by the installed job. It keeps the Bridge, control channel, Mac node, Gateway
connectivity, and termination handling active while disabling automatic windows, updater startup, Dock promotion,
pairing and exec-approval presenters, Quick Chat hotkeys, voice and cookie services, and GUI-owned Keychain reads.
Missing Screen Recording, Accessibility, or Event Synthesizing is reported by status; the host never opens System
Settings to grant it. Installation succeeds once the launchd-owned process is Bridge-ready even if those grants are
still incomplete, but it commits only after the exact paired node identity reconnects as openclaw-macos/node with the
new app version, computer capability, screen.snapshot, computer.act, and a computer-use descriptor. The installer
copies no Gateway credentials or interactive PATH; it carries only the verified state/config ownership paths and
uses the config’s existing route and auth. status rechecks Bridge, Gateway node, and TCC readiness. The installer
uses the separate ai.openclaw.mac.elevation-host job and refuses to race or rewrite ordinary Launch at login
(ai.openclaw.mac).
Cutover is transactional: the installer snapshots the exact app and source plist, stops the prior owner, installs the
replacement, and automatically restores the original bytes and loaded state if launchd, Bridge, or Gateway node
attestation fails. The install receipt binds rollback plist digests, the prior app CDHash, and any previous managed
install receipt. Generation-unique backups allow successive upgrades; recover preserves the replaced app in a unique
evidence directory, restores the prior receipt, and refuses to overwrite a source LaunchAgent path recreated by another
owner.
The elevation archive is Foundation-signed, notarized, stapled, named by the full OpenClaw and Peekaboo source
commits, and contains exactly OpenClaw.app. Its receipt binds the archive and portable-installer names and digests,
OpenClaw and Peekaboo source revisions, signer, per-architecture CDHashes, architectures, entitlement digests, and Apple notarization
submission ID. No AppleScript or Apple Events entitlement is part of this workflow.
Client discovery order
Peekaboo clients typically try hosts in this order:- Peekaboo.app (full UX)
- Claude.app (if installed)
- OpenClaw.app (thin broker)
peekaboo bridge status --verbose to see which host is active and which socket path is in use. Override with:
Security and permissions
- The bridge validates caller code signatures. The production OpenClaw host accepts only the exact Peekaboo CLI
bundle (
boo.peekaboo.peekaboo) signed by Peekaboo’s canonical current/legacy release signer set (FWJYW4S8P8andY5PE65HELJ); sharing the app’s UID or using another client signed by the app’s development team is not sufficient. - Prefer the signed bridge/app identity over a generic
noderuntime for Accessibility. Granting Accessibility tonodelets any package launched by that Node executable inherit GUI automation access; see macOS permissions. - Requests time out after 10 seconds (
requestTimeoutSec: 10). - If required permissions are missing, the bridge returns a clear error message rather than launching System Settings.
Snapshot behavior (automation)
Snapshots are stored in memory with a 10-minute validity window and a cap of 50 snapshots (InMemorySnapshotManager); artifacts are not deleted on cleanup. If you need longer retention, re-capture from the client.
Troubleshooting
- If
peekabooreports “bridge client is not authorized”, ensure the client is properly signed or run the host withPEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1in debug mode only. - If no hosts are found, open one of the host apps (Peekaboo.app or OpenClaw.app) and confirm permissions are granted.