OpenClaw macOS IPC 아키텍처 가이드

macOS에서 백그라운드 서비스와 GUI 앱 사이의 통신을 구현하다 보면 권한 관리가 정말 까다롭다는 걸 느끼실 거예요. 특히 시스템 권한(TCC) 승인이 매번 초기화되거나, 프로세스 간 통신(IPC) 보안을 설정하는 과정에서 개발 흐름이 끊기는 경우가 많죠.

OpenClaw는 이러한 문제를 해결하기 위해 로컬 Unix socket과 Gateway를 활용한 구조를 사용해요. 권한 승인을 안정적으로 유지하면서도 에이전트의 동작을 효율적으로 제어할 수 있는 아키텍처를 함께 살펴볼게요.

필요한 것

시작하기 전에 소스 문서에 언급된 다음 사항들이 준비되어 있어야 해요.

• 유효한 Apple 개발자 인증서 (SIGN_IDENTITY)
• scripts/restart-mac.sh 실행 권한
• macOS 환경 및 Swift 빌드 도구

빠른 시작

5분 안에 OpenClaw macOS 환경을 빌드하고 실행하는 방법이에요.

1. 환경 변수 설정 및 재시작 스크립트 실행 터미널에서 본인의 개발자 ID를 넣어 아래 명령어를 실행하세요. 기존 인스턴스를 종료하고 LaunchAgent를 새로 등록해요.

   SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh

2. 연결 확인 openclaw-mac 디버그 CLI를 사용해 연결 상태를 확인하세요.

   openclaw-mac discovery

3. 서비스 작동 확인 앱이 실행되면 GUI 컨텍스트에서 system.run 요청을 처리할 준비가 끝나요.

How it works

OpenClaw의 통신 구조는 크게 세 가지 축으로 나뉘어 있어요.

Gateway + Node transport

앱은 로컬 모드에서 Gateway를 실행하고, 스스로를 하나의 Node로 연결해요. 에이전트의 모든 액션(예: system.run, system.notify, canvas.*)은 node.invoke를 통해 수행돼요.

Node service + App IPC

실제 명령을 수행하는 과정은 다음과 같아요.

• Node host service: Gateway WebSocket에 연결되어 대기해요.
• IPC 통신: system.run 요청이 오면 로컬 Unix socket을 통해 macOS 앱으로 전달돼요.
• UI 컨텍스트 실행: 앱은 필요한 경우 사용자에게 프롬프트를 띄우고, UI 컨텍스트에서 명령을 실행한 뒤 결과를 반환해요.

PeekabooBridge (UI 자동화)

UI 자동화는 bridge.sock이라는 별도의 UNIX socket과 PeekabooBridge JSON 프로토콜을 사용해요. 클라이언트 측에서는 Peekaboo.app, Claude.app, OpenClaw.app 순서로 호스트를 찾아요.

Hardening & Security

보안을 위해 OpenClaw는 다음과 같은 설정을 강제해요.

• TeamID 매치: 권한이 필요한 모든 표면에서 TeamID가 일치하는지 확인해요.
• IPC 보안: Socket 모드를 0600으로 제한하고, 토큰 기반 인증, HMAC 챌린지/응답, 짧은 TTL을 적용해요.
• 로컬 전용: 모든 통신은 로컬에서만 이루어지며 외부 네트워크 소켓은 노출되지 않아요.

문제 해결

문제가 발생하면 다음 내용을 확인해 보세요.

• 앱이 즉시 종료되는 경우: 동일한 Bundle ID를 가진 다른 인스턴스가 이미 실행 중인지 확인하세요. OpenClaw는 단일 인스턴스 원칙을 지키기 위해 중복 실행 시 조기 종료돼요.
• 디버그 환경에서 소켓 연결 실패: 서명되지 않은 클라이언트로 로컬 개발을 진행 중이라면 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 환경 변수가 설정되어 있는지 확인하세요. (DEBUG 모드 전용)

---

질문이 있거나 설정 중 도움이 필요하면 AI Setup Assistant에게 물어보세요!

다음 단계

• PeekabooBridge 사용법
• macOS TCC 권한 최적화 가이드