1. 先复现agent-vision-toolkit OCR 在 Codex 里“静默无输出”的现场这次排障的起点是 TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentocr-debug-intro。场景很具体你用 Codex 或 DeepSeek agent 做文本推理agent-vision-toolkit 负责把长截图 OCR 成文字文本模型本身看不了图所以它必须先让 shell 调用 OCR 工具再把 OCR 结果当成文本读进去。结果你让 agent “识别这张报错截图”它回复了一句“已处理”但聊天里没有 OCR 文本shell 日志里也没有 stdoutecho $?却是 0。更迷惑的是TaoToken 侧的文本推理请求正常计费说明 agent 并没有完全挂掉只是视觉工具那一段像被吞掉了。先把 Key 和 Base URL 对齐去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentocr-debug-key 拿到YOUR_API_KEY然后把文本推理的 Base URL 填为https://taotoken.net/api。注意OCR 本身通常不消耗模型 Token消耗 Token 的是 Codex/DeepSeek agent 的文本推理它要判断“现在该不该调用 OCR”要读 OCR 返回的文字还要继续推理报错原因。所以 OCR 没输出不一定是模型坏了很可能是 harness 没有真正把图片路由到 OCR 工具。先做最小复现不要一上来就重装 agent-vision-toolkit。准备一张长截图mkdir -p fixtures # 把你的报错长截图放到 fixtures/error-long.png ls -lh fixtures/error-long.png下文用$AVT_OCR指代你在 agent-vision-toolkit 仓库里实际使用的 OCR 入口。它可能是python -m ...、uv run ...也可能是打包后的命令。先把它解析成绝对路径避免 agent 工作目录漂移export AVT_OCR$(command -v your-ocr-entry || true) if [ -z $AVT_OCR ]; then echo OCR 入口不在 PATH先把 agent-vision-toolkit 的 OCR CLI 路径填进来 export AVT_OCR/absolute/path/to/agent-vision-toolkit/ocr-entry fi $AVT_OCR --help | head -40错误复现通常长这样$ export TAOTOKEN_API_KEYYOUR_API_KEY $ export OPENAI_BASE_URLhttps://taotoken.net/api $ $AVT_OCR --image fixtures/error-long.png $ echo $? 0没有任何文本输出退出码还是 0。这并不代表 OCR 成功只代表脚本没有抛异常。你需要把 stderr 和 debug 日志一起抓出来$AVT_OCR --image fixtures/error-long.png --debug 21 | tee ocr-debug.log wc -c ocr-debug.log如果ocr-debug.log也是空的问题大概率在更上层agent 根本没调用 OCR或者 shell 调用被沙箱拦了。接下来看 agent 侧日志codex --config ~/.codex/config.toml --log-level debug 21 | tee codex-ocr.log grep -n -E tool_call|shell|ocr|stderr|exit_code codex-ocr.log | tail -80如果日志里没有tool_call说明文本模型只是“口头答应”并没有发起工具调用。如果日志里有tool_call但stdout_bytes0、stderr_bytes0说明命令执行了但没有产出。如果exit_code127那就是 PATH 或命令名不对。排障要分层不要把所有问题都归因于模型。2. 把文本推理切到 TaoTokenCodex config.toml 与 CC Switch 三件套OCR 工具是本地 shell 能力但 agent 的“判断、读结果、继续推理”走的是文本模型。为了让 Codex 稳定调用工具先把文本推理接好。进入 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentocr-debug-models 确认可用模型名然后编辑~/.codex/config.tomlmodel gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses环境变量这样加export TAOTOKEN_API_KEYYOUR_API_KEY # 有些工具会读 OPENAI_BASE_URLCodex 以 config.toml 的 base_url 为准 export OPENAI_BASE_URLhttps://taotoken.net/api验证文本推理是否通codex exec 只输出两个字符OK如果这里返回 401、404、模型不存在或者一直空回复先修模型配置。因为 agent 连“要不要调用 OCR”这一步都完不成后面的 OCR 工具自然没有输出。如果你用 CC Switch 做多配置切换要同步三件套Base URL 填https://taotoken.net/apiAPI Key 填YOUR_API_KEY模型名填你实际可用的模型。三件套任意一个不一致都会出现“看起来切换了实际还在旧端点”的假象。尤其注意Codex 用config.toml和TAOTOKEN_API_KEY不要把 Claude Code 的ANTHROPIC_*变量套到 Codex 上两套配置混用最常见的表现就是文本推理请求发错端点agent 直接静默失败。切换完成后再跑一次最小文本调用保存日志codex exec 请用一句话说明当你看到 .png 文件时应该先调用 OCR 工具而不是直接读取二进制。 | tee text-route.log这一步不是形式主义。它验证了模型能接收“图片要路由到 OCR”的指令。很多 OCR 没输出的根因不在 OCR 引擎而在文本模型没有把图片路径当成工具调用参数。3. OCR 工具没输出的根因树从 shell 调用、PATH、skill 判据到长图分片排 OCR 没输出建议按下面顺序查不要跳步。第一层agent 是否真的发起了 shell 调用。看codex-ocr.log里有没有类似tool_call shell: $AVT_OCR --image /abs/path/fixtures/error-long.png --lang chi_simeng tool_result exit_code0 stdout_bytes0 stderr_bytes0如果只有 assistant 的自然语言没有tool_call说明 skill 判据没命中。纯文本模型看不到图片像素如果你只是在对话里说“看这张图”agent 可能把它当成普通附件直接跳过。修复方式是把图片绝对路径作为文本传进去请对 /home/dev/project/fixtures/error-long.png 调用 OCR 工具输出完整文字不要总结。第二层shell 是否被沙箱拦截。典型日志command not found: your-ocr-entry permission denied: /absolute/path/to/ocr-entry解决办法是给绝对路径、确认可执行权限并把 OCR 入口所在目录加入 PATHchmod x $AVT_OCR export PATH$(dirname $AVT_OCR):$PATH $AVT_OCR --version第三层OCR 依赖是否完整。长截图 OCR 常见依赖包括 tesseract 二进制、语言包、Python 图像库。验证命令which tesseract tesseract --list-langs python -c import pytesseract, PIL; print(python deps ok)如果tesseract --list-langs没有chi_sim中文截图 OCR 会输出空文本或乱码。安装语言包后重试sudo apt-get install -y tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng第四层长图是否超过默认限制。长截图高度可能上万像素某些 OCR 实现会静默失败或者只处理第一屏。加 debug 参数观察图片尺寸和分片数量$AVT_OCR --image fixtures/error-long.png --debug --lang chi_simeng 21 | tee ocr-long.log grep -E size|chunk|height|timeout|memory ocr-long.log第五层输出是否被 harness 吞掉。有些 OCR 脚本把结果写到文件stdout 只打印“done”。agent 读到的是“done”自然没有文字。修复方式是在 skill 或包装脚本里强制 stdout 输出 OCR 正文同时保留文件路径$AVT_OCR --image $IMG --lang chi_simeng --format txt 21第六层图片路径是否在工作目录之外。agent 的工作目录和你的终端不一定相同。统一用realpathIMG$(realpath fixtures/error-long.png) $AVT_OCR --image $IMG --lang chi_simeng --format txt第七层skill 是否要求 agent“先判断再调用”。如果 skill 写得含糊比如“需要时使用视觉工具”模型可能认为“不需要”。把触发条件写死遇到.png/.jpg/.jpeg/.webp路径、遇到“截图/报错图/设计图”关键词、遇到用户要求 OCR都必须先调用 OCR再把结果读回来。4. 修复后配置让 Codex/DeepSeek agent 稳定触发 OCR 的 shell 包装最稳的做法是不要直接让 agent 拼 OCR 命令而是给它一个固定包装脚本。创建scripts/agent_ocr.sh#!/usr/bin/env bash set -euo pipefail IMG${1:?usage: agent_ocr.sh image [lang]} LANG_OPT${2:-chi_simeng} AVT_OCR${AVT_OCR:?请先 export AVT_OCR/abs/path/to/ocr-entry} if [ ! -f $IMG ]; then echo [agent_ocr] file not found: $IMG 2 exit 2 fi ABS_IMG$(realpath $IMG) echo [agent_ocr] image$ABS_IMG lang$LANG_OPT 2 # 关键stdout 只给正文stderr 给诊断方便 agent 读正文 $AVT_OCR --image $ABS_IMG --lang $LANG_OPT --format txt赋予执行权限并验证chmod x scripts/agent_ocr.sh export AVT_OCR/absolute/path/to/agent-vision-toolkit/ocr-entry ./scripts/agent_ocr.sh fixtures/error-long.png chi_simeng | tee ocr-fixed.txt wc -c ocr-fixed.txt修复后的日志应该能看到正文长度[agent_ocr] image/home/dev/project/fixtures/error-long.png langchi_simeng [avt-ocr] enginetesseract 5.3.0 [avt-ocr] chunks7 chars7462 elapsed18.4s Traceback (most recent call last): File app.py, line 42, in module raise RuntimeError(missing DATABASE_URL) RuntimeError: missing DATABASE_URL注意上面Traceback是截图里的报错内容不是你的脚本报错。区分这一点很重要否则你会把 OCR 成功识别出的报错误判成 OCR 失败。然后在 Codex 侧固定调用方式。可以在项目根目录放一个CLAUDE.md或 skill 说明明确要求遇到图片路径时必须执行 scripts/agent_ocr.sh absolute-image-path chi_simeng 再把 stdout 原文读入上下文禁止只回复“已处理”。 如果 exit_code 非 0先输出 stderr 前 80 行再决定是否重试。再跑一次 agent 任务codex exec 请读取 fixtures/error-long.png 里的报错用三行总结原因。必须调用 scripts/agent_ocr.sh。如果模型配置正确、skill 判据明确、包装脚本 stdout 干净agent 端日志会出现tool_call shell: scripts/agent_ocr.sh /home/dev/project/fixtures/error-long.png chi_simeng tool_result exit_code0 stdout_bytes7462 assistant: 截图中的关键报错是缺少 DATABASE_URL应用启动时读取环境变量失败...到这一步OCR 没输出的问题才算真正闭环不是“模型突然会看图了”而是 harness 把图片转成文本文本模型继续做推理。5. 长截图 OCR 的稳定化分片、超时、日志与最小回归长截图是 OCR 没输出的高发区。很多脚本在处理小图时正常一遇到高度 8000px 以上的截图就静默返回空。解决思路是分片 OCR再按顺序合并。下面是一个不依赖特定 OCR 实现的 Python 分片脚本from pathlib import Path from PIL import Image import subprocess import os import sys IMAGE Path(sys.argv[1]).resolve() OUT Path(ocr-merged.txt).resolve() CHUNK_H 1800 OVERLAP 120 AVT_OCR os.environ[AVT_OCR] img Image.open(IMAGE) w, h img.size chunks [] top 0 idx 0 while top h: bottom min(top CHUNK_H, h) chunk_path IMAGE.with_name(f{IMAGE.stem}.chunk-{idx:03d}.png) img.crop((0, top, w, bottom)).save(chunk_path) chunks.append(chunk_path) if bottom h: break top bottom - OVERLAP idx 1 with OUT.open(w, encodingutf-8) as out: for chunk in chunks: out.write(f\n {chunk.name} \n) proc subprocess.run( [AVT_OCR, --image, str(chunk), --lang, chi_simeng, --format, txt], capture_outputTrue, textTrue, timeout120, ) out.write(proc.stdout) if proc.returncode ! 0: out.write(f\n[stderr]\n{proc.stderr}\n) chunk.unlink(missing_okTrue) print(fmerged - {OUT} chars{OUT.stat().st_size})运行export AVT_OCR/absolute/path/to/agent-vision-toolkit/ocr-entry python scripts/ocr_long.py fixtures/error-long.png wc -c ocr-merged.txt分片时注意三点每片高度不要超过 OCR 引擎舒适区片与片之间留重叠避免行被切断每片设置超时避免某一片卡死导致整体无输出。最小回归用例也很重要找一张包含固定错误码的长截图比如E_CONN_REFUSED_104每次修复后都要求输出必须包含这个字符串。这样你就能区分“OCR 完全没跑”和“OCR 跑了但识别质量差”。如果你在 Codex 或 DeepSeek agent 里执行建议把分片和合并也封装成一条 shell 命令让模型只负责读合并后的文本python scripts/ocr_long.py fixtures/error-long.png sed -n 1,120p ocr-merged.txt6. 把 OCR 工作流接到 Claude Codesettings.json 与 ANTHROPIC_* 不串到 Codex如果你同时用 Claude Code 做 agent 排障配置方式不同。Claude Code 走settings.json和ANTHROPIC_*不要把这套变量复制到 Codex 的config.toml场景里。示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5 } }保存后验证claude -p 只输出 OK然后在 Claude Code 项目说明里加入 OCR 路由规则当用户提供 .png/.jpg/.jpeg/.webp 路径或提到“截图/OCR/报错图”必须先执行 scripts/agent_ocr.sh absolute-path chi_simeng 读取 stdout 后再回答。若 stdout 为空执行 scripts/agent_ocr.sh absolute-path chi_simeng 21 | tail -80 并把 stderr 原文贴出来。Claude Code 侧的常见坑和 Codex 类似只给相对路径、沙箱不允许执行脚本、AVT_OCR环境变量没继承、TESSDATA_PREFIX没设置。可以显式检查echo $ANTHROPIC_BASE_URL echo $AVT_OCR echo $TESSDATA_PREFIX如果 Base URL 不是https://taotoken.net/api或者 Key 还是旧值先修配置。Claude Code 文档入口放在文末 CTA需要时按官方文档对齐字段名。7. 成本与边界文本推理走 TaoTokenOCR 本地跑不要把图片硬塞给文本模型agent-vision-toolkit 这类工具的价值不是让纯文本模型突然拥有像素级视觉而是把“看图”拆成两步本地 OCR/UI 工具先把图片转成结构化文本文本模型再读文本。这样做有两个直接好处第一文本推理可以继续走 Codex/DeepSeek 这类成本更可控的模型第二图片不必上传到模型侧OCR 在本地 shell 完成适合私有化或敏感截图场景。边界也要说清楚OCR 对“报错文字、日志、聊天记录、设计图标注”这类结构化信息很有效但“这个配色好不好看”“这个图标有没有设计感”这类审美判断工具替代不了原生多模态模型。你的排障目标如果是“让 agent 读出截图里的报错并继续推理”那 OCR 工具足够如果是“让 agent 理解复杂视觉语义”就要换模型或补多模态能力。回到本次排障OCR 没输出时不要先怀疑模型能力。按顺序查 agent 是否发起 tool_call、shell 是否执行、OCR 依赖是否完整、长图是否分片、stdout 是否被吞、路径是否为绝对路径。修复后保留三样东西错误复现的ocr-debug.log、修复后的ocr-fixed.txt、以及 Codex/Claude Code 的最终配置。下次再遇到“OCR 静默无输出”直接拿最小回归用例跑一遍。8. 文末 CTA模型对话 → Coding Plan → 创建 Key → Claude Code 文档如果你还没把文本推理接好建议按下面路径走一遍先试模型对话确认文本推理可用https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentocr-cta-chat需要长期跑 agent 排障看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentocr-cta-plan创建并管理 Key把YOUR_API_KEY换成真实值https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentocr-cta-keyClaude Code 配置细节看官方文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentocr-cta-claude最后再强调一次配置要点Codex 用config.tomlTAOTOKEN_API_KEYClaude Code 用settings.jsonANTHROPIC_*两者不要混用Base URL 统一填https://taotoken.net/api不要带 UTMKey 占位符用YOUR_API_KEY。把 OCR 工具包装成固定脚本强制 stdout 输出正文长截图先分片agent 端日志留档。这样再遇到 agent-vision-toolkit 的 OCR 工具没输出你就能在十分钟内定位到是模型路由、shell 调用、依赖缺失还是长图分片问题而不是反复重装工具。