1. 为什么要在 Claude Code 里接一个视觉模型Claude Code 这个终端里的编码助手从发布到现在绝大多数人拿它干的事都停留在读代码、改 bug、写脚本这一层。它本质上是一个能调用工具、能读写本地文件的 Agent 框架模型只是它背后的大脑。既然大脑可以换那就有意思了——如果换上一个能看图的大脑这个终端工具立刻就能变成一个视觉 Agent能读截图、能看 UI 稿、能分析图表、能对着报错截图直接定位问题。GLM-4.1V-Thinking 就是这么一个带视觉理解能力、并且支持思考链的模型。它和纯文本模型最大的区别在于输入里可以塞图片输出前会先走一段推理。把这种模型接到 Claude Code 的 Agent 循环里理论上就能复现出给一张界面截图让它自己分析布局、找出问题、甚至生成修复代码的完整链路。但这里有个现实问题Claude Code 默认只认 Anthropic 自家的接口格式而 GLM 系列走的是另一套 API 规范。直接改配置是接不上的中间必须有一个协议转换层。TaoToken 这类中转服务扮演的就是这个角色——它对外暴露一个兼容 Anthropic 消息格式的端点对内把请求翻译成目标模型能听懂的格式再把结果翻译回来。这样 Claude Code 完全感知不到背后换了模型照常发请求就行。这篇内容适合三类人看一是已经在用 Claude Code、想把它从文本助手升级成视觉 Agent的开发者二是手上有 GLM 系列 API、想找个趁手客户端来跑评测的人三是单纯想搞清楚协议转换层到底在干什么的技术好奇者。我会把配置过程、踩坑点、评测方法、以及实测下来的效果边界都讲清楚尽量让你照着做就能复现。需要提前说明的是视觉 Agent 评测这件事难点从来不在能不能跑起来而在跑起来之后怎么判断它到底行不行。所以后半段我会花不少篇幅讲评测集怎么设计、指标怎么看、哪些结果是模型能力问题、哪些其实是工程配置问题。2. 把链路拆开看Claude Code、中转层、GLM 各自负责什么2.1 Claude Code 的 Agent 循环到底在做什么很多人把 Claude Code 当成一个命令行版的聊天框这个理解其实偏了。它真正的价值在于那个 Agent 循环接收你的自然语言指令决定要不要调用工具读文件、写文件、执行命令、搜索拿到工具返回结果后继续推理直到任务完成或需要你介入。这个循环对模型的要求有三个第一能稳定输出结构化的工具调用意图第二能在多轮里记住上下文第三能处理比较长的输入。Claude Code 的提示词和工具定义都是围绕 Anthropic 的消息格式设计的包括system、messages、tools这些字段的结构以及工具调用结果的回传方式。所以当你换模型时真正要保证的不是模型能聊天而是模型能在这个特定格式下稳定地做工具调用。这一点非常关键后面评测部分会反复提到。2.2 中转层解决的其实是方言问题Anthropic 的 Messages API 和 OpenAI 风格的 Chat Completions API虽然都是发消息、收回复但字段结构差别不小。举几个具体的维度Anthropic Messages 格式OpenAI Chat Completions 格式系统提示独立的system字段放在messages里 role 为 system图片输入content 数组里 type 为 imagebase64 或 urlcontent 数组里 type 为 image_url工具调用tool_use/tool_result块tool_calls字段 role 为 tool 的消息停止原因stop_reasonfinish_reason流式事件细粒度事件类型统一的 delta 结构中转层的活儿就是在这两套方言之间做双向翻译。你发给它的请求是 Anthropic 格式它拆开、重组成目标模型认识的格式发出去拿到回复后再拼回 Anthropic 格式还给你。Claude Code 全程无感。这里有个容易被忽略的点翻译不是无损的。比如 Anthropic 的tool_use块和 OpenAI 的tool_calls在语义上接近但不完全等价尤其是并行工具调用、工具调用和文本混排的场景翻译层处理不好就会出现工具调用丢失或者参数被截断的问题。这也是为什么有些中转服务跑纯文本没问题一上工具调用就翻车。2.3 GLM-4.1V-Thinking 的视觉能力边界GLM-4.1V-Thinking 这个名字里V是视觉Thinking是推理。它接收图片的方式是把图片编码进 content 数组和文本混在一起。实际用下来它对以下几类图片处理得比较稳界面截图能识别按钮、输入框、列表这些常见控件能描述布局代码截图能读出代码内容但长代码容易漏行图表柱状图、折线图能读出大致趋势精确数值经常出错报错截图能提取错误信息但堆栈很长的会截断Thinking这部分意味着它在给出最终答案前会先输出一段推理过程。这在 Agent 场景下是双刃剑好处是复杂任务的成功率更高坏处是延迟明显增加而且推理内容会占用输出 token。评测的时候要把这部分单独考虑不能和最终答案混在一起算。2.4 三者拼起来的数据流把链路串起来一次完整的视觉 Agent 调用是这样的你在 Claude Code 里输入指令比如看一下这张截图里的界面有什么问题Claude Code 把指令和图片路径打包成 Anthropic 格式请求发往配置好的 base_url中转层收到请求把 Anthropic 格式翻译成目标模型格式转发给 GLMGLM 处理图片和文本输出推理过程加最终答案中转层把结果翻译回 Anthropic 格式返回给 Claude CodeClaude Code 解析回复如果里面有工具调用就执行然后回到第 2 步理解这条链路之后出问题时你就能快速定位是哪一环的锅是 Claude Code 配置错了是中转层翻译丢了东西还是模型本身没理解图片。3. 环境准备与配置从零把链路搭起来3.1 安装 Claude Code 与前置检查Claude Code 的安装方式取决于你的系统。Node 环境下最省事的是全局安装npm install -g anthropic-ai/claude-code装完之后先别急着配模型跑一下claude --version确认能正常输出版本号。如果这一步就报错大概率是 Node 版本太低建议 18 以上。Windows 用户如果用的是 WSL注意路径问题。Claude Code 在 WSL 里跑但你的项目文件如果在 Windows 盘符下访问路径是/mnt/c/...这种形式配置里写路径的时候要对应上。我见过不少人卡在这里以为是模型配置问题其实是路径根本没找对。还有一个前置检查容易被跳过确认你的终端能正常访问外网 API 端点。有些公司内网环境会拦截非标准端口的请求配置全对但请求发不出去报错信息又很含糊。先用curl手动打一下中转服务的健康检查接口能通再往下走。3.2 中转服务的接入信息怎么拿TaoToken 这类服务通常给你两样东西一个 base_url 和一个 API key。base_url 是请求的入口地址API key 是身份凭证。这两样都要保管好尤其是 key泄露了别人就能拿你的额度。拿到之后建议先做一次最小验证别直接塞进 Claude Code 里试。用 curl 打一个最简单的请求curl -X POST 你的base_url/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的key \ -H anthropic-version: 2023-06-01 \ -d { model: glm-4.1v-thinking, max_tokens: 256, messages: [{role: user, content: 你好}] }能返回正常内容说明中转层和模型都通了。这一步的价值在于把配置问题和模型问题隔离开——如果 curl 都不通那后面 Claude Code 里怎么调都是白搭。注意不同中转服务对模型名的写法要求不一样有的要带前缀有的要全小写。拿不准就先看服务商给的文档或者用最保守的写法试。3.3 让 Claude Code 指向自定义端点Claude Code 通过环境变量来指定后端。核心是这几个export ANTHROPIC_BASE_URL你的中转服务base_url export ANTHROPIC_API_KEY你的key export ANTHROPIC_MODELglm-4.1v-thinking如果你想让配置持久化写进~/.bashrc或~/.zshrc。但我不建议一上来就写死先在当前终端会话里 export测通了再持久化不然配错了每次开终端都受影响。这里有个细节Claude Code 有些版本会校验模型名是否在它认识的列表里。如果它不认glm-4.1v-thinking这个名字可能会在启动时警告或者直接拒绝。遇到这种情况可以试试用中转服务提供的别名或者看服务商有没有专门为 Claude Code 适配的模型名。配置完之后启动claude随便问一句看它能不能正常回复。能回复就说明文本链路通了接下来才是视觉部分。3.4 图片输入在 Claude Code 里怎么触发这是整个配置里最容易被误解的一环。Claude Code 本身对贴图的支持方式和网页版聊天不一样。在终端里你没法直接 CtrlV 粘贴图片通常的做法是把图片存到项目目录下然后在指令里给出文件路径让 Claude Code 用读文件工具去读这个图片但这里有个前提模型得支持图片输入而且中转层得正确地把图片数据翻译过去。如果中转层只处理文本那图片路径传过去也只会被当成普通文本模型根本看不到图。所以验证视觉能力的第一步是确认你的中转服务确实支持图片透传。方法还是用 curl构造一个带图片的请求curl -X POST 你的base_url/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的key \ -H anthropic-version: 2023-06-01 \ -d { model: glm-4.1v-thinking, max_tokens: 512, messages: [{ role: user, content: [ {type: text, text: 描述这张图}, {type: image, source: {type: base64, media_type: image/png, data: 你的base64}} ] }] }如果返回的描述和图片内容对得上说明视觉链路是通的。对不上或者报错那就是中转层没处理图片字段得换服务或者找服务商确认。4. 评测集设计怎么判断视觉 Agent 到底行不行4.1 为什么不能只用随便找张图试试跑通链路之后很多人会随手截个图丢进去看模型答得对不对然后凭感觉下结论。这种做法的问题在于单张图的结果随机性太大模型这次答对了不代表稳定答错了也不代表能力不行可能只是这张图恰好踩到了它的盲区。要做靠谱的评测得有结构化的评测集。评测集的设计要围绕你想验证什么能力来展开而不是随便凑一堆图。对视觉 Agent 来说至少要覆盖这几类任务界面理解给一张 App 或网页截图让它描述布局、找出可交互元素代码识别给一张代码截图让它复述代码或找出语法问题图表读取给一张数据图表让它读出趋势或具体数值错误诊断给一张报错截图让它提取错误信息并给出排查方向多图对比给两张相似截图让它找出差异每类任务准备 10 到 20 个样本样本之间要有难度梯度。这样跑下来你才能看出模型在哪个能力维度上强、哪个维度上弱。4.2 评测样本的构造要点构造样本时有几个坑要避开。第一图片分辨率别太高也别太低。太高的图模型可能直接压缩细节丢失太低的图连人都看不清测不出真实能力。建议控制在 1024 到 2048 像素这个区间。第二任务指令要明确。别写看看这张图要写这张图是一个登录界面请列出所有输入框和按钮并说明它们的用途。指令越具体评测结果越可复现。第三要准备标准答案。没有标准答案你只能凭感觉判断对错评测就失去了意义。标准答案不用特别精细但关键信息点要列出来比如图中有 3 个输入框、2 个按钮、1 个验证码区域。第四控制变量。同一批评测里图片格式、尺寸、指令风格尽量统一不然你分不清结果差异是来自模型还是来自输入本身。4.3 评测指标怎么定视觉 Agent 的评测指标不能只看答对没答对要拆细一点指标含义怎么算任务完成率最终答案是否满足任务要求人工判定通过/不通过关键信息召回标准答案里的关键点被提到了多少命中数 / 总关键点数幻觉率答案里编造了图中不存在的内容编造点数 / 总输出点数平均延迟从发请求到收到完整回复的时间多次取平均工具调用成功率Agent 循环里工具调用是否被正确触发成功次数 / 总调用次数其中幻觉率特别值得关注。视觉模型很容易看图说话把没看到的东西脑补出来。在 Agent 场景下幻觉会导致它基于错误信息做决策后果比纯文本场景更严重。4.4 用 Claude Code 跑评测的实际操作把评测跑起来最直接的方式是写一个脚本批量调用中转服务的接口把结果存下来再人工核对。但既然我们用的是 Claude Code也可以让它自己来跑——把评测样本和指令整理成文件让 Claude Code 逐个处理。不过要注意Claude Code 的 Agent 循环会引入额外变量。它可能会自己决定去读别的文件、执行别的命令这些行为会干扰评测。所以跑评测时最好把工作目录清空只放评测需要的图片和指令文件减少干扰。实测下来用 Claude Code 跑评测的效率比手写脚本高因为它的工具调用能力可以自动处理读图、分析、记录结果这一整套流程。但代价是每次调用都走完整的 Agent 循环token 消耗比直接调 API 大不少。如果评测集很大建议还是写脚本直接打接口Claude Code 用来做抽样验证。5. 实测中暴露的问题与排查链路5.1 图片传过去了但模型说看不到这是最常见的问题。现象是请求返回 200模型也回复了但回复内容明显没基于图片比如我无法查看图片或者答非所问。排查链路是这样的先确认 curl 直接打接口时图片能不能被识别。如果 curl 能识别、Claude Code 里不能那问题在 Claude Code 这一侧——很可能是它没有把图片正确编码进请求。这时候要检查你的指令是不是明确让模型去读图片文件以及中转层有没有正确解析 Claude Code 发出的图片字段。如果 curl 也不能识别那就是中转层的问题。有些中转服务对图片字段的处理是选择性支持的文本透传没问题图片直接丢弃。这种情况只能换服务或者找服务商确认图片支持情况。5.2 工具调用在视觉任务里频繁失败纯文本场景下工具调用正常一加图片就开始出问题这个现象很典型。原因通常是中转层在翻译工具调用时没有正确处理图片 工具调用混合的 content 数组。Anthropic 格式里一条消息的 content 可以是多个块的数组里面既有 text 又有 image 又有 tool_use。翻译层如果只处理了 text 和 tool_use把 image 块丢了模型就看不到图如果处理顺序错了工具调用的参数可能被截断。排查方法是把中转层返回的原始响应打出来看。如果响应里工具调用的参数不完整或者 content 块的数量对不上那就是翻译层的问题。这种问题一般用户改不了只能反馈给服务商或者换服务。5.3 长上下文下的性能衰减GLM-4.1V-Thinking 支持很长的上下文但实测下来当对话轮次变多、图片累积变多时模型的表现会明显下降。具体表现是前面几轮还能准确描述图片到后面就开始混淆不同图片的内容或者干脆忽略新传入的图片。这不是模型独有的问题长上下文场景下几乎所有模型都有类似的衰减。应对办法有两个一是控制单次会话的图片数量别一次塞太多二是及时清理上下文把已经处理完的图片从对话历史里移除。在 Claude Code 里可以通过开新会话的方式来清理上下文。如果任务需要连续处理多张图建议分批处理每批之间重启会话。5.4 延迟高到影响使用体验带 Thinking 的模型延迟本来就高加上中转层的翻译开销一次请求等十几秒是常事。如果图片还大等半分钟也不奇怪。优化方向有几个一是压缩图片在保证可读的前提下把分辨率降下来二是减少 max_tokens别让它输出太长的推理过程三是如果中转服务支持流式输出一定要开启至少能让用户看到进度而不是干等。实测下来把图片压到 1024 宽、max_tokens 控制在 1024 以内单次请求的延迟能压到可接受的范围。再低就会影响识别准确率了不建议继续压。6. 视觉 Agent 评测的几条实操心得6.1 评测前先固定住工程变量我踩过的最大的坑是在评测过程中改了配置。第一次跑的时候用的是 A 配置跑了一半觉得延迟太高换成了 B 配置结果前后两批结果没法对比整个评测白做。所以评测开始前把所有工程变量都固定住模型名、max_tokens、图片尺寸、指令模板、中转服务版本。中途不要改任何东西要改就整批重跑。这个原则听起来简单但实际执行时很容易因为就改一个小地方而破坏评测的一致性。6.2 把模型能力和工程问题分开看评测结果差的时候第一反应往往是这模型不行。但实际上相当一部分失败案例是工程问题导致的图片没传过去、工具调用被截断、上下文超限、请求被限流。我的做法是每次评测都同时记录两类信息一类是模型输出一类是原始请求和响应。当结果异常时先看原始请求响应确认工程链路没问题再去判断模型能力。这样能避免把工程问题误判成模型问题也能避免反过来。6.3 小样本快速迭代大样本最终验证评测不用一上来就搞几百个样本。先用 10 到 20 个样本快速跑一轮看看整体趋势发现问题就调整评测集或配置。等小样本稳定了再用大样本做最终验证。小样本阶段重点看的是有没有系统性问题比如某一类任务全军覆没那大概率是评测集设计或者配置有问题。大样本阶段重点看的是稳定性同样的任务多跑几次结果是否一致。6.4 记录失败案例比记录成功案例更有价值成功案例只能告诉你这条路能走通失败案例才能告诉你边界在哪里。每次评测完我都会把失败案例单独整理出来分析失败原因是图片太模糊、是指令有歧义、是模型能力不足、还是工程链路有问题。积累一段时间后你会发现失败案例是有模式的。比如某类图表模型总是读错数值某类界面模型总是漏掉隐藏元素。这些模式就是模型的能力边界也是你后续使用时需要规避的地方。6.5 别忽略成本视觉模型的调用成本比纯文本高因为图片本身要占 token。一张 1024 宽的图编码后可能占几百到上千 token。如果评测集大、每张图还要多轮对话成本会快速累积。我的建议是评测阶段先用小图、短对话把流程跑通确认没问题再上大图、长对话。同时监控 API 调用量设置预算上限避免评测跑飞了才发现账单爆炸。7. 这套方案还能往哪些方向延伸跑通Claude Code 中转层 视觉模型这条链路之后能做的事情其实不止评测。我试过几个延伸方向效果还不错。第一个方向是自动化 UI 走查。把产品截图批量丢进去让 Agent 检查布局是否对齐、文案是否有错别字、控件是否符合规范。这个场景对模型的界面理解能力要求高但对精确数值要求低正好落在视觉模型的舒适区。第二个方向是报错截图自动诊断。把用户反馈的报错截图丢进去让 Agent 提取错误信息、搜索代码库、给出可能的修复方向。这个场景结合了视觉识别和代码理解是 Claude Code 的强项。第三个方向是多模态文档处理。把带图表的文档丢进去让 Agent 提取图表数据、生成文字摘要。这个场景对图表读取的准确率要求高实测下来模型还有提升空间但作为辅助工具已经能用。每个方向的评测方法都不一样但底层的链路是同一套。把链路搭稳、把评测方法摸清剩下的就是针对具体场景调优了。
