OpenClaw macOS IPC 架构

当前模型： 本地 Unix socket 将 node host service 连接到 macOS 应用，用于 exec 批准 + system.run。存在 openclaw-mac 调试 CLI 用于发现/连接检查；agent 操作仍通过 Gateway WebSocket 和 node.invoke 流转。UI 自动化使用 PeekabooBridge。

目标

  • 拥有所有面向 TCC 工作（notifications、screen recording、mic、speech、AppleScript）的单个 GUI 应用实例。
  • 用于自动化的小表面：Gateway + node 命令，加上用于 UI 自动化的 PeekabooBridge。
  • 可预测的权限：始终相同的签名 bundle ID，由 launchd 启动，因此 TCC 授予保持。

工作原理

Gateway + node 传输

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

Node service + app IPC

  • 无头 node host service 连接到 Gateway WebSocket。
  • system.run 请求通过本地 Unix socket 转发到 macOS 应用。
  • 应用在 UI 上下文中执行 exec，根据需要提示，并返回输出。

图表（SCI）：

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

PeekabooBridge（UI 自动化）

  • UI 自动化使用名为 bridge.sock 的单独 UNIX socket 和 PeekabooBridge JSON 协议。
  • 主机偏好顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
  • 安全：bridge 主机需要允许的 TeamID；DEBUG-only 同 UID 逃生舱口由 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 保护（Peekaboo 惯例）。
  • 参见：PeekabooBridge usage 了解详情。

操作流程

  • 重启/重建：SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • 杀死现有实例
    • Swift 构建 + 打包
    • 写入/引导/启动 LaunchAgent
  • 单实例：如果具有相同 bundle ID 的另一个实例正在运行，应用提前退出。

强化注意事项

  • 对所有特权表面优先需要 TeamID 匹配。
  • PeekabooBridge：PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1（DEBUG-only）可能允许同 UID 调用者用于本地开发。
  • 所有通信保持仅本地；不暴露网络 socket。
  • TCC 提示仅源自 GUI 应用包；在重建时保持签名的 bundle ID 稳定。
  • IPC 强化：socket 模式 0600、token、peer-UID 检查、HMAC 质询/响应、短 TTL。
← 返回文档首页