OpenClaw를 활용한 macOS UI 자동화: Peekaboo Bridge 설정하기

UI 자동화를 구현하다 보면 권한 설정 문제로 골치 아픈 경우가 많습니다. 자동화 스크립트를 실행할 때마다 보안 팝업이 뜨거나, 매번 복잡한 권한 승인 과정을 거쳐야 한다면 개발 흐름이 쉽게 끊기곤 하죠.

이런 번거로움을 줄이고 macOS의 TCC 권한을 효율적으로 재사용하고 싶다면 Peekaboo Bridge가 좋은 해결책이 될 수 있습니다.

필요한 것

• OpenClaw macOS 앱
• peekaboo CLI

빠른 시작

OpenClaw를 UI 자동화 브로커로 활용해 5분 안에 설정을 끝내는 방법입니다.

1. 브리지 활성화: macOS용 OpenClaw 앱을 열고 Settings → Enable Peekaboo Bridge를 체크하세요.
2. 호스트 확인: 브리지가 활성화되면 OpenClaw가 로컬 UNIX socket 서버를 시작합니다.
3. 상태 체크: 터미널에서 아래 명령어를 입력해 현재 어떤 호스트가 활성화되어 있는지 확인하세요.

   peekaboo bridge status --verbose

4. 소켓 경로 수동 설정 (선택 사항): 특정 경로의 소켓을 사용해야 한다면 환경 변수를 설정할 수 있습니다.

   export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

Peekaboo 클라이언트는 기본적으로 Peekaboo.app, Claude.app, OpenClaw.app 순서로 호스트를 탐색합니다. OpenClaw는 가벼운 브로커 역할을 수행하며, 실제 시각적 오버레이는 Peekaboo.app에서 처리됩니다.

보안 및 스냅샷 동작

• 보안 검증: 브리지는 호출자의 code signatures를 확인합니다. Peekaboo와 OpenClaw의 TeamID가 포함된 allowlist를 통해 접근을 제한합니다.
• 타임아웃: 모든 요청은 약 10초 후에 만료됩니다.
• 권한 오류: 필요한 권한이 없을 경우 시스템 설정을 강제로 여는 대신 명확한 에러 메시지를 반환합니다.
• Snapshot 관리: Snapshot은 메모리에 저장되며 짧은 시간 후에 자동으로 만료됩니다. 데이터 유지가 더 오래 필요하다면 클라이언트에서 다시 캡처해야 합니다.

문제 해결

• “bridge client is not authorized” 에러가 발생할 때: 클라이언트가 제대로 서명되었는지 확인하세요. 디버그 모드에서 테스트 중이라면 아래 환경 변수를 사용해 서명되지 않은 클라이언트를 허용할 수 있습니다.

  PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1

• 호스트를 찾을 수 없을 때: OpenClaw.app이 실행 중인지 확인하고, macOS 시스템 설정에서 필요한 권한이 모두 부여되었는지 점검하세요.

설정 과정에서 도움이 필요하신가요? AI Setup Assistant에게 질문해 보세요.

다음 단계

• Peekaboo CLI 사용법 문서
• macOS 권한 관리 가이드