Peekaboo Bridge macOS UI Automation

OpenClaw is able to run PeekabooBridge as a local UI automation broker that respects permissions (PeekabooBridgeHostCoordinator, powered by the steipete/Peekaboo Swift package). Through this arrangement, the peekaboo CLI can perform UI automation while taking advantage of the TCC permissions already granted to the macOS app.

What this is (and is not)

Host: OpenClaw.app is capable of serving as a PeekabooBridge host.
Client: the peekaboo CLI is the only client; no separate openclaw ui ... interface exists.
UI: visual overlays remain within Peekaboo.app; OpenClaw functions purely as a lightweight broker host.

Relationship to other desktop-control paths

Four distinct desktop-control paths are deliberately kept separate within OpenClaw:

PeekabooBridge host: OpenClaw.app maintains the local PeekabooBridge socket. Acting as the client, the peekaboo CLI relies on 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-in computer tool obtains screenshots through screen.snapshot and controls the pointer and keyboard via the risky computer.act node command. A macOS node satisfies computer.act in-process, drawing on the embedded Peekaboo automation services this bridge exposes plus narrow CoreGraphics primitives, without touching the PeekabooBridge socket or the peekaboo CLI. Refer to Computer use.
Codex Computer Use: the bundled codex plugin verifies and can install Codex's computer-use MCP plugin (extensions/codex/src/app-server/computer-use.ts), after which Codex takes ownership of native desktop-control tool calls during Codex-mode turns. OpenClaw does not route those actions through PeekabooBridge.
Direct cua-driver MCP: OpenClaw can expose TryCua's upstream cua-driver mcp server as a standard MCP server, granting agents the CUA driver's own schemas and pid/window/element-index workflow without going through the Codex marketplace or the PeekabooBridge socket.

For broad macOS automation coverage, rely on Peekaboo through OpenClaw.app's permission-aware bridge host. When the gateway agent needs to observe and manipulate the desktop via a consistent computer.act node command usable by any vision model, agent-driven computer use is the right choice. Codex Computer Use fits when a Codex-mode agent should depend on Codex's native plugin. To present the CUA driver to any OpenClaw-managed runtime as a regular MCP server, use direct cua-driver mcp.

Enable the bridge

Within the macOS app: Settings -> Enable Peekaboo Bridge. This toggle demands that Allow Computer Control be active, because both grant local UI automation; when Computer Control is off, the toggle stays disabled and the host remains inactive. To use Peekaboo without Computer Control, run Peekaboo's own Mac app as the host instead.

Once enabled (with Computer Control active), OpenClaw launches a local UNIX socket server at ~/Library/Application Support/OpenClaw/<socket-name>. Turning it off stops the host, and peekaboo switches to whatever other hosts are available. The coordinator additionally keeps legacy socket symlinks (clawdbot, clawdis, moltbot under Application Support) that point to the current socket for older peekaboo installs.

For a single unattended execution, --attach-only --background-only prevents automatic windows and GUI-owned Keychain loading. The persistent elevation host serves as a managed-deployment route for OpenClaw Foundation release operators. Its package command needs the Foundation signing identity plus notarization credentials; OpenClaw does not currently offer a general-download elevation archive. Only install a certified, source-addressed archive provided by an authorized release operator:

cd /path/to/elevation-artifact-set
export PREFIX="OpenClaw-<full-openclaw-sha>-Peekaboo-<full-peekaboo-sha>-stable"
export INSTALLER_SHA256="<authenticated-installer-sha256>"
export RECEIPT_SHA256="<authenticated-receipt-sha256>"
[[ "$(shasum -a 256 "$PREFIX-installer.sh" | awk '{print $1}')" == "$INSTALLER_SHA256" ]] || exit 1
shasum -a 256 -c "$PREFIX.zip.sha256"
shasum -a 256 -c "$PREFIX-installer.sh.sha256"
./"$PREFIX-installer.sh" verify \
  --archive "$PREFIX.zip" \
  --receipt "$PREFIX.json" \
  --receipt-sha256 "$RECEIPT_SHA256"
./"$PREFIX-installer.sh" migration-plan \
  --migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" install \
  --archive "$PREFIX.zip" \
  --receipt "$PREFIX.json" \
  --receipt-sha256 "$RECEIPT_SHA256" \
  --migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" status --state-dir "<existing-state-dir>"

Move the full artifact set: archive, receipt, portable installer, and both checksum files. A source checkout of OpenClaw is not required on the target Mac. The authorized operator handoff must independently supply the installer and receipt SHA-256 digests. Before planning a cutover, run verify with the authenticated receipt digest; the receipt then picks the approved archive, and verify revalidates the Foundation-signed app, notarization, staple, Gatekeeper result, architectures, entitlements, and both source revisions. Because the portable installer falls outside the app's code signature, this explicit two-digest release-operator handoff remains part of the internal trust boundary.

The managed elevation workflow upgrades a Mac that is already paired. 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 runs those checks without altering the app, process, LaunchAgent, state, or Gateway. It recognizes the canonical CLI-managed ai.openclaw.node job and app-backed background LaunchAgents. When the old app runs in background mode without a LaunchAgent, choose --adopt-running-app over --migrate-launch-agent and pass its state/config paths explicitly if they are not the defaults.

--elevation-host follows from the installed job. It maintains the Bridge, control channel, Mac node, Gateway connectivity, and termination handling 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 flagged by status; the host never opens System Settings to grant it. Installation completes once the launchd-owned process is Bridge-ready even if those grants are still pending, 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 relies on the separate ai.openclaw.mac.elevation-host job and refuses to race or rewrite ordinary Launch at login (ai.openclaw.mac).

Cutover happens transactionally: 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 permit successive upgrades; recover keeps the replaced app in a unique evidence directory, restores the prior receipt, and declines 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 holds 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 included in this workflow.

Client discovery order

Peekaboo clients typically attempt hosts in this sequence:

Peekaboo.app (full UX)
Claude.app (if installed)
OpenClaw.app (thin broker)

To determine which host is active and which socket path is in use, call peekaboo bridge status --verbose. Override with:

export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

Security and permissions

The bridge checks that caller code signatures are valid. The production OpenClaw host will only accept the exact Peekaboo CLI bundle (boo.peekaboo.peekaboo) that carries the signature from Peekaboo's canonical current/legacy release signer set (FWJYW4S8P8 and Y5PE65HELJ); merely sharing the app's UID or using a different client signed by the app's development team won't pass.
Favor the signed bridge/app identity over a generic node runtime when dealing with Accessibility. Granting Accessibility to node means any package launched through that Node executable can inherit GUI automation access; refer to macOS permissions.
Requests expire after 10 seconds (requestTimeoutSec: 10).
When required permissions are absent, the bridge returns a clear error message instead of opening System Settings.

Snapshot behavior (automation)

Snapshots live in memory, valid for 10 minutes, with a maximum of 50 stored (InMemorySnapshotManager); cleanup does not remove artifacts. For longer retention, capture again from the client.

Troubleshooting

If peekaboo says "bridge client is not authorized", verify the client is signed correctly, or run the host with PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 in debug mode only.
When no hosts show up, launch one of the host apps (Peekaboo.app or OpenClaw.app) and verify permissions are in place.