OpenClaw之父发布Peekaboo工具

Peekaboo 现在已经在 OpenClaw 组织下。这个项目看起来很容易被误解：一个给 Agent 截图、再让模型判断下一步怎么点的工具。

源码读下来，我更愿意把它理解成 macOS Agent 的本地执行层。截图只是入口，它真正解决的是另一个问题：Agent 怎么稳定理解桌面 UI，并且在 macOS 权限模型下面执行动作。

它是什么

Peekaboo 的表层能力很直观：截屏、窗口捕获、识别 UI 元素、点击、输入、滚动、操作菜单、管理窗口和 Dock。它也可以作为 MCP server 暴露给 Codex、Claude Code、Cursor 这类客户端。

真正有意思的是它把这些能力接成了一条链。

Agent 先通过 see 看当前窗口，Peekaboo 生成带元素 ID 的 UI map。后续动作不需要猜坐标，可以说点击某个元素 ID，或者针对某个 query 找元素。这个差别很大。坐标是脆的，窗口一动、缩放一变就失效；元素 ID 和 Accessibility 结构更接近真实 UI。

源码里的架构

Peekaboo 的代码分层比较清楚。

根 package 暴露的是几个库：Foundation、Protocols、AutomationKit、Bridge。CLI 是另一个 package，入口是 peekaboo。MCP、Tachikoma agent runtime、Commander 命令行解析都在 CLI 和 Core 这边接起来。

AutomationKit 负责 macOS primitives：截图、AX 读树、输入、菜单、窗口、Dock、Dialog。Bridge 负责本地 socket 协议和权限代理。AgentRuntime/MCP 把同一套 native tools 包装成 agent tools 和 MCP tools。

这个设计有个好处：CLI、MCP、agent 共享同一组工具定义。PeekabooMCPServer 注册 native tools，PeekabooAgentService 也把同一组工具包装给 Tachikoma agent 使用。对维护来说，这能减少接口漂移。

UI 自动化靠 AX 树

很多人会以为这类工具主要靠视觉模型识别按钮。Peekaboo 走的是另一条路线。

ElementDetectionService 的核心是 AXorcist 和 Accessibility Tree。它会解析目标 app/window，收集 AX tree，缓存窗口和进程维度的结果，还会针对 Chromium、Tauri 这类隐藏 Web 内容做 fallback。

所以它生成的 UI map 更像一张结构化控件表，和模型在截图上随便圈几个框差别很大。

动作执行也有策略。默认输入策略里，点击和滚动是 action-first，先尝试 Accessibility action；不支持时才 fallback 到 synthetic input。set-value 和 perform-action 则是 action-only。这说明作者在尽量避免所有动作都退化成鼠标键盘模拟。

这个判断很务实。桌面自动化最怕“看起来点了，实际没点到”。AX action 能表达语义，synthetic input 负责兜底，两者混用才有稳定性。

Bridge 才是关键

macOS 桌面自动化绕不开 TCC 权限。Screen Recording、Accessibility、AppleScript、Event Synthesizing，每一个权限都和实际执行进程绑定。

这对 Agent 很麻烦。Agent 往往是 Node、终端、子进程、MCP server 混在一起。今天是 CLI 在截屏，明天是另一个 subprocess 在点按钮，权限很容易断。

PeekabooBridge 的思路是：让一个签名 GUI app 做权限宿主。CLI 或 agent client 通过本地 Unix socket 发 JSON 请求，真正执行截图和 UI 操作的是那个已经拿到权限的 host。

源码里能看到几个关键设计：

签名校验走 TeamID allowlist；socket 文件权限是 0600；请求有超时；operation 会根据当前权限过滤；不同操作绑定不同权限，比如截图需要 Screen Recording，点击和菜单操作需要 Accessibility，应用启动/退出需要 AppleScript。

和 OpenClaw 的关系

OpenClaw 对 Peekaboo 的接入分两层。

一层是 skill。OpenClaw 仓库里有 skills/peekaboo/SKILL.md，告诉 agent 怎么调用 peekaboo CLI，怎么 see、click、type、操作窗口。

另一层更深：OpenClaw macOS companion app 直接依赖 PeekabooBridge 和 PeekabooAutomationKit。它有一个 PeekabooBridgeHostCoordinator，启用后会在 ~/Library/Application Support/OpenClaw/bridge.sock 开本地 socket，并创建几个 legacy socket symlink 兼容旧路径。

OpenClaw 的 app state 里，Peekaboo Bridge 默认启用。设置页里也有一个 “Enable Peekaboo Bridge” 开关。也就是说，OpenClaw 在 macOS 上会主动把自己变成一个 permission-aware bridge host。

这点很关键。OpenClaw 主链路仍然是 Gateway、node.invoke、system.run、exec approval；UI 自动化单独走 PeekabooBridge。这两个面分开，比把所有能力塞进一条 IPC 里更容易审计。

当前还有兼容债

这条集成已经能看出方向，但也有一些迁移痕迹。

项目现在在 openclaw/Peekaboo，但 npm 包名还是 @steipete/peekaboo，package metadata 里 repository、bugs、homepage 也还有旧地址。OpenClaw 本地 package 依赖里也还能看到 steipete/Peekaboo.git。

还有 socket discovery。文档说 client 会尝试 Peekaboo.app、Claude.app、OpenClaw.app；本地代码里默认 candidates 仍是 Peekaboo、Claude、clawdbot。OpenClaw 用 legacy symlink 把 clawdbot/clawdis/moltbot 指到 OpenClaw socket，解决了兼容问题，但对用户和 Agent 来说还是有点绕。

这类问题不影响核心能力，但会影响可用性。Agent 恢复失败时，最怕文档、路径、命名对不上。

安全边界

Bridge 的能力面很宽。截图、点击、输入、窗口、菜单、Dock、剪贴板、浏览器、AppleScript，都可能通过这条链路接进来。

签名、TeamID、socket 0600、local-only 这些设计是必要的。后面还应该继续拆 capability group。截图是一组权限，输入是一组权限，剪贴板是一组权限，浏览器和 shell 又是另一组风险。不能让“能截图”自然推出“能操作一切”。

对 OpenClaw 这种桌面 Agent 来说，真正需要产品化的是三件事：用户知道当前选中的 bridge host 是谁；用户能看到 agent 调过哪些能力；高风险能力能单独开关和审计。

总结

Peekaboo 的价值不在截图，而在把 macOS GUI 变成 Agent 能稳定调用的动作语义层。

OpenClaw 需要这样的层。只靠 Node subprocess 或脚本去做桌面自动化，会一直撞权限、焦点、签名和窗口状态问题。让签名 GUI app 托管 TCC 权限，再通过 PeekabooBridge 执行 UI 动作，是更接近 macOS 现实约束的方案。

后续最值得补的是把 discovery、metadata、SPM 地址、socket 命名和权限分组统一起来。桌面 Agent 最终拼的是每一次动作能不能被可靠执行、被解释、被撤销。