Peekaboo 🫣 — macOS 桌面自动化工具包（AI Agent 版）

> 一句话版本：一个 macOS 工具，你用 brew 装上后，可以用自然语言说"打开 Safari 搜 Peekaboo"，它能看屏幕、识别按钮、点鼠标、打字，全自动完成。AI 编程工具（Codex、Claude Code、Cursor）也能通过 MCP 协议直接控制你的 Mac 桌面。

来源: https://peekaboo.sh/

GitHub: https://github.com/openclaw/Peekaboo

作者: Peter Steinberger（@steipete，PSPDFKit 创始人）

版本: v3.x（3.4k+ ⭐）

日期: 2026-05-13

评分: ⭐⭐⭐⭐½ (4.5/5)

这是什么？

Peekaboo 是一个macOS 桌面自动化工具包——但它不是传统的脚本自动化（AppleScript/Automator），而是专门为AI Agent 时代设计的：

它能看屏幕（像素级截图 + 无障碍树）、能理解界面（识别按钮/输入框/菜单）、能操作界面（点/打字/滚动/快捷键/菜单/对话框），并且自带一个 AI Agent 运行时，让你用自然语言就能指挥它干任何事。

更关键的是，它提供一个 MCP 服务器，让 Codex、Claude Code、Cursor 这些 AI 编程工具可以直接控制你的 Mac 桌面——你的编程助手不仅能写代码，还能帮你操作 Xcode、浏览器、终端。

安装

# Homebrew（推荐）
brew install steipete/tap/peekaboo

# MCP 服务器（Node 22+，纯 npm）
npx -y @steipete/peekaboo

两个权限：Screen Recording（必须）+ Accessibility（推荐）。

五大能力

① 看屏幕 (Capture & Vision)

• 像素级截图：全屏、窗口、菜单栏
• 无障碍树读取：返回结构化 JSON，稳定元素 ID 可复用
• 智能标注：截图 + 元素边框可视化，一眼看清 AI 识别了什么

② 自动化操作 (Automation)

所有 GUI 操作都支持，且支持坐标模式和元素 ID 模式：

• click — 点按钮、链接、坐标
• type — 打字（有人类输入模拟模式）
• scroll / drag / hotkey
• menu — 菜单栏发现+导航（结构化 JSON）
• dialog — 弹窗处理
• window — 窗口管理（层级/焦点/位置）
• space — Mission Control 空间切换
• app — 应用启动/切换/退出

③ 自然语言 Agent (Agent Runtime)

peekaboo agent "打开 Safari，访问 github.com，搜索 Peekaboo"

Agent 会自动：截图 → 分析 UI → 规划步骤 → 执行操作 → 检查结果 → 继续/停止。

高级 Agent 模式：

• 明确任务完成：Agent 必须显式调用 task_completed 工具声明任务完成，避免"我还在解释计划但 Agent 以为完了"的问题
• 工具审批机制：可以配置哪些工具需要人工审批（比如 shell 命令）、哪些自动放行（截图）、哪些永远拒绝
• 生命周期钩子：完整的钩子系统（开始/结束/工具调用/迭代/错误），支持日志、监控、审计

④ MCP 服务器

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo"],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.5,anthropic/claude-opus-4-7"
      }
    }
  }
}

只需几行配置，你的 AI 编程助手就能直接控制你的 Mac。

⑤ 视觉反馈系统 (Visualizer)

操作过程中会在屏幕上显示一个叠加层，实时展示 AI 正在做什么（当前聚焦的元素、操作类型、状态），让你能看着 AI 干活，知道它思路对不对。

技术架构

Tachikoma (AI 模型管理)
  GPT-5.x / Claude 4.x / Grok 4 / Gemini 2.5 / Ollama
       │
PeekabooAutomation (自动化引擎)
  截图 / 无障碍树 / 菜单服务 / 窗口管理 / 输入模拟
       │
PeekabooAgentRuntime (Agent + MCP 运行时)
  ToolRegistry / Agent 服务 / MCP 上下文
       │
PeekabooCore (统一入口)
  CLI / macOS App / MCP Server

架构特点：

• 从旧式 Singleton 模式迁移到依赖注入架构
• PeekabooServices 服务定位器，可替换具体实现便于测试
• 所有 UI 操作绑定 @MainActor（macOS 要求）
• AI provider 完全抽象，支持本地（Ollama）和远程（OpenAI/Anthropic/Grok/Gemini）

AI 模型支持

与 OpenClaw 的关系

Peekaboo 与 OpenClaw 同属一个组织，项目中已有专门的 Agent Skill 文件（skills/peekaboo/），说明 OpenClaw 已经内置了对 Peekaboo 的原生支持。

这意味着：OpenClaw Agent 可以直接通过 MCP 控制整个 macOS 桌面。比如 Researcher Agent 可以操作浏览器、前端 Agent 可以操作 Xcode/VS Code、自动化 Agent 可以处理任何 GUI 应用。

对比竞品

Peekaboo 的独特位置是：macOS 原生 AI Agent 的"手和眼"。它不是要替代 Playwright（Web 场景 Playwright 更强），而是在 macOS 桌面这个 Playwright 够不到的领域，给了 AI Agent 完整的能力。

评价

这就是 macOS AI Agent 一直缺的那层基础设施。

过去想让 AI 操作 Mac 桌面，你需要要么用 AppleScript（太古老），要么用 SikuliX（图像匹配太脆弱），要么用计算机视觉自己造（太复杂）。Peekaboo 把这个能力做成了一个 brew install 的命令行工具，并且通过 MCP 让所有 AI 编程工具都能用。

几个特别值得关注的工程决策：

1. Unified Tool Surface：同一个工具集同时暴露给 CLI、Agent Runtime、MCP Server——"一次实现，到处可用"

2. Agent 设计成熟：显式 task_completed、工具审批、生命周期钩子——这些不是学术玩具，是生产级 Agent 框架才有的设计

3. 依赖注入架构：从 Singleton 迁移到 DI，说明代码质量追求很高

4. 人类输入模拟：有人类打字/鼠标移动模式，避免被一些 app 识别为自动化

与我们的关联

⚠️ 直接相关 — 我们是 OpenClaw 用户，Peekaboo 是 OpenClaw 生态系统的一部分：

• MCP 集成：OpenClaw Agent 可以通过 Peekaboo MCP 控制 macOS 桌面
• 测试自动化：可以用 Peekaboo 做 macOS 端到端测试
• Browser 操作的补充：对于需要混合桌面应用 + Web 的自动化流程，Peekaboo + Playwright 是完美组合
• 潜在的 Xcode 自动化：对于 iOS/macOS 开发者，Peekaboo 可以自动化 Xcode 操作

评分