Peekaboo：让 macOS 上的 AI 代理真正看见屏幕并操作界面
Peekaboo 是一款 macOS CLI 和可选的 MCP 服务器，使 AI 代理能够捕获应用程序或整个系统的屏幕截图，并通过本地或远程 AI 模型提供可选的视觉问答。
秒懂
- 它是什么？
- Peekaboo 是一个面向 macOS 的 CLI 与 MCP 服务器，提供屏幕捕获、可访问性检查和原生 UI 自动化能力。它通过结构化元素 ID 和背景输入，让 AI 代理在不抢占前台的情况下完成多步操作。
- 适合谁用？
- Peekaboo 适合那些需要在 macOS 上执行精确 UI 自动化的开发者，尤其是使用 Codex、Claude Code 或 Cursor 等 MCP 客户端的场景。它不适合需要跨平台支持或对非模态窗口有复杂交互需求的用户。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Swift（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题
AI 代理要操作桌面应用，通常只能靠猜测坐标或模拟键盘事件。Peekaboo 换了一种思路：先截屏，再通过 Accessibility API 生成带不透明元素 ID 的结构化 UI 地图，最后让代理基于这些 ID 执行点击、输入和按键。这个循环解决了两个具体问题：一是代理不知道屏幕上有什么，二是代理无法稳定地指向某个按钮。Peekaboo 把观察和操作都变成命令行工具，任何能调用 CLI 的程序都能接入。它主要面向 macOS 上的开发者，特别是那些在用 Codex、Claude Code 或 Cursor 这类 MCP 客户端的人。
核心机制：从像素到元素 ID
Peekaboo 的观察命令是 `peekaboo see`。不带参数时，它返回当前屏幕的截图和元素列表。加 `--app Finder` 可以只检查某个应用，加 `--json` 则输出结构化数据。关键设计是元素 ID 不透明，代理不需要理解坐标，只需要记住 ID。操作命令如 `click` 和 `type` 接受元素名称或 ID，并支持 `--window-id` 参数来锁定特定窗口。这种设计避免了多窗口环境下误操作的问题。README 强调，窗口选择器可以保持背景操作，但 App/PID 级别的操作需要明确的前台同意。这意味着 Peekaboo 在安全性和便利性之间做了取舍：精确的目标可以后台执行，模糊的目标必须经过用户确认。
安装与配置：三条路径
安装方式有三种。Homebrew 用户执行 `brew install steipete/tap/peekaboo`，npm 用户运行 `npx -y @steipete/peekaboo --version`（需要 Node.js 22），或者从 GitHub Releases 下载签名 DMG 安装菜单栏应用。CLI 和菜单栏应用可以分开安装。配置存储在 `~/.peekaboo` 目录下，用 `peekaboo config` 查看和修改。权限是使用前提：屏幕捕获需要 Screen Recording 权限，UI 检查和操作需要 Accessibility 权限，合成输入还需要额外权限。文档中专门有 permissions 指南，说明这不是一个可跳过的步骤。
自动化示例：锁定窗口的交互
README 给出了一个具体流程：先列出 Safari 的窗口，复制 `window_id`，然后所有操作都绑定这个 ID。例如 `peekaboo click "Address and search bar" --app Safari --window-id 12345`，接着 `peekaboo type "github.com/openclaw/Peekaboo" --app Safari --window-id 12345`，最后 `peekaboo press Return --app Safari --window-id 12345`。这里的关键是背景输入：只要 Peekaboo 能解析到进程，应用就不需要成为前台。这比传统的 AppleScript 更灵活，也比基于坐标的自动化更可靠。但要注意，原始 CLI 的 `press` 命令只有在指定精确窗口选择器时才能后台运行，否则也需要前台同意。
Agent 与 MCP 集成
Peekaboo 自带一个 agent 子命令，可以接受自然语言指令，比如 `peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground`。这个 agent 需要配置模型提供商，文档中有专门的 agent setup 指南。同时，通过 `mcp` 命令可以把 Peekaboo 的工具暴露给 MCP 客户端，这样 Codex 或 Claude Code 就能直接调用屏幕捕获和 UI 操作。版本 4.2.3 的更新说明提到，Agent 和 MCP 工具只暴露策略安全的操作，背景自动化需要精确的快照。这意味着如果你通过 MCP 使用，某些模糊操作会被拒绝，这是设计上的安全边界。
限制与失败模式
Peekaboo 明确要求 macOS 15 或更高版本，这排除了大量仍在运行的旧系统。权限配置是最大的摩擦点：Screen Recording 和 Accessibility 权限缺失时，命令会静默失败或返回不完整结果。README 提到窗口清单会解释可用的捕获方式，但这也暗示了不同窗口类型可能有不同的兼容性。另一个限制是，背景自动化只支持经过验证的非模态 SwiftUI 窗口，对于非模态的复杂窗口，可能需要回退到截图恢复或刷新证据。如果你需要操作模态对话框或非标准 UI 元素，Peekaboo 的能力边界并不清晰，文档中只提到“更清晰的对话框恢复”，但没有具体说明。
替代方案与对比
最直接的替代是 AppleScript 和 System Events，它们也能操作 UI，但缺乏视觉反馈，且脚本编写繁琐。Peekaboo 的优势在于把观察和操作统一到同一个 CLI 循环中，并且通过元素 ID 而非坐标来定位。另一个方向是计算机视觉方案，比如基于截图和 OCR 的自动化工具，但这类工具通常不能原生触发 macOS 的 Accessibility API，操作精度和速度都受限。Peekaboo 还提供了 PeekabooWin 和 PeekabooX 两个社区移植版本，分别面向 Windows 和 Linux，这说明它的设计理念可以跨平台，但原版只支持 macOS。如果你需要跨平台，应该直接考虑那些移植版本，而不是期待 Peekaboo 本身支持。
维护与许可
项目使用 MIT 许可证，允许自由使用和修改。最近更新频繁，v4.2.2 在 2026 年 8 月 20 日发布，说明维护活跃。但活跃维护也意味着 API 可能变动，升级时需要关注 release notes。配置存储在 `~/.peekaboo`，升级 CLI 时原有配置通常可以保留，但如果你使用自定义提供商，需要检查 provider 配置是否兼容。构建源码需要 Swift 6.2 和 Node.js 22，开发环境门槛较高，但普通用户通过 Homebrew 或 npm 安装则无需关心这些。总体来看，维护成本集中在权限管理和版本跟进上，没有发现需要额外付费的服务。
编辑结论
Peekaboo 适合那些需要在 macOS 上执行精确 UI 自动化的开发者，尤其是使用 Codex、Claude Code 或 Cursor 等 MCP 客户端的场景。它不适合需要跨平台支持或对非模态窗口有复杂交互需求的用户。在采用前，先验证你的 macOS 版本是否达到 15，确认 Screen Recording 与 Accessibility 权限配置无误，并在非关键环境中测试背景输入对目标应用的兼容性。最终判断：如果你能接受 macOS 15 的硬性门槛和权限管理成本，Peekaboo 是目前将视觉观察与原生操作结合得最直接的 CLI 工具之一。
社区笔记