Peekaboo：面向 macOS 的开源 AI 截图与自动化工具

一、Peekaboo 是什么？

Peekaboo 是一款基于 macOS 系统的开源自动化工具，融合 CLI（命令行界面）与 MCP 服务器双重运行模式，依托多厂商 AI 模型实现高精度屏幕捕获、自然语言驱动的 GUI 自动化及可视化交互。工具支持窗口、屏幕、菜单栏等多场景像素级截图，兼容 OpenAI、Anthropic、Google 等主流 AI 提供商及 Ollama 本地模型，可通过命令行或自然语言完成点击、输入、窗口管理、应用控制等全流程自动化操作。

作为一款兼具灵活性与实用性的开源工具，Peekaboo 提供两种核心运行模式：一是轻量化 CLI 命令行模式，支持通过终端输入指令快速完成截图、点击、输入等单一或组合操作；二是 MCP（Model Control Protocol）服务器模式，可与 Claude Desktop、Cursor 等 AI 开发工具深度集成，让 AI 智能体直接调用系统资源完成复杂自动化任务。

工具目前处于 3.0.0-beta4 版本，相比早期版本新增了原生 AI 智能体工作流、多屏幕跨空间自动化等核心功能，同时优化了截图精度与 AI 模型兼容性，支持 macOS 15.0+（Sequoia）系统，基于 Swift 6.2 开发，Node 22.0+ 仅用于 MCP 服务器及辅助脚本运行，核心功能无需额外依赖，以 MIT 协议开源，允许个人与商业场景自由使用、修改与二次开发。

值得注意的是，Peekaboo 并非简单的截图工具或脚本执行器，而是一套完整的 macOS 自动化生态：它既支持开发者通过命令行编写精准的自动化脚本，也允许非技术用户通过自然语言描述需求完成复杂操作，同时提供了可复现的工作流配置与严格的类型校验，确保自动化过程的稳定性与可靠性。

二、功能特色

Peekaboo 的核心优势在于“可视化感知+AI 驱动+全场景覆盖”，其功能特色可概括为以下六大核心维度，每个维度均围绕“降低自动化门槛、提升操作精准度”展开：

1. 高精度屏幕捕获：像素级还原，多场景适配

Peekaboo 提供行业领先的屏幕捕获能力，突破了传统 macOS 截图工具的功能局限：

• 多目标捕获：支持全屏、单个窗口、菜单栏、应用菜单等多种捕获模式，可精准定位任意可视化元素，无需手动框选或调整范围；

• Retina 高清适配：默认支持 2 倍 Retina 缩放，确保截图在高清屏幕上依然保持像素级清晰，避免因缩放导致的 AI 识别误差；

• 结构化输出：捕获后不仅生成图片文件，还会自动标注 UI 元素 ID、位置坐标、文本标签等结构化数据，以 JSON 格式输出，为后续自动化操作提供精准定位依据；

• 无干扰捕获：捕获过程不影响当前应用运行，支持后台捕获与多窗口切换捕获，尤其适用于需要连续操作的自动化场景。

2. AI 驱动的智能交互：自然语言+多模型兼容

AI 能力是 Peekaboo 的核心竞争力，它并非绑定单一 AI 模型，而是构建了多厂商、多类型的 AI 生态：

• 自然语言自动化：支持直接通过自然语言描述需求，AI 智能体会自动拆解任务、调用工具链完成操作。例如输入“Open Notes and create a TODO list with three items”，工具会自动启动备忘录应用、创建清单并添加三个条目，无需手动编写任何命令；

• 多 AI 提供商支持：覆盖主流云端 AI 模型与本地模型，包括 OpenAI（GPT-5.1 默认、GPT-4.1/4o 视觉版）、Anthropic（Claude 4.x）、xAI（Grok 4-fast 推理+视觉）、Google（Gemini 2.5 Pro/Flash），以及本地 Ollama 模型（llama3.3、llava 等），用户可根据需求选择云端高效模型或本地隐私保护模型；

• 视觉问答能力：支持对捕获的截图进行 AI 分析，例如识别界面元素功能、提取文本信息、判断操作状态等，即使无结构化 UI 数据也能完成精准交互；

• 智能任务拆解：对于复杂需求，AI 会自动拆分为多个步骤（如“打开浏览器→访问网址→输入账号密码→点击登录”），并按顺序调用对应的 CLI 命令，无需用户手动拆分流程。

3. 全场景 GUI 自动化：覆盖 macOS 核心操作

Peekaboo 几乎覆盖了 macOS 系统的所有可视化操作场景，提供近 20 类核心命令，满足从简单点击到复杂工作流的全需求：

• 基础交互操作：包括点击（按元素 ID、标签、坐标）、文本输入（支持清空、输入延迟调节）、快捷键触发（如 cmd+shift+t）、滚动（上下方向、滚动步数控制）、拖拽（平滑手势拖拽、跨元素拖拽）等；

• 窗口与空间管理：支持窗口列表查看、移动、缩放、聚焦、设置边界，以及 macOS 多空间（Spaces）的切换、窗口跨空间移动等，解决多屏幕办公场景的自动化需求；

• 应用与 Dock 控制：可启动、退出、重启、切换应用，列出当前运行应用；同时支持 Dock 项目的启动、右键点击、隐藏/显示、列表查看，甚至可将文件拖拽至 Dock 应用或废纸篓；

• 菜单与状态栏操作：无需点击即可列出应用菜单、系统菜单栏项目，支持精准点击菜单选项或状态栏图标（如音量调节、网络切换），解决传统自动化工具难以操控菜单的痛点；

• 系统对话框驱动：支持识别并操控系统对话框（如文件打开/保存、权限请求、警报框），可自动输入文本、选择文件、点击确认/取消，解决自动化流程中“对话框阻塞”的核心问题。

4. 双运行模式：灵活适配不同使用场景

Peekaboo 提供 CLI 与 MCP 服务器两种运行模式，兼顾轻量化操作与深度集成需求：

• CLI 命令行模式：适用于快速操作、脚本编写、批量任务执行，所有功能均可通过终端命令调用，支持命令组合与管道操作（如通过管道传递截图 ID 实现“捕获-点击”联动）；

• MCP 服务器模式：可作为 MCP 服务器运行，与 Claude Desktop、Cursor 等支持 MCP 协议的 AI 工具集成，让 AI 智能体直接调用 Peekaboo 的自动化能力，实现“自然语言描述→AI 调用工具→系统执行”的端到端自动化，无需用户手动输入任何命令。

5. 高可配置性与可复现性：适配个性化需求

Peekaboo 提供完善的配置与工作流管理功能，确保自动化过程的灵活性与稳定性：

• 灵活配置选项：支持通过环境变量（如 PEEKABOO_AI_PROVIDERS）或命令行配置 AI 提供商、模型参数、截图保存路径、操作延迟等，适配不同场景的个性化需求；

• 自动化脚本支持：可将复杂工作流编写为 .peekaboo.json 配置文件，通过 peekaboo run 命令一键执行，支持步骤顺序控制、错误处理（--no-fail-fast 选项）、输出结果自定义；

• 快照与缓存管理：自动保存操作过程中的截图快照与元素数据，支持快照复用（如多次点击基于同一快照）、缓存清理（按时间或快照 ID 删除），确保工作流可复现与系统资源优化；

• 权限管理工具：提供专门的 permissions 命令，可快速查看当前屏幕录制、辅助功能权限状态，引导用户一键授予所需权限，避免因权限问题导致自动化失败。

6. 开发友好：开源透明，易于扩展

作为开源项目，Peekaboo 为开发者提供了完善的二次开发支持：

• 清晰的代码结构：项目分为 Core（核心功能）、Apps（应用程序）、Helpers（辅助工具）、Examples（示例代码）等模块，依赖管理清晰，支持 Swift Package Manager（SPM）；

• 丰富的开发工具：提供格式化脚本（swiftformat）、代码检查工具（swiftlint）、测试脚本，支持 CI/CD 流程，便于开发者参与贡献或二次开发；

• 详细的文档支持：项目包含 AGENTS.md（AI 智能体使用指南）、CLAUDE.md（Claude 集成文档）、CHANGELOG.md（版本更新日志）等，同时提供权限配置、快速启动、命令详解等文档，降低开发与使用门槛。

三、技术细节

Peekaboo 的强大功能背后，是基于 macOS 原生技术与现代开发框架的深度优化，其核心技术细节可从以下维度解析：

1. 技术栈选型

Peekaboo 采用“主语言+辅助工具”的技术架构，确保性能与兼容性的平衡：

• 核心开发语言：Swift 6.2，作为 macOS 原生开发语言，Swift 具备高性能、类型安全、与系统 API 深度集成的优势，能够高效调用 macOS 屏幕捕获、窗口管理、 accessibility 等底层接口；

• 辅助技术：Node.js 22.0+（仅用于 MCP 服务器包装、npm 包发布、辅助脚本运行，核心 CLI 与应用功能不依赖 Node.js）；

• 依赖管理：使用 Swift Package Manager（SPM）管理 Swift 依赖（如 AXorcist、Commander 等子模块），pnpm 管理 Node.js 依赖，确保依赖版本一致性与安装效率；

• 构建工具：支持 Xcode 16+ 构建，提供脚本化构建流程（pnpm run build:cli），便于开发者快速编译与测试。

2. 核心技术实现

（1）屏幕捕获与 UI 识别

• 底层接口：基于 macOS 原生的 Core Graphics、Quartz Display Services 框架实现屏幕捕获，支持高分辨率截图与多屏幕检测，相比第三方库减少了性能损耗；

• Accessibility 集成：通过 macOS 的 Accessibility API（辅助功能 API）获取 UI 元素的结构化数据（如元素 ID、位置、标签、类型），结合 AXorcist 子模块优化 UI 元素识别精度，即使无视觉信息也能定位元素；

• Retina 适配：自动检测屏幕缩放比例，支持 1x/2x 缩放模式切换，截图时保留原始像素信息，避免因 Retina 屏幕缩放导致的坐标偏移问题；

• 快照管理：捕获的截图与 UI 数据会以快照形式存储，每个快照分配唯一 ID，支持跨命令复用，减少重复捕获带来的性能开销。

（2）AI 集成架构

• 多模型适配层：Peekaboo 设计了统一的 AI 提供商接口，通过封装不同厂商的 API（如 OpenAI API、Anthropic API、Ollama 本地接口），实现“一键切换模型”，开发者可通过扩展接口添加自定义 AI 提供商；

• 视觉-文本联动：对于需要视觉分析的场景（如截图内容识别、界面元素定位），工具会自动将截图转换为 AI 模型支持的格式（如 Base64 编码），结合文本描述发送至模型，接收结构化的分析结果后映射为操作指令；

• 智能体工作流：基于 Prompt Engineering 优化 AI 提示词，让模型能够理解自动化任务需求、拆解步骤、选择合适的 CLI 命令，同时支持“干运行”（--dry-run）模式，预览操作步骤而不实际执行，降低误操作风险。

（3）自动化执行引擎

• 事件注入：通过 macOS 的 CGEvent 框架模拟用户输入事件（鼠标点击、键盘输入、快捷键），事件注入精度达毫秒级，支持模拟真实用户的操作节奏（如输入延迟、拖拽速度调节）；

• 窗口与空间管理：基于 NSWindow、NSWorkspace 框架获取窗口信息与应用状态，通过 AppleScript 辅助实现跨应用交互与多空间切换，确保操作的兼容性与稳定性；

• 错误处理机制：内置操作失败重试、超时检测、权限校验等逻辑，例如点击操作失败时会重新捕获 UI 元素并尝试定位，权限不足时会提示用户授予权限，提升自动化流程的鲁棒性。

（4）MCP 服务器实现

• 协议兼容：遵循 MCP（Model Control Protocol）规范，实现与 Claude Desktop、Cursor 等工具的通信，支持命令下发、结果返回、错误处理等核心流程；

• 轻量级服务：MCP 服务器以 Node.js 脚本形式实现（peekaboo-mcp.js），无需额外部署，通过 npx @steipete/peekaboo 即可快速启动，占用资源少，响应速度快；

• 环境隔离：支持为 MCP 服务器配置独立的环境变量（如指定 AI 提供商），与 CLI 模式的配置互不干扰，便于不同场景的灵活切换。

3. 项目结构

Peekaboo 的项目结构清晰，模块划分合理，便于维护与扩展，核心目录如下：

• Core：核心功能模块，包含屏幕捕获、AI 集成、自动化执行、命令解析等核心逻辑；

• Apps：应用程序模块，包含 Peekaboo 桌面应用与 CLI 入口；

• Helpers：辅助工具模块，如 MenuBarHelper（菜单栏辅助工具）；

• Submodules（子模块）：依赖的开源项目，如 AXorcist（Accessibility 工具）、Commander（命令行解析库）、Tachikoma（MCP 服务器辅助库）等；

• Examples：示例代码模块，提供自动化脚本示例，帮助用户快速上手；

• docs：文档模块，包含权限配置、快速启动、命令详解、集成指南等；

• scripts：构建与测试脚本，如编译脚本、格式化脚本、测试脚本；

• release：发布相关文件，如更新日志、安装包配置；

• homebrew：Homebrew 安装配置，支持通过 brew 快速安装。

4. 性能优化

Peekaboo 针对 macOS 系统特性进行了多维度性能优化：

• 低资源占用：核心功能基于原生框架开发，避免冗余依赖，截图与自动化操作过程中 CPU 占用率低，不影响其他应用运行；

• 缓存机制：缓存频繁使用的 UI 元素数据与截图快照，减少重复计算与 I/O 操作；

• 异步处理：支持多步骤异步执行，例如截图捕获与 AI 分析可并行处理，提升复杂任务的执行效率；

• 按需加载：依赖模块按需加载，例如 MCP 服务器相关代码仅在启动 MCP 模式时加载，减少 CLI 模式的启动时间。

四、应用场景

Peekaboo 凭借其“可视化+AI 驱动+全场景覆盖”的特性，可广泛应用于个人办公、开发者效率提升、企业自动化流程等多个场景，以下是典型应用场景解析：

1. 个人办公自动化：解放重复劳动

日常办公中，大量重复操作（如文件整理、数据录入、报表生成）可通过 Peekaboo 实现自动化，节省时间与精力：

• 文件批量处理：例如“将桌面所有 PDF 文件移动至 Documents/PDF 文件夹，并重命名为‘日期+原文件名’”，通过自然语言描述或简单脚本即可自动执行；

• 数据录入与报表生成：从网页、Excel 表格中提取数据，自动填入表单、生成规范报表（如每周工作周报模板填充），支持跨应用数据传输；

• 软件操作自动化：例如“每天 9 点启动 Safari，访问公司内网，自动登录账号（输入用户名密码、点击登录按钮），打开工作看板”，通过定时任务+Peekaboo 脚本实现；

• 系统设置快速配置：新电脑初始化时，通过脚本自动设置桌面背景、 Dock 位置、网络配置、浏览器书签等，无需手动逐一配置。

2. 开发者效率提升：简化开发与测试流程

开发者在日常开发、测试过程中，经常需要重复执行环境配置、测试步骤等操作，Peekaboo 可显著提升效率：

• 开发环境一键搭建：自动下载依赖、配置环境变量、启动开发服务器、打开代码编辑器与浏览器，让开发者快速进入开发状态；

• UI 自动化测试：针对 macOS 应用，编写自动化测试脚本，模拟用户操作（点击按钮、输入文本、切换窗口），自动验证 UI 功能是否正常，支持批量测试与结果输出；

• 日志分析与报告生成：自动捕获应用运行日志、截图报错界面、提取错误信息，生成结构化测试报告，便于问题定位；

• 多版本兼容性测试：自动切换应用版本、系统版本，执行相同的测试流程，验证应用在不同环境下的兼容性，减少手动测试工作量。

3. AI 智能体集成：扩展 AI 工具的系统操控能力

随着 AI 智能体（如 Claude Desktop、Cursor）的普及，Peekaboo 可作为“AI 与系统交互的桥梁”，让 AI 具备直接操控 macOS 的能力：

• AI 辅助办公：向 Claude Desktop 输入“帮我整理桌面文件，将图片文件分类到 Pictures 文件夹，文档文件分类到 Documents 文件夹”，AI 会通过 MCP 服务器调用 Peekaboo 完成操作；

• AI 驱动的软件使用：对于复杂软件（如 Photoshop、Final Cut Pro），可通过自然语言向 AI 描述需求（如“用 Photoshop 打开图片，裁剪为 1080x1080 尺寸，保存为 PNG 格式”），AI 调用 Peekaboo 自动执行操作，无需手动熟悉软件操作流程；

• 智能问题解决：当遇到系统问题（如网络连接异常），AI 可通过 Peekaboo 捕获系统设置界面、分析当前配置，自动尝试修复（如重启网络服务、重新连接 Wi-Fi）。

4. 企业批量管理：简化设备与流程管控

企业 IT 部门或行政部门可利用 Peekaboo 实现多台 macOS 设备的批量管理与流程标准化：

• 设备批量配置：为新入职员工的电脑自动配置企业办公软件（如 Slack、Office）、网络权限、安全设置，确保设备配置统一；

• 流程标准化执行：例如“员工入职流程”，自动打开 HR 系统、填写入职表单、发送欢迎邮件、添加企业通讯录，减少人工操作与错误；

• 设备状态监控：定期捕获设备屏幕、列出运行应用、检查系统更新状态，生成设备使用报告，便于 IT 部门监控设备安全与性能。

5. 创意与设计辅助：自动化重复设计操作

设计师在日常工作中，部分重复的设计操作（如格式转换、批量导出）可通过 Peekaboo 自动化：

• 图片批量处理：自动打开设计软件（如 Sketch、Figma 桌面端），导出指定尺寸的图片、转换图片格式（如 SVG 转 PNG）、添加水印；

• 设计规范检查：自动捕获设计稿界面，通过 AI 分析是否符合企业设计规范（如颜色、字体、间距），生成检查报告；

• 演示文稿自动化：自动打开 Keynote，导入设计图片、填充文本内容、设置动画效果，生成标准化演示文稿。

五、使用方法

Peekaboo 的使用流程简单直观，分为“安装-权限配置-基础使用-高级配置”四个步骤，无论是技术用户还是非技术用户，都能快速上手：

1. 安装准备

在安装 Peekaboo 前，需确保满足以下环境要求：

• 操作系统：macOS 15.0+（Sequoia）；

• 可选依赖：Node.js 22.0+（仅用于 MCP 服务器模式或开发构建，核心功能无需）；

• 开发环境（可选）：Xcode 16+、Swift 6.2（用于二次开发或编译源码）。

2. 安装方式

Peekaboo 提供两种主流安装方式，用户可根据需求选择：

（1）Homebrew 安装（推荐，适用于 macOS 应用+CLI）

Homebrew 是 macOS 常用的包管理器，通过以下命令可快速安装 Peekaboo 及其 CLI 工具：

brew install steipete/tap/peekaboo

安装完成后，在终端输入 peekaboo --version，若输出“3.0.0-beta4”（当前版本），则说明安装成功。

（2）npm 安装（适用于 MCP 服务器模式，无需全局安装）

若仅需使用 MCP 服务器模式（如与 Claude 集成），可通过 npm 直接运行，无需全局安装：

npx -y @steipete/peekaboo

该命令会自动下载 MCP 服务器相关依赖并启动服务，适用于临时使用或无需 CLI 功能的场景。

（3）源码编译安装（适用于开发或自定义修改）

若需二次开发或使用最新未发布功能，可通过源码编译安装：

1. 克隆仓库：git clone --recurse-submodules https://github.com/steipete/Peekaboo.git（--recurse-submodules 用于拉取子模块）；

2. 进入项目目录：cd Peekaboo；

3. 安装依赖：pnpm install（需先安装 pnpm）；

4. 编译 CLI：pnpm run build:cli；

5. 运行测试：pnpm run test:safe（验证编译结果）；

6. 安装到系统：sudo cp .build/release/peekaboo /usr/local/bin/（或通过 Xcode 归档安装）。

3. 权限配置

Peekaboo 需依赖 macOS 的“屏幕录制权限”与“辅助功能权限”才能正常工作，配置步骤如下：

1. 打开系统设置：点击 macOS 顶部菜单栏“系统设置”；

2. 进入辅助功能：选择“隐私与安全性”→“辅助功能”；

3. 授予辅助功能权限：点击“+”号，选择终端（或使用 Peekaboo 的应用程序），勾选对应的权限；

4. 授予屏幕录制权限：在“隐私与安全性”→“屏幕录制”中，同样勾选终端（或 Peekaboo 应用程序）；

5. 验证权限：在终端输入 peekaboo permissions status，若输出“Screen Recording: Enabled, Accessibility: Enabled”，则说明权限配置成功。

注意：权限配置后，若 Peekaboo 仍无法正常工作，需重启终端或 Peekaboo 应用，确保权限生效。

4. 基础使用（CLI 模式）

CLI 模式是 Peekaboo 最常用的使用方式，支持通过终端命令完成各类操作，以下是核心命令的使用示例：

（1）快速截图

• 捕获全屏并保存到桌面（Retina 2x 缩放）：

 peekaboo image --mode screen --retina --path ~/Desktop/screen.png

• 捕获 Safari 应用窗口并输出 JSON 格式的 UI 数据：

 peekaboo see --app Safari --mode window --json-output

（2）自动化点击与输入

• 通过标签点击 Safari 中的“Reload this page”按钮（需先捕获快照）：

 # 第一步：捕获 Safari 快照并获取快照 ID
 peekaboo see --app Safari --json-output | jq -r '.data.snapshot_id' | read SNAPSHOT
 # 第二步：基于快照 ID 点击指定标签的按钮
 peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"

• 向文本框输入内容（清空原有内容，延迟 100ms 输入）：

 peekaboo type --text "Hello, Peekaboo!" --clear --delay-ms 100

（3）自然语言自动化

直接通过自然语言描述需求，AI 自动完成操作：

peekaboo "Open Notes and create a TODO list with three items: Buy milk, Finish report, Call mom"

执行后，工具会自动启动备忘录应用，创建新清单并添加指定三个条目。

（4）窗口与应用管理

• 列出当前运行的所有应用：

 peekaboo list apps

• 移动 Safari 窗口到屏幕右上角（坐标可通过 peekaboo see 获取）：

 peekaboo window move --app Safari --to "x:1000, y:50"

• 重启微信应用：

 peekaboo app relaunch --app WeChat

（5）菜单与状态栏操作

• 列出 Safari 应用的所有菜单：

 peekaboo menu list --app Safari

• 点击菜单栏中的“Wi-Fi”图标：

 peekaboo menubar click --name "Wi-Fi"

5. 高级使用（MCP 服务器模式）

MCP 服务器模式适用于与 Claude Desktop、Cursor 等 AI 工具集成，让 AI 直接调用 Peekaboo 完成自动化操作，配置步骤如下：

（1）启动 MCP 服务器

在终端输入以下命令，启动 Peekaboo MCP 服务器：

npx -y @steipete/peekaboo

启动成功后，终端会显示服务器地址与端口（默认本地通信）。

（2）配置 Claude Desktop 集成

1. 打开 Claude Desktop，点击顶部菜单栏“Developer”→“Edit Config”；

2. 在配置文件中添加以下内容（指定 MCP 服务器信息与 AI 提供商）：

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

3. 保存配置后，重启 Claude Desktop，即可在对话中让 Claude 调用 Peekaboo 执行操作（如“帮我整理桌面文件”）。

6. 自动化脚本（.peekaboo.json）

对于复杂且需要重复执行的工作流，可编写 .peekaboo.json 脚本文件，通过 peekaboo run 命令一键执行。以下是示例脚本（自动打开浏览器并访问指定网址）：

（1）创建脚本文件

在任意目录创建 my-automation.peekaboo.json，内容如下：

{
 "name": "Open GitHub",
 "steps": [
  {
   "command": "app launch",
   "args": {
    "app": "Safari"
   }
  },
  {
   "command": "sleep",
   "args": {
    "duration": 2000
   }
  },
  {
   "command": "type",
   "args": {
    "text": "https://github.com",
    "clear": false
   }
  },
  {
   "command": "press",
   "args": {
    "key": "return"
   }
  }
 ]
}

（2）执行脚本

在终端进入脚本所在目录，输入以下命令执行：

peekaboo run my-automation.peekaboo.json

工具会按顺序执行脚本中的步骤：启动 Safari→等待 2 秒→输入 GitHub 网址→按下回车访问。

7. AI 提供商配置

Peekaboo 支持通过环境变量或命令行配置 AI 提供商，以下是两种配置方式：

（1）环境变量配置（临时生效）

在终端输入以下命令，指定优先使用的 AI 提供商：

export PEEKABOO_AI_PROVIDERS="openai/gpt-5.1,anthropic/claude-opus-4,ollama/llama3.3"

（2）命令行配置（永久生效）

通过 peekaboo config add 命令添加 AI 提供商配置：

peekaboo config add providers openai/gpt-5.1
peekaboo config add providers anthropic/claude-opus-4

查看当前配置：

peekaboo config show

六、常见问题解答（FAQ）

1. Peekaboo 支持哪些 macOS 版本？

Peekaboo 仅支持 macOS 15.0+（Sequoia）及以上版本，旧版本 macOS（如 Ventura 13.x、Sonoma 14.x）可能存在兼容性问题，建议升级系统后使用。

2. 为什么执行命令时提示“权限不足”？

Peekaboo 需要 macOS 的“屏幕录制权限”与“辅助功能权限”才能正常工作。若提示权限不足，请按照“使用方法-权限配置”部分的步骤，在系统设置中授予终端或 Peekaboo 应用对应的权限，授予后重启终端或应用即可生效。

3. 可以使用本地 AI 模型吗？

可以。Peekaboo 支持 Ollama 本地模型（如 llama3.3、llava 等），使用前需先安装 Ollama 并下载对应的模型（如 ollama pull llama3.3），然后通过配置指定本地模型（如 PEEKABOO_AI_PROVIDERS="ollama/llama3.3"），即可无需联网使用本地 AI 完成自动化操作。

4. MCP 服务器模式无法启动，提示“Node.js 版本过低”怎么办？

MCP 服务器模式依赖 Node.js 22.0+，若提示版本过低，请先升级 Node.js：可通过 nvm（Node Version Manager）安装最新版本（nvm install 22），或直接从 Node.js 官网下载安装。升级后重新执行 npx -y @steipete/peekaboo 即可启动 MCP 服务器。

5. 执行自动化操作时，点击或输入位置不准确怎么办？

这可能是由于屏幕缩放比例未正确识别导致的。建议在截图或执行操作时添加 --retina 选项（适用于 Retina 屏幕），确保坐标计算准确；同时，可通过 peekaboo see --app <应用名> --json-output 查看元素的准确坐标，手动指定坐标进行点击（如 peekaboo click --on "x:200, y:300"）。

6. 如何清理 Peekaboo 生成的快照与缓存？

Peekaboo 提供 clean 命令用于清理快照与缓存：

• 清理所有快照：peekaboo clean --all-snapshots；

• 清理 7 天前的快照：peekaboo clean --older-than 7d；

• 清理指定快照 ID：peekaboo clean --snapshot <快照ID>。

7. 可以自定义 AI 模型的参数吗？

目前 Peekaboo 支持通过环境变量或配置文件指定 AI 提供商与模型，但暂不支持自定义模型的具体参数（如温度值、最大 tokens 等）。该功能计划在后续正式版本中推出，若有需求可关注项目的 CHANGELOG.md 查看更新动态。

8. 二次开发时如何编译与测试代码？

二次开发需满足以下环境：macOS 15.0+、Xcode 16+、Swift 6.2、pnpm。编译与测试步骤如下：

1. 克隆仓库并拉取子模块：git clone --recurse-submodules https://github.com/steipete/peekaboo.git；

2. 安装依赖：pnpm install；

3. 编译 CLI：pnpm run build:cli；

4. 运行安全测试：pnpm run test:safe；

5. 运行本地测试：./.build/release/peekaboo <测试命令>。

9. Peekaboo 会收集用户数据吗？

Peekaboo 是开源工具，所有功能均在本地执行，不会收集用户的屏幕截图、操作记录、AI 交互数据等隐私信息。若使用云端 AI 模型（如 GPT-5.1、Claude 4.x），数据会按 AI 提供商的隐私政策处理，本地模型则完全不涉及数据上传。

七、相关链接

• 项目 GitHub 仓库：https://github.com/steipete/Peekaboo

• npm 包地址：https://www.npmjs.com/package/@steipete/peekaboo

• Homebrew Tap：https://github.com/steipete/homebrew-tap

八、总结

Peekaboo 是一款面向 macOS 系统的开源 AI 自动化工具，通过融合 CLI 与 MCP 服务器双运行模式、高精度屏幕捕获技术、多厂商 AI 模型兼容能力，实现了“可视化感知-AI 决策-自动化执行”的全链路闭环。它既支持技术用户通过命令行编写精准的自动化脚本，也允许非技术用户通过自然语言描述需求完成复杂操作，覆盖了窗口管理、应用控制、菜单交互、系统对话框驱动等 macOS 核心操作场景，适用于个人办公自动化、开发者效率提升、AI 智能体集成、企业批量管理等多个场景。工具基于 Swift 6.2 开发，适配 macOS 15.0+ 系统，以 MIT 协议开源，具备高可配置性、可复现性与可扩展性，同时提供了完善的文档与示例，降低了使用与二次开发门槛。尽管当前处于 beta 版本，但核心功能稳定，已能有效解决 macOS 自动化中的痛点问题，为用户提供高效、灵活、智能的自动化解决方案。