Peekaboo 桥接

OpenClaw 可以将 PeekabooBridge 作为本地的、权限感知的 UI 自动化代理进行托管（PeekabooBridgeHostCoordinator，由 openclaw/Peekaboo Swift 包提供支持）。这让 peekaboo CLI 能够驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。

这是什么（以及不是什么）¶

• 主机（Host）：OpenClaw.app 可以作为 PeekabooBridge 主机。
• 客户端（Client）：peekaboo CLI，从 peekaboo.sh 安装（没有单独的 openclaw ui ... 接口）。
• UI：可视化叠加层保留在 Peekaboo.app 中。OpenClaw 是一个轻量代理主机。

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

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

• PeekabooBridge 主机：OpenClaw.app 托管本地 PeekabooBridge 套接字。peekaboo CLI 作为客户端，使用 OpenClaw.app 的 macOS 权限进行截图、点击、菜单、对话框、Dock 操作和窗口管理。
• 代理驱动的计算机使用（computer.act）：网关代理内置的 computer 工具通过 screen.snapshot 捕获截图。它通过危险的 computer.act 节点命令驱动指针和键盘。macOS 节点在进程内完成 computer.act。它使用此桥暴露的嵌入式 Peekaboo 自动化服务，以及有限的 CoreGraphics 原语。它不经过 PeekabooBridge 套接字或 peekaboo CLI。参见 计算机使用。
• Codex 计算机使用：捆绑的 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/窗口/元素索引工作流。它不通过 Codex 市场或 PeekabooBridge 套接字路由。

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

启用桥接器¶

在 macOS 应用中，打开 仪表盘（Dashboard）→ 设置（Settings）→ 这台 Mac（This Mac）→ 功能（Capabilities），并启用 Peekaboo Bridge。桥接器要求 计算机控制（Computer Control） 处于开启状态，因为两者都授予本地 UI 自动化权限。如果计算机控制关闭，主机将不会运行。要在没有计算机控制的情况下驱动 Peekaboo，请改为运行 Peekaboo 自己的 Mac 应用作为主机。

启用后（并且计算机控制开启），OpenClaw 会在 ~/Library/Application Support/OpenClaw/<socket-name> 启动一个本地 UNIX 套接字服务器。如果禁用，主机停止运行，peekaboo 会回退到其他可用的主机。协调器还会维护指向当前套接字的旧版套接字符号链接（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/node-worker/ 下的 arm64 和 x86_64 两种 worker 负载。打包者必须同时提供两者。无论目标 Mac 的架构如何，verify 都会检查两者。每个 worker 必须包含 Mach-O Node 运行时、OpenClaw 包入口点，以及与应用的版本、源码提交、构建时间戳和 worker 构建 ID 匹配的构建元数据。每个 worker 中的所有原生代码，包括插件（addons）、静态归档以及没有可执行权限位的库，都必须支持其所在目录的架构。允许通用（universal）Mach-O 代码。拒绝外来平台的原生代码。可签名的 Mach-O 镜像还必须为每个分片（slice）暴露原生签名元数据。通用的资源签名，即使严格的全应用验证成功，也不能作为原生签名的证据。兼容的 thin、fat32 和 fat64 静态归档仍然是受应用密封（app seal）和架构检查保护的资源。它们不需要独立的 Mach-O 签名。混合的归档/原生容器会验证失败。检查永远不会对所提供的负载进行瘦身或重写。缺失或意外的架构树、逃逸或循环的 worker 符号链接，以及 thin 共享可执行文件或可执行库，都会导致验证失败。违反此闭包的依赖必须在打包中修复，而不是从验证中排除。便携式安装程序既不需要源码检出，也不需要单独的资源清单辅助工具。

标准和 elevation 打包都会从完整的已安装软件包构建全新的 worker，且不会更改该输入。 它会保留 JavaScript、WASM、其他资源、模式以及所包含的相对符号链接，并且仅省略 无法在所选 Darwin 架构上运行的原生映像。匹配的通用二进制文件保持完整。以 Windows 命名的源代码、 脚本和 README 文件会保留。目录名称不会决定文件的省略。无法分类的原生映像以及 会逃逸、循环或变为悬空的链接会导致打包停止。 两条路径都使用相同的 worker 验证和发布流程。构建元数据在物化过程中保持不变。

受管理的 elevation 工作流用于升级已配对的 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 提升、配对和 exec 审批展示器、Quick Chat 热键、语音和 cookie 服务以及 GUI 拥有的 Keychain 读取。status 会报告缺失的屏幕录制、辅助功能或事件合成权限。该主机绝不会打开系统设置来授予这些权限。一旦 launchd 拥有的进程具备 Bridge 就绪状态，即使这些授权仍未完成，安装也会成功；但只有在精确配对的节点身份以新应用版本、computer 能力、screen.snapshot、computer.act 和 computer-use 描述符重新连接为 openclaw-macos/node 后，安装才会提交。安装程序不会复制任何 Gateway 凭据或交互式 PATH。它仅携带已验证的状态/配置所有权路径，并使用配置中现有的路由和认证。status 会重新检查 Bridge、Gateway 节点和 TCC 的就绪状态。安装程序使用独立的 ai.openclaw.mac.elevation-host 任务，并拒绝与普通的登录时启动（ai.openclaw.mac）竞争或重写它。

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

elevation 归档文件经过 Foundation 签名、公证、装订，以 OpenClaw 和 Peekaboo 的完整源代码提交命名，并且恰好包含 OpenClaw.app。其回执绑定归档文件和便携式安装程序的名称与摘要、OpenClaw 和 Peekaboo 源代码修订版本、签名者、各架构 CDHash、架构、entitlement 摘要以及 Apple 公证提交 ID。此工作流不包含任何 AppleScript 或 Apple Events entitlement。

客户端发现顺序¶

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 或使用由应用开发团队签名的其他客户端是不够的。
• 对于辅助功能（Accessibility），应优先使用已签名的 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），然后检查权限是否已授予。

相关文档¶

• macOS app
• macOS permissions
• Codex Computer Use