Peekaboo：macOS 屏幕感知自动化 CLI

项目简介

Peekaboo 是一个面向 macOS 的命令行工具和菜单栏应用，用于屏幕截图、辅助功能（Accessibility）检查和原生 UI 自动化。你可以直接使用它，也可以让内置 Agent 规划多步任务，或把同一套工具通过 MCP 暴露给其他客户端。

发布的 CLI 和 app 需要 macOS 15 或更高版本。

主要功能

• 屏幕捕获：截取指定应用或整个系统的画面。
• 界面检查：获取运行中应用的结构化 UI 地图，返回不透明元素 ID。
• UI 交互：支持 click、type、press、scroll、drag、set-value、action 等操作。
• macOS 控制：通过 app、window、menu、menubar、dock、dialog、space 等命令控制系统界面。
• Agent 工作流：用自然语言驱动多步自动化，例如打开 Safari 并搜索内容。
• MCP 集成：通过 mcp 命令把工具集暴露给 Codex、Claude Code、Cursor 等 MCP 客户端。
• 配置管理：提供商凭据和设置存放在 ~/.peekaboo，可用 peekaboo config 查看或修改。

安装与使用

使用 Homebrew 安装 CLI

brew install openclaw/tap/peekaboo

使用 npm 运行 MCP 包

npm 包需要 Node.js 22 或更高版本，包含 CLI 和 MCP 启动器。

npx -y @steipete/peekaboo --version

安装 Mac 应用

从 最新 GitHub Release 下载签名的 DMG。菜单栏应用提供权限引导、视觉反馈和 Agent 会话；如果还需要在 PATH 中使用 peekaboo，请单独安装 CLI。

快速开始

检查权限状态，然后截图：

peekaboo permissions status
peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png

检查运行中的应用，获取带元素 ID 的 UI 地图：

peekaboo see --app Finder --json

自动化示例

列出 Safari 的窗口，复制目标 window_id，再把后续操作固定到该窗口：

peekaboo window list --app Safari --json
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

使用 Agent

peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground

Agent 运行前需要配置模型提供商。

注意事项

• 屏幕捕获需要「屏幕录制」权限；辅助功能权限用于 UI 检查和控件操作，合成输入还需要额外权限。
• 后台输入需要可解析的进程或精确窗口选择器；仅指定应用/PID 或没有目标的组合键需要显式前台授权。
• Agent 和 MCP 的后台策略要求使用新的精确非对话框快照。
• 源码构建需要 macOS 15 或更高版本、Swift 6.2 或更高版本、Node.js 22 或更高版本，以及仓库子模块。
• 项目采用 MIT 许可证。

---

本作品整理自 GitHub 开源项目 openclaw/Peekaboo，原作者 @openclaw，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。