macOS IPC 架构

macOS 应用使用本地 Unix socket 连接节点宿主服务与 macOS 应用，用于 exec 审批和 system.run。Agent 动作仍通过 Gateway WebSocket 和 node.invoke 流转。

架构目标

• 单一 GUI 应用实例拥有所有 TCC 相关工作（通知、屏幕录制、麦克风、语音、AppleScript）
• 自动化的小型接口：Gateway + 节点命令，加上 PeekabooBridge 用于 UI 自动化
• 可预测的权限：始终使用相同的已签名 Bundle ID，由 launchd 启动

工作原理

Gateway + 节点传输

• 应用运行 Gateway（本地模式）并作为节点连接
• Agent 动作通过 node.invoke 执行（如 system.run、system.notify、canvas.*）

节点服务 + 应用 IPC

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

• 无头节点宿主服务连接 Gateway WebSocket
• system.run 请求通过本地 Unix socket 转发到 macOS 应用
• 应用在 UI 上下文中执行，必要时提示用户，返回输出

PeekabooBridge（UI 自动化）

• 使用独立 UNIX socket（bridge.sock）和 PeekabooBridge JSON 协议
• 客户端优先顺序：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行
• 安全：bridge 宿主要求允许的 TeamID

安全加固

• socket 模式 0600，token，peer-UID 检查，HMAC 挑战/响应，短 TTL
• 所有通信仅限本地；不暴露网络 socket
• TCC 提示仅来自 GUI 应用 bundle；保持签名 Bundle ID 稳定

操作流程

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

相关链接

• platform-macos — macOS 平台总览
• platform-mac-peekaboo — PeekabooBridge 集成