1. 从 AppleScript 到 PeekaboomacOS 自动化为什么需要视觉感知如果你写过 macOS 自动化脚本大概率经历过这种崩溃用 AppleScript 写了一段控制 Safari 的脚本跑得好好的某天系统更新或者应用改版tell application Safari to ...直接报错因为 Scripting Bridge 的接口变了。更别提那些基于 Electron 的应用——Slack、Notion、VS Code它们压根不提供完整的 AppleScript 字典你只能退回到 Python 的pyautogui或者cliclick用硬编码坐标去点按钮。窗口一移动整个流程瞬间翻车。这就是传统 macOS 自动化的根本困境它依赖应用开发者“愿意”暴露接口。AppleScript 本质上是一套预定义的 RPC 协议应用不实现你就没辙。坐标点击则是另一个极端——完全放弃语义把屏幕当成一张静态图片。两者之间缺少一个中间层一个能“看见”屏幕内容、理解 UI 结构、并且用统一协议暴露给 AI 的感知网关。Peekaboo 的出现填补了这个空白。它做的事情可以这样理解把 macOS 的 Accessibility API辅助功能接口和屏幕截图能力封装成一个标准化的 MCP 服务器让 Claude Code、Cursor 这类 AI 开发环境可以直接调用。AI 不再需要“猜”按钮在哪而是通过 Accessibility Tree 拿到结构化的 UI 信息——哪个是按钮、哪个是输入框、它们的标签是什么、当前值是什么。同时Peekaboo 还会返回带注释的截图把视觉坐标和 UI 元素 ID 对应起来。这意味着什么你可以对 AI 说“点击那个发送按钮”而不是“点击坐标 (450, 890)”。即使窗口在操作过程中移动了AI 依然能通过 Accessibility API 重新定位到目标元素。这就是从“盲人摸象”到“眼明手快”的转变。但这里有一个现实问题Peekaboo 本身只是一个感知和执行层它不负责“决策”。决策需要大模型。而当你把 Peekaboo 接入 Claude Code 或者自己写的 Agent 时你会面临多模型 API Key 管理的问题——Claude 一个 Key、GPT 一个 Key、本地模型又是另一套配置。每换一个模型就要改一遍环境变量调试成本极高。TaoToken 在这里的作用就是统一这个入口一个 Key、一个 Base URL兼容 Anthropic 和 OpenAI 两种协议格式让你在 Peekaboo 的 MCP 调用链里可以灵活切换模型而不用反复改配置。这篇文章会带你走完一条完整的链路从 Accessibility 权限验证到 Peekaboo 的 MCP 配置再到用 TaoToken 统一 Key 接入模型最后跑通一个“截图→分析→点击”的闭环。每一步都有可复制的配置片段和排错方法。2. TaoToken 前置准备统一 Key 与 MCP 调用链的接入点在开始配置 Peekaboo 之前你需要先解决模型接入的问题。Peekaboo 本身不包含模型它只负责“看”和“动”。真正的决策来自你接入的 AI 模型。如果你用 Claude Code 作为 Agent 宿主它默认走 Anthropic 的 API如果你用 Cursor 或者自己写的 Python Agent可能走 OpenAI 兼容接口。每换一个宿主就要重新配一遍 Key 和 Base URL非常麻烦。TaoToken 的做法是提供一个统一的 API 入口同时兼容 Anthropic 和 OpenAI 两种协议格式。你只需要一个 Key就可以在 Claude Code、Cursor、Cline 或者自定义脚本里调用不同的模型。对于 Peekaboo 这种需要频繁调用模型进行“观察-决策-执行”的链路来说统一 Key 意味着你可以在调试时快速切换模型比如用 Claude 做复杂推理用 GPT-4o 做快速视觉理解而不用改任何 MCP 配置。先拿到你的 API Key。访问 TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite注册后创建一个 Key。这个 Key 同时适用于 Anthropic 和 OpenAI 两种调用格式。Base URL 是https://taotoken.net/api注意不要加 UTM 参数直接写这个地址就行。接下来验证 Key 是否可用。用 curl 发一个最简单的请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-your-key-here \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回 JSON 里包含content字段说明 Key 和通道都正常。如果你用的是 OpenAI 兼容格式把路径改成/v1/chat/completionsHeader 改成Authorization: Bearer sk-your-key-hereBody 改成 OpenAI 的格式即可。这里有一个容易踩的坑TaoToken 的 Anthropic 端点和 OpenAI 端点是分开的路径。Anthropic 用/v1/messagesOpenAI 用/v1/chat/completions。不要混用 Header 和路径否则会返回 401。如果你在 Claude Code 里配置它默认走 Anthropic 格式所以 Base URL 填https://taotoken.net/apiKey 填你的 Key模型名填claude-sonnet-4-20250514或者你需要的其他模型。对于 Peekaboo 的 MCP 调用链我建议把模型配置放在环境变量里而不是硬编码在 MCP 配置文件中。这样你可以在不同项目之间快速切换。比如在~/.zshrc里加export TAOTOKEN_API_KEYsk-your-key-here export TAOTOKEN_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY export ANTHROPIC_BASE_URL$TAOTOKEN_BASE_URL这样 Claude Code 启动时会自动读取这些环境变量不需要在配置文件里重复写 Key。如果你用 Cline 或者 Cursor它们也支持从环境变量读取 API Key配置方式类似。还有一个细节Peekaboo 作为 MCP 服务器它本身不直接调用模型。模型调用发生在 Agent 宿主比如 Claude Code里。所以你需要确保 Agent 宿主的模型配置指向 TaoToken。以 Claude Code 为例它的配置文件在~/.claude/settings.json你可以这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-key-here } }如果你用 Cline它的 MCP 配置在 VS Code 的 settings.json 里模型配置在 Cline 自己的设置面板里。把 API Provider 选成 AnthropicBase URL 填https://taotoken.net/apiKey 填你的 Key模型选claude-sonnet-4-20250514。到这里前置准备就完成了。你有了一个统一的 Key可以同时服务 Anthropic 和 OpenAI 两种协议接下来就是配置 Peekaboo 本身。3. 可复制配置Peekaboo MCP 服务器与 Accessibility 权限验证Peekaboo 的安装方式有两种通过 Homebrew 安装预编译版本或者从源码编译。我建议用 Homebrew因为依赖管理更简单。打开终端执行brew tap steipete/tap brew install peekaboo安装完成后你需要给 Peekaboo 授予 Accessibility 权限。这是 macOS 的安全机制任何想要读取 UI 元素或者模拟输入的应用都必须获得这个权限。打开“系统设置”→“隐私与安全性”→“辅助功能”点击“”号把 Peekaboo 的可执行文件加进去。如果你不知道 Peekaboo 装在哪用which peekaboo查一下路径通常在/opt/homebrew/bin/peekaboo。授予权限后验证一下是否生效peekaboo permissions如果输出里accessibility显示granted说明权限没问题。如果显示denied你需要回到系统设置里重新勾选。有时候系统会缓存旧的权限状态重启终端或者注销重新登录可以解决。接下来配置 MCP 服务器。Peekaboo 自带一个 MCP 模式启动命令是peekaboo mcp。你需要在 Agent 宿主的 MCP 配置文件里注册这个服务器。以 Claude Code 为例MCP 配置文件在~/.claude/mcp.json如果没有就新建一个。写入以下内容{ mcpServers: { peekaboo: { command: /opt/homebrew/bin/peekaboo, args: [mcp], env: { PEEKABOO_SCREENSHOT_DIR: /tmp/peekaboo, PEEKABOO_LOG_LEVEL: info } } } }注意command字段要填 Peekaboo 的绝对路径不要用peekaboo这个简写因为 MCP 服务器启动时不会加载你的 shell 环境变量找不到 PATH。args里的mcp是子命令告诉 Peekaboo 以 MCP 服务器模式运行。env里可以配置截图保存目录和日志级别方便调试。如果你用 ClineMCP 配置在 VS Code 的settings.json里格式类似{ cline.mcpServers: { peekaboo: { command: /opt/homebrew/bin/peekaboo, args: [mcp], env: { PEEKABOO_SCREENSHOT_DIR: /tmp/peekaboo, PEEKABOO_LOG_LEVEL: info } } } }配置完成后重启 Claude Code 或者 Cline。在 Claude Code 里输入/mcp命令应该能看到peekaboo服务器状态是connected。如果显示failed检查路径是否正确以及 Peekaboo 是否真的有可执行权限。现在验证 Accessibility API 是否真的能读到 UI 元素。在终端里直接运行peekaboo see --json这个命令会返回当前屏幕的 Accessibility Tree 快照格式是 JSON。你会看到一堆嵌套的节点每个节点有role、title、value、position、size等字段。比如一个按钮会显示role: AXButton一个输入框会显示role: AXTextField。如果返回的是空数组或者报错Accessibility API not available说明权限没生效回到系统设置里重新授权。这里有一个关键点Peekaboo 的see命令默认只返回当前活动窗口的 UI 树。如果你想看整个屏幕的所有窗口加--all参数。但通常我们只需要操作当前窗口所以默认行为就够了。接下来测试截图功能peekaboo screenshot --output /tmp/test.png打开/tmp/test.png应该能看到当前屏幕的截图。Peekaboo 的截图会带上 UI 元素的标注框每个框对应 Accessibility Tree 里的一个节点。这样 AI 就能把视觉信息和结构信息对应起来。如果你在 MCP 模式下调用Peekaboo 会暴露几个工具see、click、type、scroll、screenshot。Claude Code 会自动发现这些工具你可以在对话里直接说“看一下当前屏幕”Claude 就会调用peekaboo.see工具。配置到这里就完成了。但有一个常见问题MCP 服务器启动时找不到 Peekaboo 的路径。如果你用 Homebrew 安装路径是/opt/homebrew/bin/peekaboo如果你用 Intel Mac路径是/usr/local/bin/peekaboo。用which peekaboo确认一下然后填到command字段里。还有一个坑macOS 的 Accessibility 权限是按应用签名的。如果你从源码编译 Peekaboo每次重新编译后签名会变系统会认为这是一个新应用需要重新授权。所以建议用 Homebrew 安装稳定版本避免频繁重新授权。4. 验证请求跑通 See-Decide-Act 闭环与成功结果配置完成后我们来跑一个完整的闭环让 AI 观察屏幕、决定点击哪个按钮、执行点击。为了演示我打开一个简单的文本编辑器比如 TextEdit里面放一个按钮或者输入框。然后启动 Claude Code输入请用 peekaboo 看一下当前屏幕找到 TextEdit 的输入区域然后输入 Hello from PeekabooClaude Code 会先调用peekaboo.see工具拿到 Accessibility Tree 和截图。然后它会分析返回的 JSON找到AXTextArea或者AXTextField节点。接着调用peekaboo.click点击那个区域最后调用peekaboo.type输入文本。你可以在 Claude Code 的日志里看到完整的调用链[peekaboo] see - 返回 23 个 UI 节点 [peekaboo] click - 点击 AXTextArea at (400, 300) [peekaboo] type - 输入 Hello from Peekaboo如果一切正常TextEdit 里会出现你输入的文本。这就是 See-Decide-Act 闭环Peekaboo 负责 See 和 ActClaude 负责 Decide。但这里有一个关键点Claude 的决策质量取决于它拿到的 UI 信息是否完整。Peekaboo 返回的 JSON 里每个节点都有role、title、value、position、size。如果某个按钮没有titleClaude 可能无法识别它。这时候你可以用peekaboo see --annotate参数让 Peekaboo 在截图上画框并标注序号Claude 可以通过序号来引用元素。实测下来Peekaboo 对原生 macOS 应用Finder、Safari、TextEdit的支持最好因为它们的 Accessibility Tree 很完整。对 Electron 应用VS Code、Slack的支持也不错但偶尔会有节点缺失。对完全自定义绘图的应用比如游戏Peekaboo 只能回退到纯视觉坐标这时候就需要 Claude 的视觉理解能力来定位目标。如果你想让流程更稳定可以在 MCP 配置里加一个PEEKABOO_TIMEOUT环境变量控制每次操作的超时时间。默认是 5000 毫秒对于复杂的 UI 树解析可能不够可以调到 10000。{ mcpServers: { peekaboo: { command: /opt/homebrew/bin/peekaboo, args: [mcp], env: { PEEKABOO_SCREENSHOT_DIR: /tmp/peekaboo, PEEKABOO_LOG_LEVEL: info, PEEKABOO_TIMEOUT: 10000 } } } }还有一个实用技巧Peekaboo 支持--window-id参数可以指定操作哪个窗口。如果你有多个显示器或者多个窗口这个参数很有用。在 MCP 模式下Claude 可以通过see工具返回的窗口列表来选择目标窗口。现在验证模型调用是否走了 TaoToken。在 Claude Code 里输入/status应该能看到 API Base URL 是https://taotoken.net/api。如果你用 curl 直接测试可以发一个请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-your-key-here \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 200, messages: [{role: user, content: 用一句话描述 macOS Accessibility API 的作用}] }如果返回正常说明 TaoToken 通道没问题。这时候你的 Peekaboo 闭环就完全跑通了Peekaboo 负责感知和执行Claude 负责决策TaoToken 负责模型接入。如果你想让 Agent 更智能可以在 Claude Code 的 system prompt 里加一段关于 Peekaboo 工具使用的说明。比如你可以使用 peekaboo 工具来观察和操作 macOS 屏幕。 当用户要求你操作某个应用时先用 peekaboo.see 获取当前屏幕的 UI 树 找到目标元素后用 peekaboo.click 点击它或者用 peekaboo.type 输入文本。 如果 UI 树里找不到目标元素尝试用 peekaboo.screenshot 获取截图 然后根据视觉信息推断坐标。这样 Claude 会更倾向于使用 Peekaboo 工具而不是自己瞎猜。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth即使配置正确你仍然可能遇到一些报错。这一节整理了几个高频问题及其解决方法。401 Unauthorized这是最常见的错误通常是因为 API Key 不对或者 Base URL 写错了。检查你的 Key 是否以sk-开头Base URL 是否是https://taotoken.net/api注意不要加/v1TaoToken 的 Anthropic 端点是/v1/messages但 Base URL 本身不带/v1。如果你在 Claude Code 里配置确认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY环境变量是否正确。有时候 Key 复制时带了空格也会导致 401。用echo $ANTHROPIC_API_KEY | tr -d 检查一下。local proxy failed这个错误通常出现在 MCP 服务器启动时。Peekaboo 的 MCP 模式需要访问本地网络接口如果你的防火墙或者安全软件阻止了本地连接就会报这个错。解决方法是在系统设置→隐私与安全性→防火墙里允许 Peekaboo 接受传入连接。如果你用 Little Snitch 之类的工具也要放行 Peekaboo。reading choices 报错这个错误通常来自 OpenAI 兼容接口的响应解析。如果你用 TaoToken 的 OpenAI 端点但模型返回的格式和预期不符就会报reading choices错误。检查你的请求 Body 是否符合 OpenAI 格式{ model: gpt-4o, messages: [{role: user, content: Hello}], max_tokens: 100 }注意 OpenAI 格式用messages数组Anthropic 格式也用messages但 Header 和路径不同。如果你混用了就会报错。另外TaoToken 的 OpenAI 端点路径是/v1/chat/completions不要写成/v1/messages。OAuth 相关错误如果你在 Claude Code 里看到 OAuth 报错通常是因为 Claude Code 尝试用 OAuth 登录 Anthropic 官方账号而不是用 API Key。解决方法是在~/.claude/settings.json里明确设置ANTHROPIC_API_KEY并且不要运行claude login。如果你已经登录了 OAuth运行claude logout清除状态然后重启 Claude Code。Peekaboo 权限被重置macOS 有时会在系统更新后重置 Accessibility 权限。如果你发现 Peekaboo 突然不能读取 UI 树了回到系统设置→隐私与安全性→辅助功能把 Peekaboo 移除再重新添加。有时候需要重启终端才能生效。MCP 服务器连接失败在 Claude Code 里输入/mcp查看服务器状态。如果显示failed检查command字段的路径是否正确。用ls -la /opt/homebrew/bin/peekaboo确认文件存在且有可执行权限。如果路径不对用which peekaboo重新获取。模型返回空响应如果你用 TaoToken 调用模型时返回空内容检查max_tokens是否设置得太小。有些模型在max_tokens小于 10 时会返回空。另外检查你的请求是否包含了stream: true如果你不处理流式响应可能会看到空结果。在 Claude Code 里默认是流式响应不需要额外配置。截图目录不存在Peekaboo 默认把截图保存到/tmp/peekaboo如果这个目录不存在会报错。手动创建一下mkdir -p /tmp/peekaboo或者在 MCP 配置里把PEEKABOO_SCREENSHOT_DIR改成一个已存在的目录。Accessibility API 返回空树如果peekaboo see --json返回空数组说明当前活动窗口没有 Accessibility 信息。这可能是因为应用没有实现 Accessibility API或者窗口没有焦点。尝试点击一下目标窗口让它成为活动窗口然后再运行命令。如果还是空用peekaboo see --all查看所有窗口。TaoToken 返回 429这是速率限制错误。TaoToken 对免费账号有 QPS 限制如果你在短时间内发送大量请求会触发 429。解决方法是在 Agent 里加一个重试机制或者升级到付费计划。在 Claude Code 里你可以设置ANTHROPIC_MAX_RETRIES3环境变量让它自动重试。模型名称不匹配如果你在 Claude Code 里配置了claude-sonnet-4-20250514但 TaoToken 不支持这个模型名会返回 404。检查 TaoToken 的文档确认支持的模型列表。通常claude-sonnet-4-20250514、claude-opus-4-20250514、gpt-4o都是支持的。如果你不确定用claude-sonnet-4-20250514这个通用名称。排错的核心思路是先确认 Key 和 Base URL 正确再确认 MCP 服务器启动成功最后确认 Accessibility 权限生效。这三步都过了基本不会有大问题。6. 长期编码与 Agent 场景用 Coding Plan 统一管理模型调用如果你只是偶尔跑一下 Peekaboo 的 demo按量付费的 API Key 就够了。但如果你想把 macOS 自动化做成一个长期运行的 Agent比如每天自动整理文件、自动填写表单、自动截图分析那么按量付费的成本会很快累积。这时候可以考虑 TaoToken 的 Coding Plan它提供固定的月度额度适合高频调用的场景。Coding Plan 的接入方式和普通 API Key 一样只是 Key 的额度类型不同。你可以在 TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite里查看当前的用量和额度。如果你用 Claude Code 作为 Agent 宿主Coding Plan 的 Key 可以直接替换ANTHROPIC_API_KEY不需要改其他配置。对于 Peekaboo 这种需要频繁调用模型的场景我建议把模型调用和工具调用分开管理。Peekaboo 的 MCP 服务器负责工具调用see、click、type模型调用由 Agent 宿主负责。这样你可以在 Agent 宿主里配置多个模型比如用 Claude 做复杂决策用 GPT-4o 做快速视觉理解。TaoToken 的统一 Key 让你可以在同一个 Base URL 下切换模型只需要改模型名即可。如果你用 Cline 或者 Cursor它们的 MCP 配置和 Claude Code 类似只是配置文件路径不同。Cline 的 MCP 配置在 VS Code 的settings.json里模型配置在 Cline 的设置面板里。把 API Provider 选成 AnthropicBase URL 填https://taotoken.net/apiKey 填你的 Coding Plan Key模型选claude-sonnet-4-20250514。如果你自己写 Python Agent可以用anthropic或者openai库把base_url指向 TaoToken。比如from anthropic import Anthropic client Anthropic( api_keysk-your-key-here, base_urlhttps://taotoken.net/api ) response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens1024, messages[{role: user, content: 分析这张截图里的 UI 元素}] )这样你的 Python Agent 就可以同时调用 Peekaboo 的 MCP 工具和 TaoToken 的模型接口。对于长期运行的 Agent还有一个建议把 Peekaboo 的 MCP 服务器配置成开机自启动。你可以用launchd创建一个 plist 文件让 Peekaboo 在后台常驻。这样 Agent 启动时不需要重新拉起 MCP 服务器响应更快。具体做法是在~/Library/LaunchAgents/下创建一个com.peekaboo.mcp.plist内容如下?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.peekaboo.mcp/string keyProgramArguments/key array string/opt/homebrew/bin/peekaboo/string stringmcp/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plist然后运行launchctl load ~/Library/LaunchAgents/com.peekaboo.mcp.plist。这样 Peekaboo 就会在后台常驻Agent 随时可以连接。最后如果你在配置过程中遇到问题可以查阅 TaoToken 的接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有详细的 API 说明和示例代码。如果你只是想快速验证模型是否可用可以用模型对话页面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite直接测试。对于长期编码和 Agent 场景Coding Plan 是更经济的选择。