peekaboo은(는) 무엇을 하나요?
Peekaboo를 사용하여 macOS UI를 검사하고, 의도한 대상에 대해 작업을 수행하며, 결과를 확인합니다.
아래 예제는 v4 구문을 사용합니다. peekaboo --version과 설치된 명령의 --help를 확인하세요.
구 버전을 사용 중이라면 해당 버전의 도움말을 따르세요.
OpenClaw Bridge
OpenClaw macOS 앱은 Computer Control이 활성화되어 있고, 제공자가 Peekaboo이며, Peekaboo Bridge가 활성화된 경우 Peekaboo Bridge를 호스팅합니다. 해당 호스트를 통해 실행할 때는 기존 OpenClaw 소켓 선택을 유지하세요:
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json
선택한 호스트와 소켓이 의도한 것인지 확인하세요. 명시적인 PEEKABOO_BRIDGE_SOCKET 또는 --bridge-socket 선택을 유지하세요.
필요한 호스트를 사용할 수 없는 경우 해당 결과를 보고하고, 명령을 성공시키기 위해 선택을 초기화하거나
Computer Control 제공자를 전환하지 마세요.
권한은 작업을 수행하는 프로세스 또는 Bridge 호스트에 속합니다.
호출자에게 필요한 권한이 없으면 --no-remote를 전달하지 마세요.
설치된 명령 찾기
플래그 및 타겟팅 요구 사항을 확인하려면 리프 명령의 도움말을 사용하고, 명령 간에 플래그를 복사하지 마세요. 루트 도움말을 사용하여 사용 가능한 명령을 확인하세요:
peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help
V4에서는 이전 명령 루트가 제거되었습니다:
| 이전 명령 | V4 명령 |
|---|---|
list apps | app list |
image | see --no-elements (요소 검출 없이 픽셀만) |
hotkey | press (예: cmd+shift+t 코드 사용) |
swipe | drag --from … --to … |
다른 작업(클릭, 타이핑, 스크롤, 창 또는 메뉴 관리 등)은 peekaboo <command> --help를 사용하세요.
명령 옵션은 리프 명령 뒤에 두세요. --json은 구조화된 출력을 요청합니다.
검사, 작업, 확인
애플리케이션 목록과 대상의 최신 뷰로 시작하세요:
peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
--path /tmp/peekaboo-example.png --json
작업을 수행하기 전에 반환된 요소를 읽으세요. 작업은 의도한 앱, 창 및 최신 스냅샷에 연결하고, 예제 요소 ID를 재사용하지 마세요. 작업 후에는 UI를 다시 검사하고 요청한 결과를 확인하세요. 창이 변경되거나 대상이 오래되면 관찰을 새로고침하세요.
요소 검출 없이 스크린샷을 찍으려면:
peekaboo see --mode screen --screen-index 0 --no-elements --retina \
--path /tmp/peekaboo-screen.png --json
원시 키보드 코드는 명시적인 포그라운드 상호작용 또는 press가 수락한 최신 정확-창 수신이 필요합니다.
드래그는 항상 공유 커서를 이동하며 --foreground가 필요합니다. 포그라운드 상호작용이 승인된 경우:
peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json
실제 대상과 현재 관찰에서 얻은 좌표를 사용하세요. 800ms와 같은 명시적인 지속 시간 단위를 선호하고,
각 명령의 도움말에서 옵션과 전제 조건을 확인하세요.
문제 해결
- 명령 제거 오류가 발생하면 설치된 CLI가 명시한 대체 명령을 사용하세요.
- 호스트 또는 권한 실패 시, 선택한 호스트에 대해
peekaboo bridge status --json과peekaboo permissions status --json을 검사하세요. - 타겟팅 실패 시 리프 도움말을 읽고
see로 최신 UI 상태를 얻으세요. - macOS 15+에서는 비공개 창 선택기 프롬프트가 기본 Screen Recording 권한과 별도이며, Bridge 권한이 올바른 경우에도 나타날 수 있습니다.