macOS companion app

Peekaboo 브리지

OpenClaw은 PeekabooBridge를 로컬 권한 인식 UI 자동화 브로커로 호스팅할 수 있습니다(steipete/Peekaboo Swift 패키지를 기반으로 하는 PeekabooBridgeHostCoordinator). 이를 통해 peekaboo CLI는 macOS 앱의 TCC 권한을 재사용하면서 UI 자동화를 실행할 수 있습니다.

개요

호스트: OpenClaw.app은 PeekabooBridge 호스트로 작동할 수 있습니다.
클라이언트: peekaboo CLI를 사용합니다(별도의 openclaw ui ... 인터페이스는 없습니다).
UI: 시각적 오버레이는 Peekaboo.app에 유지되며, OpenClaw은 경량 브로커 호스트입니다.

다른 데스크톱 제어 경로와의 관계

OpenClaw에는 의도적으로 서로 분리된 네 가지 데스크톱 제어 경로가 있습니다.

PeekabooBridge 호스트: OpenClaw.app은 로컬 PeekabooBridge 소켓을 호스팅합니다. peekaboo CLI는 클라이언트이며, 스크린샷, 클릭, 메뉴, 대화 상자, Dock 동작 및 창 관리에 OpenClaw.app의 macOS 권한을 사용합니다.
에이전트 기반 컴퓨터 사용(computer.act): Gateway 에이전트에 내장된 computer 도구는 screen.snapshot을 통해 스크린샷을 캡처하고 위험한 computer.act Node 명령을 통해 포인터와 키보드를 제어합니다. macOS Node는 PeekabooBridge 소켓이나 peekaboo CLI를 거치지 않고, 이 브리지가 노출하는 내장 Peekaboo 자동화 서비스와 제한된 CoreGraphics 기본 기능을 사용하여 프로세스 내에서 computer.act를 처리합니다. 컴퓨터 사용을 참조하세요.
Codex 컴퓨터 사용: 번들 codex Plugin은 Codex의 computer-use MCP Plugin(extensions/codex/src/app-server/computer-use.ts)을 확인하고 설치할 수 있으며, Codex 모드 턴 중에 Codex가 네이티브 데스크톱 제어 도구 호출을 담당하도록 합니다. OpenClaw은 이러한 동작을 PeekabooBridge를 통해 프록시하지 않습니다.
직접 cua-driver MCP 사용: OpenClaw은 TryCua의 업스트림 cua-driver mcp 서버를 일반 MCP 서버로 등록할 수 있습니다. 이를 통해 에이전트는 Codex 마켓플레이스나 PeekabooBridge 소켓을 거치지 않고 CUA 드라이버 자체의 스키마와 PID/창/요소 인덱스 워크플로를 사용할 수 있습니다.

OpenClaw.app의 권한 인식 브리지 호스트를 통해 광범위한 macOS 자동화 기능을 사용하려면 Peekaboo를 사용하세요. 모든 비전 모델이 구동할 수 있는 통일된 computer.act Node 명령을 통해 Gateway 에이전트가 데스크톱을 보고 제어해야 한다면 에이전트 기반 컴퓨터 사용을 사용하세요. Codex 모드 에이전트가 Codex의 네이티브 Plugin을 사용해야 한다면 Codex 컴퓨터 사용을 사용하세요. CUA 드라이버를 일반 MCP 서버로 모든 OpenClaw 관리 런타임에 노출하려면 직접 cua-driver mcp를 사용하세요.

브리지 활성화

macOS 앱에서 Settings -> Enable Peekaboo Bridge를 선택합니다.

활성화하면 OpenClaw은 ~/Library/Application Support/OpenClaw/<socket-name>에서 로컬 UNIX 소켓 서버를 시작합니다. 비활성화하면 호스트가 중지되고 peekaboo는 사용 가능한 다른 호스트로 대체됩니다. 또한 코디네이터는 이전 peekaboo 설치를 위해 현재 소켓을 가리키는 레거시 소켓 심볼릭 링크(Application Support 아래의 clawdbot, clawdis, moltbot)를 유지합니다.

클라이언트 검색 순서

Peekaboo 클라이언트는 일반적으로 다음 순서로 호스트를 찾습니다.

Peekaboo.app(전체 UX)
Claude.app(설치된 경우)
OpenClaw.app(경량 브로커)

활성 호스트와 사용 중인 소켓 경로를 확인하려면 peekaboo bridge status --verbose를 사용하세요. 다음과 같이 재정의할 수 있습니다.

bash

export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

보안 및 권한

브리지는 호출자의 코드 서명을 검증하며, TeamID 허용 목록(Peekaboo 호스트 TeamID와 실행 중인 앱 자체의 TeamID)이 적용됩니다.
손쉬운 사용 권한에는 범용 node 런타임보다 서명된 브리지/앱 ID를 사용하는 것이 좋습니다. node에 손쉬운 사용 권한을 부여하면 해당 Node 실행 파일로 시작된 모든 패키지가 GUI 자동화 접근 권한을 상속할 수 있습니다. macOS 권한을 참조하세요.
요청은 10초 후 시간 초과됩니다(requestTimeoutSec: 10).
필수 권한이 없으면 브리지는 시스템 설정을 실행하는 대신 명확한 오류 메시지를 반환합니다.

스냅샷 동작(자동화)

스냅샷은 10분의 유효 기간과 최대 50개 제한으로 메모리에 저장됩니다(InMemorySnapshotManager). 정리 시 아티팩트는 삭제되지 않습니다. 더 오래 보존해야 한다면 클라이언트에서 다시 캡처하세요.

문제 해결

peekaboo가 "bridge client is not authorized"라고 보고하면 클라이언트가 올바르게 서명되었는지 확인하거나, 디버그 모드에서만 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1을 설정하여 호스트를 실행하세요.
호스트를 찾을 수 없다면 호스트 앱 중 하나(Peekaboo.app 또는 OpenClaw.app)를 열고 권한이 부여되었는지 확인하세요.