​

OpenClaw macOS IPC 架构

​

目标

• 一个单一的 GUI 应用实例，负责所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
• 一个用于自动化的小表面：Gateway + 节点命令、进程内 computer.act，以及面向独立 UI 自动化客户端的 PeekabooBridge。
• 可预测的权限：始终使用相同的已签名 bundle ID，由 launchd 启动，因此 TCC 授权会保持有效。

​

工作原理

​

Gateway + 节点传输

• 应用运行 Gateway（本地模式），并作为节点连接到它。
• Agent 操作通过 node.invoke 执行（例如 system.run、system.notify、canvas.*）。
• 节点命令包括 canvas.*、camera.list、camera.snap、camera.clip、camera.ptz.status、camera.ptz.control、screen.snapshot、screen.record、computer.act、system.run 和 system.notify。
• 节点会报告一个 permissions 映射，以便 Agent 查看屏幕、摄像头、麦克风、语音、自动化或辅助功能访问权限是否可用。

​

Node 服务 + 应用 IPC

• 一个无头的节点宿主服务连接到 Gateway WebSocket。
• system.run 请求会通过本地 Unix 套接字（ExecApprovalsSocket.swift）转发到 macOS 应用。
• 应用在 UI 上下文中执行该命令，必要时提示用户，并返回输出。

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

​

PeekabooBridge（UI 自动化）

• 内置 Agent 的 computer 工具不使用这个套接字。配对的 macOS 节点会在应用进程中借助嵌入式 Peekaboo 服务来实现 computer.act。
• UI 自动化使用单独的 UNIX 套接字（~/Library/Application Support/OpenClaw/<socket>）以及 PeekabooBridge JSON 协议。
• 主机优先级顺序（客户端侧）：Peekaboo.app -> Claude.app -> OpenClaw.app -> 本地执行。
• 安全性：bridge 主机要求允许列表中的 TeamID（捆绑的 PeekabooBridgeHostCoordinator 会将固定团队以及应用自身的签名团队加入允许列表）；一个仅限 DEBUG 的同 UID 逃生通道由 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 保护（Peekaboo 约定）。
• 参见：PeekabooBridge 使用 了解详情。

​

运行流程

• 重启/重新构建：scripts/restart-mac.sh 会终止现有实例，通过 Swift 重新构建、重新打包并重新启动。它会自动检测可用的签名身份，并在未找到时回退到 --no-sign；传入 --sign 可强制要求签名（如果没有可用密钥则失败），或传入 --no-sign 强制走未签名路径。签名路径下在环境中设置的 SIGN_IDENTITY 会被取消设置，因此 scripts/codesign-mac-app.sh 自己的身份自动检测会选择证书。
• 单实例：应用会检查 NSWorkspace.runningApplications 中是否存在重复的 bundle ID，并在发现多个实例时退出（MenuBar.swift 中的 isDuplicateInstance()）。

​

加固说明

• 优先要求所有特权表面都匹配 TeamID。
• PeekabooBridge：PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1（仅 DEBUG）可能允许相同 UID 的调用者用于本地开发。
• 所有通信始终仅限本地；不会暴露网络套接字。
• TCC 提示仅来自 GUI 应用程序包；请在重建之间保持已签名的 bundle ID 稳定。
• Exec approvals 套接字加固：文件模式 0600、共享令牌存储在 state/openclaw.sqlite 的 exec_approvals_config 行中、对端 UID 检查（getpeereid）、HMAC-SHA256 挑战/响应，以及请求的短 TTL。

​

相关内容

• macOS 应用
• macOS IPC 流程（Exec 审批）。