Peekaboo v3 完全指南:让 AI Agent 真正「看得见、动得了」

AI Agent 能聊天、能写代码、能分析问题，但它能帮你点击屏幕上的按钮吗？能自动填写表单吗？能操作你 Mac 上的任何应用吗？Peekaboo v3 给出了答案。

引言：AI Agent 的「手眼协调」难题

2026 年，AI Agent 已经能处理邮件、写代码、分析数据，但它们仍然被困在一个尴尬的境地：能思考，不能行动。

想让 AI 帮你点击屏幕上的"保存"按钮？抱歉，它看不到。想让 AI 自动填写表单？对不起，它摸不着。AI Agent 就像一个被困在文字世界里的聪明大脑，无法直接操作真实的桌面环境。

Peekaboo v3 的出现，彻底改变了这一局面。

一、Peekaboo 是什么？

Peekaboo 是一款专为 macOS 打造的 AI 原生 UI 自动化工具，由 PSPDFKit 前创始人 Peter Steinberger 发起，现由 OpenClaw 社区维护。

官方定位一句话：

"macOS automation toolkit for humans and agents"
（面向人类和 AI Agent 的 macOS 自动化工具包）

核心定位

Peekaboo 是 AI Agent 的「眼睛」和「手」：

• • 👁️ 眼睛：捕获屏幕像素、读取 Accessibility 树、理解界面结构
• • 🖐️ 手：模拟点击、输入、滚动、拖拽、快捷键等真实用户操作

项目基本信息

二、四大核心功能

Peekaboo v3 提供了完整的能力矩阵，覆盖从视觉感知到自动执行的全部环节。

1. Capture & Vision（捕获与视觉）

• • 📸 像素级屏幕 / 窗口 / 菜单栏截图
• • 🔍 可选 Retina 2x 缩放，保留所有视觉细节
• • 🗺️ 带注释的 Accessibility 地图（唯一元素 ID）

2. Automation（自动化操作）

• • 🖱️ 点击（click）、输入（type）、滚动（scroll）
• • 🤏 拖拽（drag）、手势滑动（swipe）
• • ⌨️ 热键组合（hotkey）
• • 🪟 菜单、对话框、窗口、Spaces 操作

3. Agent（自然语言 Agent）

• • 💬 自然语言 plan/act 循环
• • 🔄 支持多 Provider 切换
• • 💾 可恢复的会话（resumable sessions）
• • 👁️ 可视化反馈（visualizer feedback）

4. MCP（Model Context Protocol 服务器）

• • 🔌 把所有 Peekaboo 工具通过 stdio 暴露给 AI 客户端
• • 🤖 原生支持 Codex、Claude Code、Cursor

三、30+ CLI 命令速查

Peekaboo 提供了 30+ 个 CLI 命令，覆盖所有自动化场景。

视觉与识别

输入操作

窗口与应用管理

四、安装方法（三种方式）

方法一：Homebrew 安装（推荐）

# 安装 CLI + Mac App
brew install steipete/tap/peekaboo

# 检查权限状态
peekaboo permissions status

# 自动打开系统设置授予权限
peekaboo permissions grant

方法二：作为 MCP 服务器使用

# 使用 npx 启动 MCP 服务器（无需全局安装）
npx -y @steipete/peekaboo

# 或者在 Peekaboo 安装后使用 mcp 子命令
peekaboo mcp serve

方法三：OpenClaw 技能安装

# 1. 先通过 Homebrew 安装 Peekaboo CLI 核心
brew install steipete/tap/peekaboo

# 2. 授予必要的系统权限
peekaboo permissions grant

# 3. 克隆官方仓库并复制技能文件
git clone https://github.com/openclaw/Peekaboo.git
cp -r Peekaboo/skills/peekaboo ~/.openclaw/skills/

五、快速上手：5 分钟入门

步骤 1：安装

brew install steipete/tap/peekaboo

步骤 2：授予权限

在 系统设置 > 隐私与安全性 中开启：

• • ✅ Screen Recording（屏幕录制）—— 用于屏幕截图
• • ✅ Accessibility（辅助功能）—— 用于模拟用户输入操作

快速授权命令：

peekaboo permissions grant

步骤 3：运行第一个 Agent 任务

peekaboo agent "open Safari and search for Peekaboo"

Peekaboo 会自动：

1. 1. 打开 Safari 浏览器
2. 2. 在搜索栏输入 "Peekaboo"
3. 3. 按回车执行搜索
4. 4. 返回执行结果

六、实战使用示例

示例 1：全屏截图并 AI 分析

# Retina 截图保存到桌面
peekaboo image --mode screen --retina --path ~/Desktop/screen.png

# 截图并让 AI 分析总结
peekaboo image --mode screen --analyze "总结这个页面的主要内容"

示例 2：语义化 UI 自动化

# 捕获 Safari 窗口并生成带元素 ID 的 UI 快照
peekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT

# 通过标签文本点击按钮
peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"

# 直接设置文本字段的值
peekaboo set-value --on T1 --value "Hello Peekaboo" --snapshot "$SNAPSHOT"

示例 3：自然语言多步自动化

# 打开 Notes 并创建 TODO 列表
peekaboo agent "Open Notes and create a TODO list with three items: 买牛奶、取快递、写报告"

示例 4：执行自动化脚本

# 执行 .peekaboo.json 脚本（适合重复性任务）
peekaboo run .peekaboo.json --output result.json

七、配置 AI 模型（多 Provider 支持）

Peekaboo 不绑定单一模型厂商，支持多 Provider 切换和自动 fallback。

支持的 AI 模型

配置方式

方式一：环境变量

export PEEKABOO_AI_PROVIDERS="openai/gpt-5.5,anthropic/claude-opus-4-7"

方式二：config 子命令

peekaboo config add

多模型 fallback 机制：逗号分隔多个模型，Peekaboo Agent 运行时按 fallback 顺序尝试，第一个模型失败会自动切换到下一个。

八、MCP 服务器：接入 AI 客户端

Peekaboo 可以作为标准 MCP 服务器运行，让 Claude Code、Cursor、Codex 等 AI 客户端获得 macOS 屏幕操作和自动化能力。

MCP 客户端配置示例

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

配置完成后，你的 AI 客户端就能：

• • 📸 捕获屏幕截图
• • 🖱️ 点击界面元素
• • ⌨️ 输入文字
• • 🔍 理解当前屏幕内容

九、与 OpenClaw 的关系

定位差异

集成价值

集成前：

• • OpenClaw 能从 Telegram/Slack/iMessage 等入口接收任务
• • 但无法操作本地应用、网页、模拟器等真实桌面环境
• • Agent 想出步骤后仍需把待办清单递回给人

集成后：

• • OpenClaw 从"多渠道消息网关 + Agent 调度台"升级为"能在本机环境真正办事的系统"
• • 完整执行链路：OpenClaw 收到聊天指令 → 拆出需要桌面操作的步骤 → 通过 Peekaboo MCP 调用执行 → Peekaboo Agent 完成 see/click 循环 → 结果回传 OpenClaw → OpenClaw 回复用户

十、典型使用场景

场景 1：远程 iOS 模拟器测试

识别欢迎页 → 点击主按钮 → 等待界面变化 → 截图继续探索
（适合自动化 UI 测试）

场景 2：重复性 UI 测试

把多步 UI 交互写成 .peekaboo.json 脚本，用 peekaboo run 批量执行

场景 3：AI 编程 IDE 集成

挂到 Claude Code/Cursor/Codex 的 MCP 配置里，让 AI 编程助手能看屏幕状态、帮助调试真实应用

场景 4：跨应用工作流

从 Notes 到 Calendar 到 Mail 的跨应用多步任务，一条命令搞定

场景 5：浏览器自动化替代方案

相比 Playwright/Puppeteer 的"只能操作浏览器"，Peekaboo 能操作系统上任何应用

十一、与同类工具对比

Peekaboo 核心优势：

1. 1. macOS 原生体验：Swift 6.2 + AXorcist（自研 AX 封装），对 macOS Accessibility 树的处理深度比跨平台工具好
2. 2. AI Agent 一等公民：自带 plan/act 循环、resumable sessions、可视化反馈
3. 3. MCP 第一公民：同一套工具既能用 CLI 跑、也能通过 MCP 给 AI 客户端调用
4. 4. 多模型 Provider：不绑定单一厂商

十二、常见问题 FAQ

Q：Peekaboo 支持 Windows/Linux 吗？

A：官方版本仅支持 macOS 15+。社区项目 PeekabooWin（@FelixKruger 维护）提供 Windows 版，但不是官方维护。Linux 暂无对应版本。

Q：Peekaboo 和 Claude Computer Use 是什么关系？

A：两者定位相似但实现路径不同。Claude Computer Use 仅支持 Claude 模型；Peekaboo 是独立的 macOS 自动化工具包，多 Provider 兼容，能作为 MCP 服务器给任意 AI 客户端调用。

Q：Peekaboo 能处理网页内容吗？

A：可以。Safari/Chrome/Firefox 等浏览器在 macOS 上也走 AX 树，Peekaboo 的 see/click/type 对浏览器窗口同样有效。但如果是纯浏览器自动化任务，Playwright/Puppeteer 在 DOM 操作上更细致。

Q：使用 Peekaboo 需要付费吗？

A：不需要。Peekaboo 基于 MIT 许可证开源，完全免费使用、修改和分发。

总结：AI Agent 的「手眼协调」时代已经到来

Peekaboo v3 在 2026 年 5 月补齐了 OpenClaw 缺失的「本地桌面执行层」，让 AI Agent 从"能聊天"进化到"能看屏幕、点按钮、操作真实应用"。

核心价值三点：

1. 1. AI 原生设计：从立项之初就为 AI Agent 构建，内置完整的自然语言代理引擎
2. 2. 深度 macOS 集成：完全基于 Apple 官方 API 构建，Accessibility 树处理深度领先跨平台工具
3. 3. 多模型不绑定：OpenAI、Anthropic、xAI、Google、本地 Ollama 全部支持

对于 macOS 用户和 OpenClaw 用户来说，Peekaboo 是不可或缺的效率倍增器。

官网：https://peekaboo.sh\ GitHub：https://github.com/openclaw/Peekaboo\ OpenClaw：https://openclaw.sh

本喵抓虾，爪拿把掐 🐾