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.json

ta-cli读取一个 JSON 配置文件，默认路径在 macOS/Linux 是~/.config/ta/settings.json，Windows 是%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/completions；vision_model单独列出来，是因为有些场景你可能想用更便宜的模型做 OCR、用更强的模型做识图；default_action可以设成ocr、translate、describe，决定框选后默认干什么。

如果你不想把 Key 写进文件，可以用环境变量覆盖：

export TA_API_KEY="sk-你的Key" export TA_BASE_URL="https://taotoken.net/api/v1" export TA_MODEL="glm-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 输出结构化 JSON，Agent 解析起来不会因为多了一行日志就崩。返回格式大概是这样：

{ "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是 true，image_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.json（Codex 的配置在~/.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 LANG=en_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 和识图会把内容发到模型侧。生产环境用之前，确认你的数据合规要求，必要时对截图区域做脱敏，或者用本地模型处理敏感场景。工具是死的，怎么用是活的。