OpenClaw macOS IPC 아키텍처

현재 모델: 로컬 Unix 소켓이 node host service를 exec 승인 + system.run을 위한 macOS 앱에 연결합니다. 발견/연결 확인을 위한 openclaw-mac 디버그 CLI가 존재합니다; 에이전트 액션은 여전히 Gateway WebSocket 및 node.invoke를 통해 흐릅니다. UI 자동화는 PeekabooBridge를 사용합니다.

목표

  • 모든 TCC 대면 작업 (알림, 화면 녹화, 마이크, 음성, AppleScript)을 소유하는 단일 GUI 앱 인스턴스.
  • 자동화를 위한 작은 인터페이스: Gateway + node 명령, 그리고 UI 자동화를 위한 PeekabooBridge.
  • 예측 가능한 권한: 항상 동일한 서명된 번들 ID, launchd에 의해 시작되므로 TCC 부여가 유지됩니다.

작동 방식

Gateway + node 전송

  • 앱은 Gateway를 실행하고 (로컬 모드) 노드로 연결합니다.
  • 에이전트 액션은 node.invoke를 통해 수행됩니다 (예: system.run, system.notify, canvas.*).

Node service + 앱 IPC

  • 헤드리스 node host service가 Gateway WebSocket에 연결합니다.
  • system.run 요청은 로컬 Unix 소켓을 통해 macOS 앱으로 포워딩됩니다.
  • 앱은 UI 컨텍스트에서 exec를 수행하고, 필요 시 프롬프트하며, 출력을 반환합니다.

다이어그램 (SCI):

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

PeekabooBridge (UI 자동화)

  • UI 자동화는 별도의 UNIX 소켓 bridge.sock과 PeekabooBridge JSON 프로토콜을 사용합니다.
  • 호스트 선호 순서 (클라이언트 측): Peekaboo.app → Claude.app → OpenClaw.app → 로컬 실행.
  • 보안: 브리지 호스트는 허용된 TeamID를 요구합니다; DEBUG 전용 same-UID 탈출구는 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1로 보호됩니다 (Peekaboo 규칙).
  • 참조: 세부 정보는 PeekabooBridge usage 참조.

운영 플로우

  • 재시작/재빌드: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • 기존 인스턴스 종료
    • Swift 빌드 + 패키지
    • LaunchAgent 작성/부트스트랩/kickstart
  • 단일 인스턴스: 동일한 번들 ID를 가진 다른 인스턴스가 실행 중이면 앱이 조기 종료.

강화 참고사항

  • 모든 권한 있는 인터페이스에 대해 TeamID 일치를 요구하는 것을 선호합니다.
  • PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG 전용)은 로컬 개발을 위해 same-UID 호출자를 허용할 수 있습니다.
  • 모든 통신은 로컬 전용으로 유지됩니다; 네트워크 소켓이 노출되지 않습니다.
  • TCC 프롬프트는 GUI 앱 번들에서만 발생합니다; 서명된 번들 ID를 재빌드 시에도 안정적으로 유지하세요.
  • IPC 강화: 소켓 모드 0600, 토큰, peer-UID 확인, HMAC challenge/response, 짧은 TTL.
← 문서로 돌아가기