工具调用零解析失败,给 Agent 再搭一条 SDK 中转通道
上一篇的 CLI 中转在我机器上跑了两周多,十个 Agent 的请求全走它,没出过事。但这段时间 Agent 的活越来越细,毛病就冒出来了。
CLI 版的工具调用是曲线救国,把工具定义写进对话,让 Claude 按约定格式输出文本,再用正则从文本里往外抠。这条链路有三个环节可能掉链子,Claude 可能不按格式输出,格式可能有微妙偏差,正则可能匹配不上。实测可靠性 95% 上下。日常聊天这个数字够用,可跑自动化,那 5% 就是 5% 的中断,一次解析失败,一个任务卡在半路,排在后面的活全部跟着停。最气人的是这种失败不报错,Claude 老老实实回了话,只是没守格式,正则一无所获,你以为是模型闹脾气,其实是链路天生不稳。
所以我把备份方案也补齐了,SDK 版中转。CLI 版继续当主力,管隐蔽。SDK 版随时待命,管精准。这篇把它拆开,系统提示怎么做到零污染,工具调用怎么做到零解析失败,指纹上欠的账怎么用组合弥补,末尾照例给一份能照抄的部署清单。
系统提示里的五千 token 私货
先解释名词。系统提示就是你在对话前给模型的预设指令,比如「你是一个翻译官,只输出中文」,指令越干净,回答越贴需求。
谁需要在意这件事。只要你是订了 Claude 之后想让 OpenClaw 这样的多 Agent 系统直接调用,而不是再花钱买一份 API 额度,那系统提示就是你的第一笔账。
问题在于 Claude Code 自带一整套默认指令。你通过它中转请求时,它会把这些指令悄悄垫在你的内容前面,我数过,大约 5000 个 token,写的全是「你是 Claude Code,你可以执行命令、读写文件」这类自我介绍,还有遇到权限问题要请求授权、输出格式要守什么规矩等等。你只想让它翻译一句话,它得先读完这一整页履历。
算笔账。十个 Agent 每天调 300 次,每次多读 5000 token,一个月就是 4500 万 token 花在读私货上。钱是订阅包了的,不额外花,但上下文窗口是实打实被挤占的,留给正经内容的空间就少了。像打电话给客服,你只想问一句话,客服每次接通都先背三分钟免责声明。
SDK 版的解法直接,四个配置全部锁死。不加载任何配置文件,不注册任何内置工具,不连接任何外部插件,系统提示完全由你定义。效果是从 5000 token 降到 50 上下,你传什么它读什么,一个字不多。零污染不是功能,是边界,你的指令和它的私货必须泾渭分明。
工具调用,从 95 到 100
这是我补 SDK 版的最大动力。
Agent 让 Claude 搜新闻、查数据、发消息,Claude 得返回一条格式标准的结构化指令,程序才能解析执行。CLI 版靠文本约定加正则提取,谁偏一点这条调用就废了。
SDK 版走的是原生机制。Claude 天生就知道怎么返回结构化的工具调用指令,只是走的是 Anthropic 自己的协议。你的程序用 OpenAI 格式定义工具,中转把它翻译成 Claude 认识的格式注册进去,Claude 返回标准结构化指令,再翻译回 OpenAI 格式还给你。全程结构化数据传递,不经过任何文本解析,可靠性是实打实的 100%。多个工具同时调用也不怕,每个调用是独立数据块,互不干扰,不像正则逐个匹配时,格式稍有偏差就互相打架。
一个实现细节别漏,注册工具时把 maxTurns 锁在 1,Claude 只生成调用、不执行调用,执行权留在你自己的程序手里。漏了这一步,模型会自作主张替你把工具跑了,排查起来非常迷惑。
打个比方,CLI 版像用对讲机指挥工人,大多听得清,偶尔信号差听岔一个词。SDK 版像发一张带标准编号的工单,编号、物品、位置全部打印清楚,照单执行就行。
还有一类请求不归这条通道管,带图片、音频、视频的多模态请求。SDK 的通道本身只吃文本,我的做法是加一层路由,检测到多模态内容,整条请求改道走 Gemini API。文本保精准,多媒体保功能,各走各的门。

真流式,还要防思考泄漏
claude -p 是一次性吐完整回答的,CLI 版只能在标点处切块,模拟打字效果。SDK 版是真流式,异步生成器逐事件转成 SSE 推送,Claude 每想出一个词就送过来,和你在网页里聊天看到的一模一样。对要实时反馈的 Agent 系统来说,这个差别很实在。
这里有个容易漏的安全点。Opus 这代模型有自适应推理,回答之前会先在内部推演一遍,这些思考块里可能原样带着你的系统提示。直接转发给客户端,你的 Agent 内部指令等于公开处刑。所以转发层要把所有思考事件过滤干净,一行都不许外流。过滤之后还要做一次实测验证,带着完整系统提示发一个请求,看客户端收到的流里有没有混进推理内容,这一步做在上线前,别做在事故后。
顺带说一句并发。SDK 这层我同样用 p-queue 排队,默认四路,满了先等,等位超载就返回 429 让对方稍后再来。模型侧的通道和 CLI 版是同一条,节奏控制住,比并发数字重要。

代价是指纹,两套一起跑才稳
天下没有两头甜。
CLI 版指纹干净,因为每个请求都是真实的 claude 命令行进程,后台看到的跟你手动敲命令没区别。SDK 版的指纹有暗伤,「什么都不加载、什么都不注册」这组参数,正常用户里几乎不会出现,等于穿制服进银行,你确实是来办事的,但谁都看得出你不是普通客户。
我的用法是两套同时跑。CLI 版在端口 3457 当主力,指纹干净,长期在线。SDK 版在端口 3456 当备份,工具调用百分之百可靠,主力有风吹草动就切过去。一套方案是风险,两套方案是保险。模型覆盖倒是不用担心,SDK 走的就是 Claude Code 同一条通道,终端里能用什么,它就能用什么。
把上一篇的风险排序搬过来对着看更清楚,CLI 子进程优于 SDK 优于网页 Cookie 优于 Token 直连。目前没有公开的封禁案例,但指纹差异客观存在,我不是在推荐谁抄作业,是在展示一遍完整的取舍过程。
没有完美的方案,只有互相补台的组合。
话说回来,把订阅转成 API 用,本身就不在 Anthropic 官方授权范围内。我两套跑了两周多没收到过警告,但这不代表以后不会,检测策略随时可能调,风险得自己掂量。老雷在企业方案里把话说在前面,这套玩法适合用得起损失的试验田,生产关键链路老老实实走官方 API,省下的订阅费要配得上担的心跳。
部署清单,五分钟跑起来
准备三样东西。Claude 订阅,100 刀或 200 刀档。装好并登录的 Claude Code。Node.js 20 以上。然后把这段话复制给 Claude Code。
「帮我搭一个 Claude SDK Proxy,用 Agent SDK 的 query 函数中转请求,对外暴露 OpenAI 兼容 API,TypeScript 加 Express,端口 3456。零污染隔离,不加载配置文件、不注册内置工具、不连外部插件,系统提示完全自定义。原生工具调用,OpenAI 工具定义转 Zod Schema 注册成内部工具,maxTurns 设为 1,只生成调用不执行。真流式,异步生成器逐事件转 SSE,自动过滤全部思考块。多模态路由,图片音频视频整条请求改走 Gemini API,密钥和模型名从环境变量读。加 Watchdog 守护,崩溃自动重启,五分钟内连崩五次停止重启。p-queue 四路并发,满载排队,超载返回 429。」
跑起来后两步验收。访问本机 3456 端口的 /health,有响应就是活的。然后在 OpenClaw 的 Provider 里填三行,接口地址填 localhost 加 3456 加 /v1,密钥随便填本地不鉴权,模型填 claude-opus-4。Cursor、Cherry Studio 这类 OpenAI 兼容客户端,同样的配法直接接。
两个常见的失败点提前说。一是 thinking 过滤忘了配,客户端会收到模型思考过程的原文,系统提示跟着泄漏,上线前拿一个带长系统提示的请求验一遍。二是工具注册时 maxTurns 没锁,表现为 Claude 自己执行了工具还把结果编进回答里,回提示词里补一句就行。
收个尾。CLI 版管隐蔽,SDK 版管精准,没有完美的方案,只有适合场景的组合。学习成本也得坦诚,两套服务、两份配置、两份日志,维护是双份的,图省事的团队未必划算。老雷见过只买最贵方案的企业,也见过把免费方案用到极致的小团队,分界线从来不在预算上,在你想清楚自己要什么的那一刻。你的 Agent 只需要聊聊天,CLI 版够用。要做精确的工具编排,SDK 版是正解。两个都要,那就两个都跑,反正它们不吵架。
