macOS IPC

기준일: 2026-07-26
공식 기준: macOS IPC

macOS IPC 문서는 OpenClaw 공식 문서(platforms/mac/xpc)를 한국어로 정리한 가이드입니다. macOS IPC architecture for OpenClaw app, gateway node transport, and PeekabooBridge 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

macOS IPC architecture for OpenClaw app, gateway node transport, and PeekabooBridge

한국어 가이드 범위: platforms/mac/xpc 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Goals
동작 방식
Gateway + node transport
Node service + app IPC
PeekabooBridge (UI automation)
Operational flows
Hardening notes
관련 문서

상세 내용

OpenClaw macOS IPC architecture

A local Unix socket connects the node host service to the macOS app for exec approvals and system.run. An openclaw-mac debug CLI (apps/macos/Sources/OpenClawMacCLI) exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and node.invoke. The node-backed computer.act path runs embedded Peekaboo automation in-process; standalone Peekaboo clients use PeekabooBridge.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Goals

주요 항목:

Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
A small surface for automation: Gateway + node commands, in-process computer.act, plus PeekabooBridge for standalone UI automation clients.
Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.

동작 방식

이 섹션의 세부 항목은 공식 문서 동작 방식를 참고하세요.

Gateway + node transport

주요 항목:

The app runs the Gateway (local mode) and connects to it as a node.
Agent actions are performed via node.invoke (e.g. system.run, system.notify, canvas.*).
Node commands include canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run, and system.notify.
The node reports a permissions map so agents can see whether screen, camera, microphone, speech, automation, or accessibility access is available.

Node service + app IPC

주요 항목:

A headless node host service connects to the Gateway WebSocket.
system.run requests are forwarded to the macOS app over a local Unix socket (ExecApprovalsSocket.swift).
The app performs the exec in UI context, prompts if needed, and returns output.

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

PeekabooBridge (UI automation)

주요 항목:

The built-in agent computer tool does not use this socket. A paired macOS node fulfills computer.act in the app process with embedded Peekaboo services.
UI automation uses a separate UNIX socket (~/Library/Application Support/OpenClaw/<socket>) and the PeekabooBridge JSON protocol.
Host preference order (client-side): Peekaboo.app -> Claude.app -> OpenClaw.app -> local execution.
Security: bridge hosts require an allowlisted TeamID (the bundled PeekabooBridgeHostCoordinator allowlists a fixed team plus the app's own signing team); a DEBUG-only same-UID escape hatch is guarded by PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (Peekaboo convention).
See: PeekabooBridge usage for details.

Operational flows

주요 항목:

Restart/rebuild: scripts/restart-mac.sh kills existing instances, rebuilds via Swift, repackages, and relaunches. It auto-detects an available signing identity and falls back to --no-sign if none is found; pass --sign to require signing (fails if no key is available) or --no-sign to force the unsigned path. SIGN_IDENTITY set in the environment is unset on the signed path, so scripts/codesign-mac-app.sh's own identity auto-detection picks the cert.
Single instance: the app checks NSWorkspace.runningApplications for a duplicate bundle ID and exits if more than one instance is found (isDuplicateInstance() in MenuBar.swift).

Hardening notes

주요 항목:

Prefer requiring a TeamID match for all privileged surfaces.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) may allow same-UID callers for local development.
All communication remains local-only; no network sockets are exposed.
TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds.
Exec approvals socket hardening: file mode 0600, shared token, peer-UID check (getpeereid), HMAC-SHA256 challenge/response, and a short TTL on requests.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/xpc
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

macOS IPC

기준일: 2026-07-26
공식 기준: macOS IPC

핵심 요약

macOS IPC architecture for OpenClaw app, gateway node transport, and PeekabooBridge

한국어 가이드 범위: platforms/mac/xpc 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Goals
동작 방식
Gateway + node transport
Node service + app IPC
PeekabooBridge (UI automation)
Operational flows
Hardening notes
관련 문서

상세 내용

OpenClaw macOS IPC architecture

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Goals

주요 항목:

Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
A small surface for automation: Gateway + node commands, in-process computer.act, plus PeekabooBridge for standalone UI automation clients.
Predictable permissions: always the same signed bundle ID, launched by launchd, so TCC grants stick.

동작 방식

이 섹션의 세부 항목은 공식 문서 동작 방식를 참고하세요.

Gateway + node transport

주요 항목:

The app runs the Gateway (local mode) and connects to it as a node.
Agent actions are performed via node.invoke (e.g. system.run, system.notify, canvas.*).
Node commands include canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run, and system.notify.
The node reports a permissions map so agents can see whether screen, camera, microphone, speech, automation, or accessibility access is available.

Node service + app IPC

주요 항목:

A headless node host service connects to the Gateway WebSocket.
system.run requests are forwarded to the macOS app over a local Unix socket (ExecApprovalsSocket.swift).
The app performs the exec in UI context, prompts if needed, and returns output.

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

PeekabooBridge (UI automation)

주요 항목:

The built-in agent computer tool does not use this socket. A paired macOS node fulfills computer.act in the app process with embedded Peekaboo services.
UI automation uses a separate UNIX socket (~/Library/Application Support/OpenClaw/<socket>) and the PeekabooBridge JSON protocol.
Host preference order (client-side): Peekaboo.app -> Claude.app -> OpenClaw.app -> local execution.
Security: bridge hosts require an allowlisted TeamID (the bundled PeekabooBridgeHostCoordinator allowlists a fixed team plus the app's own signing team); a DEBUG-only same-UID escape hatch is guarded by PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (Peekaboo convention).
See: PeekabooBridge usage for details.

Operational flows

주요 항목:

Restart/rebuild: scripts/restart-mac.sh kills existing instances, rebuilds via Swift, repackages, and relaunches. It auto-detects an available signing identity and falls back to --no-sign if none is found; pass --sign to require signing (fails if no key is available) or --no-sign to force the unsigned path. SIGN_IDENTITY set in the environment is unset on the signed path, so scripts/codesign-mac-app.sh's own identity auto-detection picks the cert.
Single instance: the app checks NSWorkspace.runningApplications for a duplicate bundle ID and exits if more than one instance is found (isDuplicateInstance() in MenuBar.swift).

Hardening notes

주요 항목:

Prefer requiring a TeamID match for all privileged surfaces.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) may allow same-UID callers for local development.
All communication remains local-only; no network sockets are exposed.
TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds.
Exec approvals socket hardening: file mode 0600, shared token, peer-UID check (getpeereid), HMAC-SHA256 challenge/response, and a short TTL on requests.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/xpc
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

macOS IPC

핵심 요약

문서 구성

상세 내용

OpenClaw macOS IPC architecture

Goals

동작 방식

Gateway + node transport

Node service + app IPC

PeekabooBridge (UI automation)

Operational flows

Hardening notes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

macOS IPC

핵심 요약

문서 구성

상세 내용

OpenClaw macOS IPC architecture

Goals

동작 방식

Gateway + node transport

Node service + app IPC

PeekabooBridge (UI automation)

Operational flows

Hardening notes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드