OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS 配套应用

macOS 进程间通信

OpenClaw macOS IPC 架构

本地 Unix 套接字将节点主机服务连接到 macOS 应用，用于 Exec 审批和 system.run。项目提供了一个 openclaw-mac 调试 CLI（apps/macos/Sources/OpenClawMacCLI），用于设备发现和连接检查；智能体操作仍通过 Gateway 网关 WebSocket 和 node.invoke 传递。由节点支持的 computer.act 路径在进程内运行嵌入式 Peekaboo 自动化；独立 Peekaboo 客户端则使用 PeekabooBridge。

目标

  • 由单个 GUI 应用实例负责所有涉及 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
  • 提供精简的自动化接口：Gateway 网关 + 节点命令、进程内 computer.act，以及供独立 UI 自动化客户端使用的 PeekabooBridge。
  • 可预测的权限：始终使用同一个已签名的捆绑包 ID，并由 launchd 启动，以确保持久保留 TCC 授权。

工作原理

Gateway 网关 + 节点传输

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

节点服务 + 应用 IPC

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

示意图（SCI）：

text
智能体 -> Gateway 网关 -> 节点服务 (WS)                            |  IPC (UDS + 令牌 + HMAC + TTL)                            v                        Mac 应用 (UI + TCC + system.run)

PeekabooBridge（UI 自动化）

  • 内置的智能体 computer 工具不使用此套接字。已配对的 macOS 节点通过嵌入式 Peekaboo 服务，在应用进程中完成 computer.act。
  • UI 自动化使用单独的 UNIX 套接字（~/Library/Application Support/OpenClaw/<socket>）和 PeekabooBridge JSON 协议。
  • 主机优先顺序（客户端侧）：Peekaboo.app -> Claude.app -> OpenClaw.app -> 本地执行。
  • 安全性：桥接主机要求 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 中是否存在捆绑包 ID 重复项；如果发现多个实例，则退出（MenuBar.swift 中的 isDuplicateInstance()）。

加固说明

  • 对所有特权接口，建议要求 TeamID 匹配。
  • PeekabooBridge：PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1（仅限 DEBUG）可允许同 UID 调用方进行本地开发。
  • 所有通信均保持仅限本地；不会暴露任何网络套接字。
  • TCC 提示仅由 GUI 应用捆绑包发起；在重新构建时应保持已签名的捆绑包 ID 稳定。
  • Exec 审批套接字加固：文件模式 0600、共享令牌、对端 UID 检查（getpeereid）、HMAC-SHA256 质询/响应，以及较短的请求 TTL。

相关内容

Was this useful?
On this page

On this page