Peekaboo bridge

Peekaboo bridge 문서는 OpenClaw 공식 문서(platforms/mac/peekaboo)를 한국어로 정리한 가이드입니다. PeekabooBridge integration for macOS UI automation 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

PeekabooBridge integration for macOS UI automation

한국어 가이드 범위: platforms/mac/peekaboo 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What this is (and is not)
Relationship to other desktop-control paths
Enable the bridge
Client discovery order
Security and permissions
Snapshot behavior (automation)
트러블슈팅
관련 문서

상세 내용

본문

OpenClaw can host PeekabooBridge as a local, permission-aware UI automation broker (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 peekaboo CLI (there is no separate openclaw 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 peekaboo CLI 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-in computer tool captures screenshots via screen.snapshot and drives the pointer and keyboard through the dangerous computer.act node command. A macOS node fulfills computer.act in-process using the embedded Peekaboo automation services this bridge exposes plus narrow CoreGraphics primitives, without going through the PeekabooBridge socket or the peekaboo CLI. See Computer use.
Codex Computer Use: the bundled codex plugin checks and can install Codex's computer-use MCP 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-driver MCP: OpenClaw can register TryCua's upstream cua-driver mcp server 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.

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.

Client discovery order

Peekaboo clients typically try hosts in this order:

Security and permissions

주요 항목:

The bridge validates caller code signatures; an allowlist of TeamIDs is enforced (Peekaboo host TeamID plus the running app's own TeamID).
Prefer the signed bridge/app identity over a generic node runtime for Accessibility. Granting Accessibility to node lets 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.

트러블슈팅

주요 항목:

If peekaboo reports "bridge client is not authorized", ensure the client is properly signed or run the host with PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 in debug mode only.
If no hosts are found, open one of the host apps (Peekaboo.app or OpenClaw.app) and confirm permissions are granted.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/peekaboo
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

Peekaboo bridge

핵심 요약

PeekabooBridge integration for macOS UI automation

한국어 가이드 범위: platforms/mac/peekaboo 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What this is (and is not)
Relationship to other desktop-control paths
Enable the bridge
Client discovery order
Security and permissions
Snapshot behavior (automation)
트러블슈팅
관련 문서

상세 내용

본문

What this is (and is not)

주요 항목:

Host: OpenClaw.app can act as a PeekabooBridge host.
Client: the peekaboo CLI (there is no separate openclaw 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 peekaboo CLI 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-in computer tool captures screenshots via screen.snapshot and drives the pointer and keyboard through the dangerous computer.act node command. A macOS node fulfills computer.act in-process using the embedded Peekaboo automation services this bridge exposes plus narrow CoreGraphics primitives, without going through the PeekabooBridge socket or the peekaboo CLI. See Computer use.
Codex Computer Use: the bundled codex plugin checks and can install Codex's computer-use MCP 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-driver MCP: OpenClaw can register TryCua's upstream cua-driver mcp server 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.

Enable the bridge

Client discovery order

Peekaboo clients typically try hosts in this order:

Security and permissions

주요 항목:

The bridge validates caller code signatures; an allowlist of TeamIDs is enforced (Peekaboo host TeamID plus the running app's own TeamID).
Prefer the signed bridge/app identity over a generic node runtime for Accessibility. Granting Accessibility to node lets 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)

트러블슈팅

주요 항목:

If peekaboo reports "bridge client is not authorized", ensure the client is properly signed or run the host with PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 in debug mode only.
If no hosts are found, open one of the host apps (Peekaboo.app or OpenClaw.app) and confirm permissions are granted.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/peekaboo
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Peekaboo bridge

핵심 요약

문서 구성

상세 내용

본문

What this is (and is not)

Relationship to other desktop-control paths

Enable the bridge

Client discovery order

Security and permissions

Snapshot behavior (automation)

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Peekaboo bridge

핵심 요약

문서 구성

상세 내용

본문

What this is (and is not)

Relationship to other desktop-control paths

Enable the bridge

Client discovery order

Security and permissions

Snapshot behavior (automation)

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드