Setting up Peekaboo Bridge with OpenClaw

I have spent many hours wrestling with macOS permissions for UI automation. It is frustrating when you want to run a script but find yourself stuck in a loop of TCC prompts or permission errors. I prefer tools that stay out of the way while handling the heavy lifting of security and access.

OpenClaw can act as a PeekabooBridge host. This means you can use the peekaboo CLI to drive UI automation while relying on OpenClaw to handle the macOS permissions. It is a thin broker that lets you run automation without managing separate permission sets for every tool.

What You’ll Need

• OpenClaw.app
• peekaboo CLI
• macOS permissions granted to OpenClaw.app

Quick Start

Setting this up takes less than five minutes. Here is the path to get it running.

1. Enable the Bridge: Open the macOS app and go to Settings. Toggle the switch for Enable Peekaboo Bridge.
2. Verify the Connection: Open your terminal and run the following command to see which host is active:

   peekaboo bridge status --verbose

3. Check Discovery: Peekaboo looks for hosts in a specific order. It checks for Peekaboo.app first, then Claude.app, and finally OpenClaw.app.
4. Manual Override: If you need to point the CLI to a specific socket, you can set the environment variable:

   export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

When you enable the bridge, OpenClaw starts a local UNIX socket server. If you turn it off, the host stops and the peekaboo CLI tries to find other available hosts.

Security and Snapshots

The bridge is built with security in mind. It validates the code signatures of anything trying to connect. Only specific TeamIDs (Peekaboo and OpenClaw) are allowed by default. If a request takes too long, it will time out after 10 seconds. If permissions are missing, the bridge gives you a clear error message instead of forcing you into System Settings.

For automation tasks, snapshots are stored in memory. They expire after a short window to keep things clean. If you need to keep a snapshot for a longer period, you should re-capture it from the client.

Troubleshooting

• “bridge client is not authorized”: This usually means the client isn’t properly signed. If you are in a debug environment, you can run the host with this flag: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1.
• No hosts found: Make sure OpenClaw.app is actually open. Check that you have granted the necessary macOS permissions within the app settings.

If you run into other issues, you can ask the AI Setup Assistant for help.

What’s Next

• Peekaboo CLI Reference
• Managing macOS TCC Permissions
• OpenClaw Settings Overview
• Local Socket Configuration