文档大纲

macOS AI自动化终极工具：Peekaboo3深度解析与实战

快速落地方法：

本文及本站大部分openclaw相关文章，都可以让Openclaw agent阅读，然后进行应用，参考Prompt如下：

请阅读这篇文章：
https://www.aiec.fun/macos-ai%e8%87%aa%e5%8a%a8%e5%8c%96%e7%bb%88%e6%9e%81%e5%b7%a5%e5%85%b7%ef%bc%9apeekaboo3%e6%b7%b1%e5%ba%a6%e8%a7%a3%e6%9e%90%e4%b8%8e%e5%ae%9e%e6%88%98/
分析有哪些内容，对我们优化工作流程有价值。并严格根据openclaw/Darwin-Skill最新官方文档进行核对，排除错误及过时信息，制定落地计划，安装和部署GBrain。

详细方法，参考文章 >>>

一、工具概述

Peekaboo3（简称 Peekaboo）是由 PSPDFKit 前创始人 Peter Steinberger（@steipete）发起开发，现由 OpenClaw 社区维护的macOS 专属 AI 原生 UI 自动化工具。它为 AI 代理提供了 "眼睛和手" 的核心能力，使其能够感知屏幕内容、理解 UI 元素语义并执行完整的图形界面交互，彻底打破了 AI 只能处理文本和代码的局限。

官方仓库：https://github.com/openclaw/Peekaboo

官方网站：https://peekaboo.sh

当前状态：v3 开发中（截至 2026 年 5 月 13 日）

许可证：MIT（完全免费使用、修改和分发）

二、核心作用

Peekaboo 的核心使命是使 macOS GUI 自动化获得与现代 Web 自动化同等的确定性和可调试性。它解决了长期以来 AI 代理在桌面环境中 "看不见、摸不着、无法自主决策" 的根本问题，通过以下六大核心能力全面赋能 AI：

高精度视觉感知：
捕获屏幕、窗口、菜单栏的像素级精确图像，支持 Retina 2x 缩放，完整保留所有视觉细节，为 AI 提供真实的 "视觉输入"
结构化 UI 理解：
生成带唯一元素 ID 的语义化 UI 地图，提取元素的位置、标签、类型、可访问性属性等结构化数据，将像素转化为 AI 可理解的信息
多模态智能交互：
执行点击、输入、滚动、拖拽、快捷键等人类级别的 GUI 操作，支持语义化元素定位而非脆弱的坐标依赖
自然语言任务编排：
内置原生代理引擎，可直接理解自然语言描述的复杂任务，自动规划执行步骤并处理异常情况
系统级深度控制：
提供对应用、窗口、空间、菜单、Dock、系统对话框的全面管理能力，覆盖 macOS 桌面的所有交互场景
多工具生态集成：
作为标准 MCP 服务器和 OpenClaw 官方技能，可被 Claude Desktop、Cursor、OpenClaw 等主流 AI 工具无缝调用

三、主要特点

1. 像素级精确捕获

支持全屏、特定应用窗口、菜单栏区域的独立截图
可选 Retina 2x 高分辨率模式，保留清晰的文字和图标细节
提供 CoreGraphics（经典）和 ScreenCaptureKit（现代）双捕获引擎
非侵入式后台捕获，无需切换应用焦点，不干扰用户当前工作

2. 语义化 UI 交互

优先使用 macOS 原生 Accessibility API 进行元素定位，比坐标定位稳定 10 倍以上
支持通过元素 ID、精确标签、模糊文本查询等多种方式定位目标元素
内置智能等待机制，自动等待元素加载完成并变为可交互状态
标准化 "see-then-interact" 工作流：先捕获分析生成快照，再基于快照执行操作

3. 多 AI 提供商原生集成

云端模型：GPT-5.1 family、Claude 4.x、Grok 4-fast (vision)、Gemini 2.5
本地模型：Ollama（llama3.3、llava 等所有支持工具调用的模型）
可通过环境变量PEEKABOO_AI_PROVIDERS或peekaboo config add命令灵活配置和切换模型
支持同时配置多个提供商，实现自动故障转移和负载均衡

4. 全面的系统控制能力

应用管理：
启动、退出、重启、切换、列出所有运行中的应用
窗口管理：
移动、调整大小、聚焦、关闭、最小化、最大化，原生支持多显示器操作
空间管理：
列出、切换 macOS Spaces，将窗口移动到不同的虚拟桌面
菜单交互：
无需实际点击即可发现并列出应用菜单和菜单栏项，输出结构化 JSON 数据
Dock 交互：
启动应用、右键点击、隐藏 / 显示 Dock 项
系统对话框：
自动处理打开 / 保存文件、确认、输入等标准系统对话框

5. 多接口无缝支持

原生 CLI：所有功能都可通过命令行访问，支持 JSON 格式输出，便于脚本和程序集成
MCP 服务器：完全兼容 Model Context Protocol 标准，可被 Claude Desktop、Cursor、Codex 等 AI 工具自动发现
OpenClaw 技能：作为 OpenClaw 生态系统的核心技能，可被 AI 代理直接调用执行桌面任务

6. 开发者友好特性

智能快照缓存机制，避免重复捕获相同屏幕内容，提升执行效率
可配置的测试工作流，支持可重现的自动化会话
严格的类型系统，大幅减少运行时错误
详细的日志和调试信息，包括带元素标注的截图
支持.peekaboo.json脚本文件，可批量执行预定义的自动化任务
原生支持 zsh、bash、fish 三种 Shell 的自动补全

四、核心优势

AI 原生设计理念：
从项目立项之初就为 AI 代理构建，而非传统人类自动化工具的 AI 改造。内置完整的自然语言代理引擎，可直接理解并执行复杂任务描述
深度 macOS 系统集成：
完全基于 Apple 官方 API（ScreenCaptureKit、Accessibility、CoreGraphics）构建，比第三方跨平台工具更稳定、更高效、兼容性更好
非侵入式操作模式：
菜单发现、窗口列表、应用状态查询等功能无需实际点击或切换焦点，在后台静默执行，完全不干扰用户的正常工作
混合自动化模型：
结合了语义化的 Accessibility API 和视觉识别技术，在应用不支持 Accessibility 时自动回退到视觉定位，实现 99% 以上的应用覆盖
统一的技术栈架构：
CLI、macOS 应用、代理运行时、MCP 服务器全部基于相同的 Swift 核心服务构建，确保所有接口的行为一致性
极致隐私保护：
完整支持本地 AI 模型（Ollama），所有屏幕数据捕获、分析和决策都在本地完成，无需上传到任何云端服务器

五、安装部署方法

系统要求

操作系统：macOS 15.0+，仅支持 macOS 平台
硬件：Apple Silicon（ARM64）强烈推荐，Intel Mac 兼容性有限
权限：必须授予 "屏幕录制" 权限，推荐授予 "辅助功能" 权限，可选 "事件合成" 权限

方法一：Homebrew 安装（推荐）

这是安装完整 Peekaboo（包括 CLI 和 macOS 应用）的官方推荐方式。注意：Homebrew tap 仍由原作者维护：

brew install steipete/tap/peekaboo

安装完成后，首次运行时会提示授予必要的系统权限：

# 检查当前权限状态
peekaboo permissions status

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

方法二：MCP 服务器安装（Node.js）

如果只需要 MCP 服务器功能（用于 Claude Desktop、Cursor 等 AI 工具），可以使用 npx 直接运行，无需全局安装：

# 直接启动Peekaboo MCP服务器
npx -y @steipete/peekaboo

MCP 客户端配置示例：

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

注：以上模型名称为示例，请根据实际可用模型进行替换。

方法三：OpenClaw 技能安装

在 OpenClaw 中安装 Peekaboo 技能的官方正确步骤：

# 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/

方法四：从源码构建

# 克隆官方仓库
git clone https://github.com/openclaw/Peekaboo.git
cd Peekaboo

# 安装构建依赖（仅用于辅助脚本，核心代码为Swift）
pnpm install

# 构建CLI工具
pnpm run build:cli

# 运行安全测试套件
pnpm run test:safe

开发环境要求：Xcode 16.4+，Swift 6.2+

六、基本使用示例

1. 屏幕捕获与分析

# 捕获全屏并保存到桌面（Retina分辨率）
peekaboo image --mode screen --retina --path ~/Desktop/screen.png

# 捕获Safari浏览器中标题包含"GitHub"的窗口
peekaboo image --app Safari --window-title "GitHub" --path ~/Desktop/safari.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"

# 直接设置文本字段的值（通过Accessibility API）
peekaboo set-value --on T1 --value "Hello Peekaboo" --snapshot "$SNAPSHOT"

# 调用元素的命名可访问性操作
peekaboo perform-action --on B1 --action AXPress --snapshot "$SNAPSHOT"

# 在TextEdit中输入文本
peekaboo type --text "Hello from AI automation" --app TextEdit

# 执行保存快捷键
peekaboo hotkey --keys "cmd,s" --app TextEdit

3. 自然语言自动化

# 直接用自然语言描述任务，由AI自动编排执行
peekaboo agent "打开Notes应用，创建一个新笔记，标题为'TODO列表'，内容包含三个项目：买牛奶、取快递、写报告"

4. 应用和窗口管理

# 启动Safari浏览器并打开GitHub网站
peekaboo app launch --name "Safari" --open https://github.com

# 列出所有打开的窗口（JSON格式）
peekaboo list windows --json

# 调整Safari窗口的位置和大小
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800

七、OpenClaw 集成注意事项

由于 macOS 严格的 TCC（透明度、同意和控制）安全机制，Peekaboo 在从 OpenClaw 的守护进程 / 网关进程调用时可能会遇到权限问题。官方推荐的解决方案是在交互式终端中运行 Peekaboo 命令，然后将结果复制粘贴到 OpenClaw 中，这样可以避免绝大多数权限问题，获得最佳的使用体验。

八、类似工具对比

对比维度	Peekaboo3	AppleScript	PyAutoGUI	K. Maestro	Shortcuts
平台支持	macOS 26.1+	macOS 仅	Win/mac/Linux	macOS 仅	Apple 全平台
AI 集成	原生内置多提供商	无（需自行）	无（需自行）	有限（插件）	有限（AI）
视觉能力	强（VQA+地图）	无	弱（图像匹配）	弱（图像匹配）	无
元素定位	AX + 视觉	AX 仅	坐标 + 图像	坐标 + 图像	AX 仅
自然语言	原生 Agent 命令	无	无	无	有限（Siri）
API 接口	CLI+MCP+Claw	脚本语言	Python API	GUI+Script	GUI+URL
开源性	完全开源 (MIT)	闭源 (Apple)	开源 (BSD)	闭源商业	闭源 (Apple)
价格	免费	免费 (内置)	免费	$36	免费 (内置)
适用场景	AI代理、动态任务	静态脚本集成	跨平台测试	个人生产力宏	简单跨设备

关键差异分析

与 AppleScript/JXA 对比：
AppleScript 是 macOS 内置的传统脚本语言，高度依赖应用提供的脚本字典支持。Peekaboo 不依赖任何应用的脚本支持，可自动化几乎所有 macOS 应用，并且提供了 AppleScript 完全没有的视觉分析能力。
与 PyAutoGUI 对比：
PyAutoGUI 是跨平台的 Python 库，主要基于脆弱的坐标和图像匹配。Peekaboo 使用原生 macOS API，性能更好、更稳定，并且支持语义化元素定位，对 UI 变化的鲁棒性大幅提升。
与 Keyboard Maestro 对比：
Keyboard Maestro 是成熟的商业宏工具，适合个人创建预定义的生产力工作流。Peekaboo 是专为 AI 代理设计的，支持动态决策和自然语言任务描述，能够处理不可预测的复杂场景。
与 Apple Shortcuts 对比：
Shortcuts 是 Apple 官方的可视化自动化工具，优势在于跨设备同步和简单的预定义工作流。Peekaboo 提供了更强大的 UI 控制和视觉分析能力，适合需要 AI 理解和动态响应的复杂任务。

九、总结

Peekaboo3 是目前macOS 平台上最先进的 AI 原生 UI 自动化工具。它填补了传统自动化工具与现代 AI 代理之间的巨大鸿沟，使 AI 从只能处理文本和代码的 "书呆子"，变成了能够真正 "看到" 并 "操作" 整个 macOS 桌面环境的智能助手。

与其他工具相比，Peekaboo 的最大优势在于其AI 原生设计理念和深度 macOS 系统集成。它不仅提供了全面的 GUI 控制能力，还内置了多 AI 提供商支持和自然语言理解，使 AI 代理能够自主完成复杂的桌面任务。

对于 OpenClaw 用户来说，Peekaboo 是不可或缺的核心技能。它极大地扩展了 AI 代理的能力边界，开启了 AI 桌面自动化的全新时代。随着 AI 技术的不断发展，Peekaboo 有望成为连接 AI 与桌面世界的标准接口。

阅读量： 652