跳转至

Peekaboo 桥接

OpenClaw 可以将 PeekabooBridge 作为本地、权限感知的 UI 自动化代理来托管(PeekabooBridgeHostCoordinator,由 openclaw/Peekaboo Swift 软件包提供支持)。这使 peekaboo CLI 能够驱动 UI 自动化,同时复用 macOS 应用的 TCC 权限。

这是什么(以及不是什么)

  • 主机:OpenClaw.app 可以充当 PeekabooBridge 主机。
  • 客户端:peekaboo CLI,从 peekaboo.sh 安装(没有单独的 openclaw ui ... 命令界面)。
  • UI:视觉叠加层仍保留在 Peekaboo.app 中。OpenClaw 是一个轻量代理主机。

与其他桌面控制路径的关系

OpenClaw 有四条刻意保持独立的桌面控制路径:

  • PeekabooBridge 主机:OpenClaw.app 托管本地 PeekabooBridge socket。peekaboo CLI 作为客户端,并使用 OpenClaw.app 的 macOS 权限来执行截图、点击、菜单、对话框、Dock 操作和窗口管理。
  • 智能体驱动的计算机使用(computer.act):网关智能体内置的 computer 工具通过 screen.snapshot 捕获截图。它通过危险的 computer.act 节点命令驱动指针和键盘。macOS 节点在进程内完成 computer.act。它使用此桥接所暴露的嵌入式 Peekaboo 自动化服务,外加窄范围的 CoreGraphics 原语。它不经过 PeekabooBridge socket 或 peekaboo CLI。参见 Computer use。
  • Codex Computer Use:自带的 codex 插件会检查并可安装 Codex 的 computer-use MCP 插件(extensions/codex/src/app-server/computer-use.ts)。随后在 Codex 模式轮次中,Codex 会负责原生的桌面控制工具调用。OpenClaw 不会通过 PeekabooBridge 代理这些操作。
  • 直接 cua-driver MCP:OpenClaw 可以将 TryCua 的上游 cua-driver mcp 服务器注册为普通 MCP 服务器。这为智能体提供了 CUA 驱动自身的 schemas 以及 pid/window/element-index 工作流。它不经过 Codex marketplace 或 PeekabooBridge socket。

如需通过 OpenClaw.app 的权限感知桥接主机获得广泛的 macOS 自动化能力,请使用 Peekaboo。当网关智能体需要查看并控制桌面时,请使用智能体驱动的计算机使用;它通过统一的 computer.act 节点命令实现,任何视觉模型都可以驱动。当 Codex 模式智能体应依赖 Codex 的原生插件时,请使用 Codex Computer Use。如需将 CUA 驱动程序作为普通 MCP 服务器暴露给任何由 OpenClaw 管理的运行时,请使用直接的 cua-driver mcp。

启用桥接

在 macOS 应用中,打开 Dashboard → Settings → This Mac → Capabilities,并启用 Peekaboo Bridge。该桥接要求开启 Computer Control,因为两者都会授予本地 UI 自动化权限。Computer Control 关闭时,主机不会运行。若要在没有 Computer Control 的情况下驱动 Peekaboo,可以改为运行 Peekaboo 自己的 Mac 应用作为主机。

启用后(且 Computer Control 开启),OpenClaw 会在 ~/Library/Application Support/OpenClaw/<socket-name> 启动本地 UNIX socket 服务器。如果停用,主机将停止,peekaboo 会回退到其他可用主机。协调器还会维护指向当前 socket 的旧版 socket 符号链接(Application Support 下的 clawdbot、clawdis、moltbot),供较旧的 peekaboo 安装使用。

对于一次性的无人值守运行,--attach-only --background-only 会抑制自动窗口和 GUI 所属 Keychain 的加载。常驻提权主机是面向 OpenClaw Foundation 发布操作员的受管部署路径。其 package 命令需要 Foundation 签名身份和公证凭据。OpenClaw 不会发布可供常规下载的提权归档。请仅安装由授权发布操作员提供的、经认证且带有源地址的归档:

cd /path/to/elevation-artifact-set
export PREFIX="OpenClaw-<full-openclaw-sha>-Peekaboo-<full-peekaboo-sha>-stable"
export INSTALLER_SHA256="<authenticated-installer-sha256>"
export RECEIPT_SHA256="<authenticated-receipt-sha256>"
[[ "$(shasum -a 256 "$PREFIX-installer.sh" | awk '{print $1}')" == "$INSTALLER_SHA256" ]] || exit 1
shasum -a 256 -c "$PREFIX.zip.sha256"
shasum -a 256 -c "$PREFIX-installer.sh.sha256"
./"$PREFIX-installer.sh" verify \
  --archive "$PREFIX.zip" \
  --receipt "$PREFIX.json" \
  --receipt-sha256 "$RECEIPT_SHA256"
./"$PREFIX-installer.sh" migration-plan \
  --migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" install \
  --archive "$PREFIX.zip" \
  --receipt "$PREFIX.json" \
  --receipt-sha256 "$RECEIPT_SHA256" \
  --migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" status --state-dir "<existing-state-dir>"

传输完整的工件集合:归档、收据、可移植安装程序以及两个校验和文件。目标 Mac 不需要有 OpenClaw 源码检出。授权操作员交接时必须独立提供安装程序和收据的 SHA-256 摘要。在规划切换之前,请使用经过认证的收据摘要运行 verify。随后,收据会选择已批准的归档。verify 会重新验证 Foundation 签名的应用、公证、staple、Gatekeeper 结果、架构、entitlements 以及两个源码修订版本。可移植安装程序不在应用代码签名的覆盖范围内,因此这种显式的双摘要发布操作员交接仍然是内部信任边界的一部分。

提权工件需要通用共享应用代码,并在 Contents/Resources/runtime/ 下放置一个私有运行时。其 bin/bun 和 lib/libsqlite3.dylib 必须同时包含 arm64 和 x86_64 的 Mach-O 分片。无论目标 Mac 的架构如何,verify 都会对两者进行检查。该运行时在架构之间共享完整的 OpenClaw 软件包,包括 CLI、worker、浏览器设置和 Control UI 入口点。软件包构建元数据必须与应用版本、源码提交、构建时间戳以及 OpenClawRuntimeBuildID 匹配。原生依赖(包括 addons、静态归档以及没有可执行权限位的库)必须支持 arm64 或 x86_64;架构特定的 Darwin 软件包在共享树中共存。非本平台的原生代码以及应用中的任何 Node 可执行文件都会被拒绝。可签名的 Mach-O 镜像还必须为每个分片暴露原生签名元数据。即使是严格的全应用验证成功,通用资源签名也不能作为原生签名的证据。兼容的 thin、fat32 和 fat64 静态归档仍然是受应用密封和架构检查保护的资源。它们不需要独立的 Mach-O 签名。混合归档/原生容器无法通过验证。检查绝不会对提供的 payload 进行瘦身或重写。缺少运行时入口点或所需的 Bun/SQLite 分片、逃逸或循环的运行时符号链接,以及运行时之外的 thin 共享应用可执行文件或可执行库,都会导致验证失败。违反此闭包规则的依赖必须在打包阶段修复,而不能被排除在验证之外。可移植安装程序既不需要源码检出,也不需要单独的清单辅助工具。

标准和提权打包都会从包含生产依赖的完整发布包构建全新运行时。暂存阶段会移除那些声明支持的 OS 或 CPU 不包含所需架构的软件包,并移除基于 Node 的命令垫片。物化则保留 JavaScript、WASM、其他资源、模式以及所包含的相对符号链接,同时省略无法在任何选定的 Darwin 架构上运行的原生镜像。匹配的通用二进制文件将保持原样。在保留的软件包中,Windows 命名的源代码、脚本和 README 文件仍会保留;仅凭目录名称不会选择省略文件。无法分类的原生镜像以及会逃逸、循环或变成悬空的链接会阻止打包。两条路径使用相同的运行时验证和发布流程。物化不会改变构建元数据。提权应用保留库验证,并拒绝 DISABLE_LIBRARY_VALIDATION=1。其私有 Bun 可执行文件具有插件 native-addon 例外;其他辅助程序保留库验证。

托管提权工作流会升级一台已配对的 Mac。其选定的状态和配置必须定义一条应用可读的直接远程 Gateway 路由,并使用字符串令牌或密码认证;所选 macOS 节点身份必须已经配对。migration-plan 执行这些检查,不会更改应用、进程、LaunchAgent、状态或 Gateway。它识别规范的 CLI 管理作业 ai.openclaw.node 以及由应用支持的后台 LaunchAgent。如果旧应用在后台模式下运行且没有 LaunchAgent,请使用 --adopt-running-app 而不是 --migrate-launch-agent,并在状态/配置路径不是默认路径时显式传递它们。

已安装的作业隐式指定了 --elevation-host。它会保持 Bridge、控制通道、Mac 节点、Gateway 连接和终止处理处于活动状态,同时禁用自动窗口、更新器启动、Dock 提升、配对和执行批准提示器、Quick Chat 热键、语音和 Cookie 服务,以及 GUI 持有的 Keychain 读取。status 报告缺少的屏幕录制、辅助功能或事件合成权限。主机绝不会打开系统设置来授予这些权限。只要 launchd 拥有的进程已准备好连接 Bridge,安装即告成功,即使这些权限授予仍不完整;但只有在精确配对的节点身份以 openclaw-macos/node 身份重新连接,并带有新应用版本、computer 能力、screen.snapshot、computer.act 和计算机使用描述符后,安装才会提交。安装程序不复制 Gateway 凭据或交互式 PATH。它只携带已验证的状态/配置所有权路径,并使用配置中现有的路由和认证。status 会重新检查 Bridge、Gateway 节点和 TCC 就绪状态。安装程序使用独立的 ai.openclaw.mac.elevation-host 作业,并拒绝与普通的登录时启动(ai.openclaw.mac)竞争或重写它。

切换是事务性的:安装程序对确切的应用和源 plist 进行快照,停止先前的所有者,安装替换版本,如果 launchd、Bridge 或 Gateway 节点认证失败,则自动恢复原始字节和已加载状态。安装收据绑定回滚 plist 摘要、先前应用的 CDHash 以及任何先前受管理的安装收据。代际唯一的备份允许连续升级。recover 将替换下来的应用保存在唯一的证据目录中,恢复先前的收据,并拒绝覆盖由其他所有者重新创建的源 LaunchAgent 路径。

提权归档由 Foundation 签名、经公证并已附加公证票据,以 OpenClaw 和 Peekaboo 的完整源代码提交命名,且只包含 OpenClaw.app。其收据绑定归档和 portable-installer 的名称与摘要、OpenClaw 和 Peekaboo 源代码修订版本、签名者、各架构 CDHash、架构、权利摘要以及 Apple 公证提交 ID。此工作流不包含任何 AppleScript 或 Apple Events 权利。

客户端发现顺序

Peekaboo 客户端通常按以下顺序尝试主机:

  1. Peekaboo.app(完整 UX)
  2. Claude.app(如果已安装)
  3. OpenClaw.app(精简代理)

使用 peekaboo bridge status --verbose 查看哪个主机处于活动状态以及正在使用哪个套接字路径。可通过以下方式覆盖:

export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

安全性与权限

  • Bridge 会检查调用方代码签名。生产版 OpenClaw 主机只接受由 Peekaboo 规范的当前/旧版发布签名者集合(FWJYW4S8P8 和 Y5PE65HELJ)签名的确切 Peekaboo CLI 包(boo.peekaboo.peekaboo)。共享应用的 UID 或使用由应用开发团队签名的另一个客户端都是不够的。
  • 对于辅助功能,应优先使用已签名的 Bridge/应用身份,而不是通用的 node 运行时。向 node 授予辅助功能权限会让该 Node 可执行文件启动的任何软件包都继承 GUI 自动化访问权限。请参阅 macOS 权限。
  • 请求在 10 秒后超时(requestTimeoutSec: 10)。
  • 如果缺少所需权限,Bridge 会返回明确的错误消息,而不会启动系统设置。

快照行为(自动化)

InMemorySnapshotManager 将快照存储在内存中。它应用 10 分钟的有效期窗口和最多 50 个快照的上限。清理不会删除工件。如果您需要更长的保留时间,请从客户端重新捕获。

故障排除

  • 更新 OpenClaw.app 以获取内嵌的自动化修复,包括关闭主机自身窗口时的崩溃。仅更新 peekaboo CLI 不会替换 Bridge 主机的窗口自动化代码。
  • 如果 peekaboo 报告 "bridge client is not authorized",请确保客户端已正确签名。作为替代方案,仅在 debug 模式下使用 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 运行主机。
  • 如果找不到主机,请打开其中一个主机应用(Peekaboo.app 或 OpenClaw.app)。然后检查权限是否已授予。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw