82fd83418e
Per docs/CLAUDE.md, Mintlify anchor generation is brittle for headings
that contain em dashes, apostrophes, and ampersands. Normalize 9 H2
headings across docs/date-time.md, docs/pi.md, docs/platforms/{index,
macos, mac/webchat, mac/peekaboo}.md, docs/nodes/{images,audio}.md, and
docs/reference/AGENTS.default.md from `X & Y` to `X and Y` so anchors
do not collapse on entity decoding. Verified no inbound anchor references
to the renamed sections in the docs tree.
3.5 KiB
summary, read_when, title
| summary | read_when | title | ||||
|---|---|---|---|---|---|---|
| PeekabooBridge integration for macOS UI automation |
|
Peekaboo bridge |
OpenClaw can host PeekabooBridge as a local, permission‑aware UI automation
broker. 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: use the
peekabooCLI (no separateopenclaw ui ...surface). - UI: visual overlays stay in Peekaboo.app; OpenClaw is a thin broker host.
Relationship to Computer Use
OpenClaw has three desktop-control paths, and they intentionally stay separate:
- PeekabooBridge host: OpenClaw.app can host the local PeekabooBridge socket.
The
peekabooCLI remains the client and uses OpenClaw.app's macOS permissions for Peekaboo automation primitives such as screenshots, clicks, menus, dialogs, Dock actions, and window management. - Codex Computer Use: the bundled
codexplugin prepares Codex app-server, verifies that Codex'scomputer-useMCP server is available, and 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. That gives agents the CUA driver's own schemas and pid/window/element-index workflow without routing through the Codex marketplace or the PeekabooBridge socket.
Use Peekaboo when you want the broad macOS automation surface and OpenClaw.app's
permission-aware bridge host. Use Codex Computer Use when a Codex-mode agent
should rely on Codex's native computer-use plugin. Use direct cua-driver mcp
when you want the CUA driver exposed to any OpenClaw-managed runtime as a normal
MCP server.
Enable the bridge
In the macOS app:
- Settings → Enable Peekaboo Bridge
When enabled, OpenClaw starts a local UNIX socket server. If disabled, the host
is stopped and peekaboo will fall back to other available hosts.
Client discovery order
Peekaboo clients typically try hosts in this order:
- Peekaboo.app (full UX)
- Claude.app (if installed)
- OpenClaw.app (thin broker)
Use peekaboo bridge status --verbose to see which host is active and which
socket path is in use. You can override with:
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
Security and permissions
- The bridge validates caller code signatures; an allowlist of TeamIDs is enforced (Peekaboo host TeamID + OpenClaw app TeamID).
- Requests time out after ~10 seconds.
- 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 and expire automatically after a short window. 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.