1. 为什么我要把截图工具做成 CLI 和 Agent 工具截图这件事看起来是个小需求但只要你每天在写文档、提 issue、做教程、跑自动化流程就会发现它出现的频率高得离谱。我统计过自己一天的操作写代码时截报错、写文章时截界面、给同事演示时截配置、做 Agent 自动化时截运行结果。一天下来二三十次是常态。问题在于传统截图工具是给人眼和手设计的不是给程序设计的。你按下快捷键、框选、保存、再手动把文件路径贴到某个地方这一套动作对人来说很自然但对一个正在跑的 Agent 工作流来说它根本插不进去。Agent 需要的是我调用一个命令你返回一个图片路径或者一段识别文本我继续往下走。这就是「拓」Ta这个开源 AI 原生截图工具想解决的问题。它有两个身份对普通用户它是一个带 AI 能力的桌面截图软件对开发者它是一个可以塞进任何 Agent 的 CLI 工具和 skill。你可以把它理解成「截图界的 curl」——一条命令完成截图、识别、翻译、标注输出结构化结果。它适合谁三类人最值得看一是需要给自动化流程加截图能力的后端/测试/运维开发者二是在做 Agent 应用、想让 Agent 具备「看屏幕」能力的 AI 工程师三是每天大量截图、想用 AI 把识别和翻译链路压缩到 3 秒内的效率党。我试过把它接进 Codex 之后让它帮我写教程文档它能自己截图、自己标注重点、自己把图插进 Markdown整个过程不需要我碰鼠标。这篇文章就把 CLI 安装、Agent 工具注册、输出验证、错误排查这几件事讲透你照着做就能嵌进现有工作流。2. TaoToken 前置准备给截图工具接上模型能力「拓」本身是截图工具但它的 AI 识别、翻译、识图、美化这些能力需要调用大模型。所以你要先有一个能稳定调用多模态模型的入口。这里我用 TaoToken 来做模型接入层原因是它把多家模型的调用方式统一成了 OpenAI 兼容格式配置一次就能在 CLI、Agent、桌面端复用不用为每个模型单独写适配。先说清楚 TaoToken 是什么它是一个大模型 API 聚合调用平台提供统一的 Base URL 和 API Key兼容 OpenAI 的/v1/chat/completions协议支持文本和多模态图片输入。对「拓」这种需要传图片 base64 或图片 URL 的工具来说只要模型支持视觉理解就能直接走通。你需要准备三样东西第一API Key。到 TaoToken 控制台的 API Keys 页面创建一个格式通常是sk-开头的一串字符。这个 Key 只显示一次创建后立刻复制保存。第二Base URL。统一用https://taotoken.net/api注意后面拼接路径时是/v1/chat/completions所以完整请求地址是https://taotoken.net/api/v1/chat/completions。很多人在这里踩坑把/api和/v1的顺序搞反导致 404。第三Model ID。截图识别和翻译建议用支持视觉的模型比如glm-5.3-flash这类多模态模型。Model ID 必须和平台文档里列出的完全一致大小写、连字符都不能错写错了会返回model not found。把这三个值记下来后面 CLI 配置和 Agent 注册都要用。我建议你先在模型对话页面手动发一张图测试一下确认 Key 和模型都能用再去配 CLI这样出问题的时候能快速定位是模型侧还是工具侧。注意API Key 不要硬编码进会提交到 Git 的配置文件里。用环境变量或者本地不纳入版本管理的配置文件后面我会给出具体做法。3. 可复制配置CLI 安装与 Agent 工具注册这一节是核心我给你可以直接复制的配置。分三步装 CLI、配模型、注册到 Agent。3.1 安装 ta-cli「拓」的 CLI 部分叫ta-cli。安装方式取决于你的系统macOS 和 Linux 用包管理器或直接下载二进制Windows 建议用 WSL 或者直接下 exe。装完后验证ta-cli --version能打印版本号就说明装好了。如果提示command not found检查二进制是否在 PATH 里或者用绝对路径调用。3.2 配置文件settings.jsonta-cli读取一个 JSON 配置文件默认路径在 macOS/Linux 是~/.config/ta/settings.jsonWindows 是%APPDATA%\ta\settings.json。内容如下{ provider: openai-compatible, base_url: https://taotoken.net/api/v1, api_key: sk-你的Key粘贴在这里, model: glm-5.3-flash, vision_model: glm-5.3-flash, output_dir: ~/Pictures/ta-output, default_action: ocr, timeout_ms: 30000 }几个关键字段说明base_url结尾是/v1因为 SDK 会自己拼/chat/completionsvision_model单独列出来是因为有些场景你可能想用更便宜的模型做 OCR、用更强的模型做识图default_action可以设成ocr、translate、describe决定框选后默认干什么。如果你不想把 Key 写进文件可以用环境变量覆盖export TA_API_KEYsk-你的Key export TA_BASE_URLhttps://taotoken.net/api/v1 export TA_MODELglm-5.3-flash配置文件里对应字段留空即可CLI 会优先读环境变量。3.3 注册到 Agent以 Codex 为例Agent 要调用截图能力本质是把ta-cli注册成一个 tool。不同 Agent 的注册格式不一样但核心三件套永远是Base URL、Key、Model ID。下面给一个通用的 tool 定义你可以按自己 Agent 的 schema 调整{ name: take_screenshot, description: 截取屏幕区域并返回图片路径或识别文本用于自动化流程中获取视觉信息, parameters: { type: object, properties: { mode: { type: string, enum: [region, fullscreen, window], description: 截图模式 }, action: { type: string, enum: [save, ocr, translate, describe], description: 截图后执行的动作 }, annotate: { type: boolean, description: 是否自动标注重点 } }, required: [mode, action] }, command: ta-cli capture --mode {{mode}} --action {{action}} --annotate {{annotate}} --json }注意最后的--json它让 CLI 输出结构化 JSONAgent 解析起来不会因为多了一行日志就崩。返回格式大概是这样{ success: true, image_path: /Users/you/Pictures/ta-output/20250101-120000.png, text: 识别出来的文字内容, model: glm-5.3-flash, elapsed_ms: 2140 }如果你用的是 Cline 这类支持 MCP 的客户端可以把ta-cli包一层 MCP server把上面的 tool 定义暴露成 MCP tool。Cline MCP 的配置里同样要写全 Base URL、Key、Model ID 三件套缺一个都会在调用时报认证或模型错误。4. 验证请求确认截图和识别真的跑通了配置写完不代表能用必须做验证。我按从简到繁给你四个验证动作每个都有明确的成功标志。第一个验证纯截图不调模型。运行ta-cli capture --mode region --action save --json框选一块区域如果返回的 JSON 里success是 trueimage_path指向的文件确实存在且能打开说明截图链路没问题。这一步不涉及网络失败基本是权限问题。第二个验证OCR 识别。运行ta-cli capture --mode region --action ocr --json框选一段有文字的界面成功的话text字段会包含识别结果elapsed_ms通常在 2000 到 3000 之间。如果text为空但success是 true可能是框选区域没文字或者模型没返回内容看下一节的排查。第三个验证翻译。运行ta-cli capture --mode region --action translate --json框选一段英文text字段应该返回中文译文。这一步同时验证了多模态输入和模型的语言能力。第四个验证Agent 端到端。在你的 Agent 里触发take_screenshot让它截一张图并描述内容。成功标志是 Agent 能拿到image_path并继续后续推理而不是卡在工具调用或者报解析错误。我建议把这四个验证做成一个脚本每次改配置后跑一遍能省掉大量「改了哪里忘了」的排查时间。#!/bin/bash set -e echo 1. 截图测试 ta-cli capture --mode fullscreen --action save --json | jq .success echo 2. OCR 测试 ta-cli capture --mode fullscreen --action ocr --json | jq .text echo 3. 翻译测试 ta-cli capture --mode fullscreen --action translate --json | jq .text echo 全部通过用jq提取字段输出干净适合放进 CI 或者 pre-commit 钩子。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节列的都是真实会撞上的报错我按错误信息给你对照解法。401 Unauthorized。最常见九成是 Key 问题。检查三件事Key 有没有复制完整前后不能有空格、Key 有没有过期或被删、请求头里Authorization: Bearer sk-xxx格式对不对。如果你用环境变量确认TA_API_KEY真的被 export 了可以在终端echo $TA_API_KEY看一眼。还有一种情况是 Base URL 写成了https://taotoken.net/api但 SDK 又自己拼了一次/api变成/api/api/v1这种会返回 404 而不是 401但表现类似一起检查。local proxy failed。这个报错通常出现在你本机配了系统级代理但 CLI 走的是直连或者反过来。解法是检查环境变量HTTP_PROXY、HTTPS_PROXY、ALL_PROXY有没有被设置成不可用的地址。临时清掉再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY ta-cli capture --mode region --action ocr --json如果清了就正常说明是代理配置冲突去你的 shell 配置文件里把相关行注释掉。Error reading choices[0].message.content或者类似reading choices的报错。这是响应结构不符合预期通常是模型返回了错误对象而不是正常 completion。原因可能是Model ID 写错导致平台返回错误 JSON、请求体里messages格式不对、或者图片 base64 太大被截断。先看原始响应ta-cli capture --mode region --action ocr --json --debug--debug会打印完整请求和响应对着看error字段写了什么。如果是model not found改 Model ID如果是image too large降低截图分辨率或者压缩后再传。OAuth 相关报错。如果你在 Codex 或 Claude Code 这类工具里看到 OAuth 失败注意走 API Key 接入时不应该触发 OAuth 流程。出现 OAuth 报错说明工具还在用账号登录模式没切到 API Key 模式。检查你的auth.jsonCodex 的配置在~/.codex/auth.json里是不是还留着旧的登录态把它清掉改成 API Key 字段。Codex 的auth.json结构大致是{ api_key: sk-你的Key, base_url: https://taotoken.net/api/v1, model: glm-5.3-flash }三件套齐全OAuth 报错就会消失。截图权限报错。macOS 上第一次运行会弹权限申请如果你点了拒绝后面所有截图都会返回空图或者黑图。去「系统设置 → 隐私与安全性 → 屏幕录制」里把终端或者 ta-cli 勾上重启终端再试。中文乱码。OCR 返回的text里中文变成问号通常是终端编码问题不是模型问题。设置export LANGen_US.UTF-8或者zh_CN.UTF-8再跑。6. 把截图能力真正嵌进你的工作流到这里CLI 装好了、模型配通了、Agent 注册完了、错误也能自己排查了。剩下的是怎么把它用出价值。我的做法是给常用场景各写一个封装脚本。比如「截报错并让 Agent 分析」ta-cli capture --mode region --action ocr --json | jq -r .text | your-agent-cli analyze比如「截界面并翻译成中文存到剪贴板」ta-cli capture --mode region --action translate --json | jq -r .text | pbcopy再比如「批量截图做文档」for i in 1 2 3; do ta-cli capture --mode window --action save --annotate true --json sleep 1 done这些脚本才是把工具变成生产力的关键。工具本身只是能力封装才是工作流。如果你要长期跑 Agent 任务比如让 Agent 自动做 UI 测试、自动生成带截图的报告建议用 Coding Plan 这类长期编码方案来管理模型调用配额比按次调用更划算也更适合高频场景。最后提醒一句截图涉及屏幕内容如果屏幕上有敏感信息OCR 和识图会把内容发到模型侧。生产环境用之前确认你的数据合规要求必要时对截图区域做脱敏或者用本地模型处理敏感场景。工具是死的怎么用是活的。