Understanding the OpenClaw macOS IPC Architecture

I’ve spent too many hours fighting with macOS permissions. It is a common headache for developers: you have a background service that needs to run a command or record the screen, but macOS blocks it or triggers a new TCC prompt every time you rebuild the binary.

Keeping those permission grants stable while maintaining a headless service is a tricky balance. I prefer a setup where the permissions stick to a single signed bundle, while the heavy lifting happens elsewhere. OpenClaw handles this by splitting the work between a node service and a GUI app.

What You’ll Need

1. An Apple Development signing identity.
2. The OpenClaw source code.
3. A stable TeamID for consistent bundle signing.
4. A local Unix socket environment.

Quick Start

OpenClaw uses a specific IPC (Inter-Process Communication) model to keep permissions predictable. A headless node host service connects to the Gateway via WebSocket, but it forwards system.run requests to the macOS app over a local Unix socket. This ensures that all TCC-facing work—like notifications or screen recording—comes from the same signed bundle.

To get the environment running and handle the initial setup:

SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh

This script performs four main tasks:

1. It kills any existing instances of the app and service.
2. It runs the Swift build and packages the app.
3. It writes and bootstraps the LaunchAgent.
4. It ensures the signed bundle ID remains stable so TCC grants persist.

The communication flow looks like this:

Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)

For UI automation, the system uses PeekabooBridge via a separate Unix socket named bridge.sock. It follows a specific host preference order: Peekaboo.app, then Claude.app, then OpenClaw.app, and finally local execution.

Troubleshooting

1. Multiple Instances: The app is designed to exit early if another instance with the same bundle ID is already running. If the app fails to start, check if a ghost process is still active.
2. Connection Checks: If actions aren’t flowing, use the openclaw-mac debug CLI. It allows you to verify discovery and check if the connection between the service and the app is active.
3. Permission Denied (Debug): During local development, you might face issues with unsigned clients. You can use PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 as a debug-only escape hatch for same-UID callers.
4. IPC Security Hardening: If connections are rejected, ensure the socket mode is 0600. The system also requires a valid token, peer-UID checks, and an HMAC challenge/response with a short TTL.

Need help with your specific configuration? Use the AI Setup Assistant.

What’s Next

• PeekabooBridge usage
• Node Service Configuration