1. 从一次“工具没被调用”说起Claude Code 工具调用编排链路到底长什么样Claude Code 是 Anthropic 推出的终端 AI 编码代理它和普通聊天机器人的最大区别在于它能自己决定“要不要调用工具、调用哪个工具、按什么顺序调用”。这套决策与执行机制就是 AI 对话引擎里的工具调用编排tool orchestration。适合谁看适合已经在本地跑 Claude Code、想搞清楚它内部请求怎么组装、流式响应怎么解析、工具执行顺序怎么排的开发者。我最初以为 Claude Code 只是把用户输入丢给模型模型返回文本就完事。直到有一次我让它“读取 package.json 并把 scripts 里的 build 命令改成 tsc -b”它没有直接改文件而是先返回了一个tool_use块里面写着Read工具和路径参数。那一刻我才意识到模型输出的不是最终答案而是一份“行动计划”真正的执行发生在本地进程里。这条链路可以拆成四段请求组装把系统提示、历史消息、工具定义打包成 API 请求、流式响应解析逐块读取 SSE区分文本增量和工具调用增量、工具执行编排判断依赖关系、并行或串行执行、权限校验、结果回填把工具输出作为新的 user/tool 消息塞回历史再次请求模型。四段循环往复直到模型返回纯文本、不再请求工具为止。理解这条链路的价值在于当工具“没被调用”或“调用错了”你能快速定位是请求里工具定义没带上、还是流式解析把 tool_use 块丢了、还是执行阶段被权限拦了。下面我按可复现的顺序把每一段拆开讲并给出能直接抄的配置和验证步骤。2. TaoToken 前置把 Base URL、Key、Model ID 三件套配好在复现编排链路之前得先让 Claude Code 能稳定发出请求。Claude Code 默认走 Anthropic 官方端点但很多人在本地调试时希望统一走一个兼容 Anthropic Messages API 的入口方便观察请求和计费。TaoToken 提供的就是这样一个入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。配置的核心是三件套Base URL、API Key、Model ID。Claude Code 读取的是环境变量和 settings 文件最稳妥的方式是写进~/.claude/settings.json而不是只 export 到当前 shell——因为 Claude Code 可能由别的进程拉起环境变量不一定继承。先拿 Key打开 https://taotoken.net/api-keys 新建一个 key复制出来。注意 key 只在创建时完整显示一次关掉页面就看不到了建议先粘到本地临时文件。然后写 settings。Claude Code 的 settings 支持env字段注入环境变量这样 Base URL 和 Key 都能被内部请求层读到{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-3-5-20241022 } }这里有个容易踩的坑ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是两个不同的变量。Claude Code 在走自定义 Base URL 时读的是ANTHROPIC_AUTH_TOKEN如果你只设了ANTHROPIC_API_KEY请求会带着空 Authorization 头出去直接 401。我试过只改 Key 变量名问题就消失了。Model ID 要写全别只写claude-sonnet-4。Anthropic 的模型 ID 带日期后缀写错了服务端会返回 model not found。ANTHROPIC_SMALL_FAST_MODEL是给后台小任务比如生成标题、压缩上下文用的配成 haiku 能省不少 token。配完可以用一条命令验证环境是否被读到claude --version cat ~/.claude/settings.json | python3 -m json.tool如果 settings 是合法 JSON第二条命令会格式化输出如果报 JSON 解析错误说明你多写了逗号或少了引号Claude Code 启动时会静默忽略整个文件表现就是“配置了但没生效”。3. 可复制配置请求组装与流式解析的关键片段这一节是全文技术密度最高的部分。Claude Code 内部用 TypeScript 写请求组装和流式解析我们可以用一段最小可运行的 Node 脚本来复现它的行为这样你能亲眼看到 tool_use 块是怎么从 SSE 流里冒出来的。先看请求体结构。Anthropic Messages API 的请求长这样// request.ts const body { model: claude-sonnet-4-20250514, max_tokens: 4096, system: You are a coding agent. Use tools when needed., tools: [ { name: Read, description: Read a file from disk, input_schema: { type: object, properties: { path: { type: string } }, required: [path] } } ], messages: [ { role: user, content: 读取 package.json 的 name 字段 } ], stream: true };注意tools数组里每个工具都有name、description、input_schema。模型就是靠这三样决定调不调、怎么调。description写得越清楚模型选错工具的概率越低。我见过有人把 description 写成“读取文件”结果模型在需要读目录时也调它因为描述没区分文件和目录。然后是流式解析。Anthropic 的 SSE 事件类型有message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。工具调用藏在content_block_starttype 为tool_use和后续的input_json_delta里// stream.ts async function parseStream(resp: Response) { const reader resp.body!.getReader(); const decoder new TextDecoder(); let buffer ; const toolCalls: any[] []; let currentTool: any null; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop() || ; for (const line of lines) { if (!line.startsWith(data: )) continue; const data line.slice(6); if (data [DONE]) continue; const evt JSON.parse(data); if (evt.type content_block_start evt.content_block.type tool_use) { currentTool { id: evt.content_block.id, name: evt.content_block.name, input: }; } if (evt.type content_block_delta evt.delta.type input_json_delta) { currentTool.input evt.delta.partial_json; } if (evt.type content_block_stop currentTool) { currentTool.input JSON.parse(currentTool.input); toolCalls.push(currentTool); currentTool null; } } } return toolCalls; }这段代码的关键点input_json_delta是分片到达的必须拼完再JSON.parse否则会拿到半截 JSON 报错。很多人第一次写流式解析直接在 delta 里 parse结果就是Unexpected end of JSON input。执行顺序编排则取决于工具之间有没有依赖。如果模型一次返回两个 tool_use一个读文件、一个跑 bash而 bash 不依赖读的结果就可以Promise.all并行如果第二个工具的参数来自第一个工具的输出就必须串行。Claude Code 的做法是先按依赖分组无依赖的组内并行组间串行。4. 验证请求跑一次完整工具调用链路并观察流式输出配置和代码都齐了现在跑一次端到端验证。目标让模型读取一个本地文件观察流式输出里文本增量和工具调用增量的到达顺序。准备一个测试文件mkdir -p /tmp/cc-demo cd /tmp/cc-demo echo {name:demo,version:1.0.0} package.json然后写一个最小脚本run.ts把第 3 节的 request 和 stream 拼起来// run.ts const resp await fetch(https://taotoken.net/api/v1/messages, { method: POST, headers: { content-type: application/json, x-api-key: process.env.ANTHROPIC_AUTH_TOKEN!, anthropic-version: 2023-06-01 }, body: JSON.stringify(body) }); console.log(status:, resp.status); const calls await parseStream(resp); console.log(tool calls:, JSON.stringify(calls, null, 2));用npx tsx run.ts跑。预期看到两类输出先是status: 200然后tool calls数组里有一个Read调用input是{ path: package.json }。如果 status 是 401回到第 2 节检查ANTHROPIC_AUTH_TOKEN如果是 404检查 Base URL 有没有多写或少写/v1。更贴近 Claude Code 真实行为的验证是直接在终端里跑claude -p 读取 package.json 并告诉我 name 字段的值加--debug能看到它发出的原始请求和收到的 SSE 事件claude --debug -p 读取 package.json 并告诉我 name 字段的值 21 | grep -E tool_use|content_block你会看到content_block_start里 type 是tool_use、name 是Read紧接着一串input_json_delta最后content_block_stop。这就是编排链路在真实进程里的样子。工具执行完后Claude Code 会把结果作为新的消息追加到历史再发一次请求这次模型返回纯文本链路结束。想更直观地看模型对话过程可以打开 https://taotoken.net/chat 把同样的 prompt 丢进去对比终端输出和网页输出的差异——网页端通常把工具调用折叠成一行“正在读取文件”终端则把原始事件打出来。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障这节我按真实报错来对每个都给出定位路径。401 Unauthorized最常见。九成是变量名写错。Claude Code 走自定义 Base URL 时读ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY。另一个可能是 key 前后带了空格或换行从网页复制时容易带上。用echo -n $ANTHROPIC_AUTH_TOKEN | wc -c看长度对不对。local proxy failed / connection refused说明 Claude Code 试图连一个本地代理端口但那个端口没进程在听。检查 settings 里有没有残留的HTTP_PROXY、HTTPS_PROXY指向127.0.0.1:xxxx。有的话删掉或者确认代理进程真的起来了。这类报错和 Base URL 无关别去改 API 地址。reading choices of undefined这是 OpenAI 格式和 Anthropic 格式混用导致的。choices是 OpenAI Chat Completions 的响应字段Anthropic Messages API 返回的是content数组。如果你用了一个按 OpenAI 格式解析响应的客户端去请求 Anthropic 端点就会在resp.choices[0]处炸掉。解决方法是确认客户端走的是 Messages API 格式或者换用支持 Anthropic 协议的 SDK。OAuth 相关报错Claude Code 某些版本会尝试 OAuth 登录流程。如果你用的是 API Key 模式确保没有同时存在 OAuth token 文件通常在~/.claude/下。两者冲突时请求可能带着过期的 OAuth token 出去。删掉 OAuth 缓存文件只保留 settings 里的 Key 配置。工具调用返回空 input流式解析时input_json_delta没拼完就 parse或者content_block_stop事件被漏掉。检查你的 buffer 分割逻辑SSE 事件之间用\n\n分隔单行data:后面可能跟多行。模型不调用工具先看请求里tools数组是不是空的。再看 system prompt 有没有明确指示“需要时使用工具”。最后看tool_choice参数默认是auto如果被设成none模型永远不会调工具。6. 语义一致 CTA把这条链路用起来编排链路跑通之后下一步是把它接到真实工作流里。如果你主要做模型能力验证和对话调试可以直接用模型对话入口 https://taotoken.net/chat 把工具定义和 prompt 贴进去观察模型在不同描述下的工具选择差异。如果你要长期跑编码任务、让 Agent 自己读写文件跑命令建议开 Coding Plan https://taotoken.net/coding-plan 它按周期计费比按 token 单次调用更适合高频工具编排场景。接入文档在 https://taotoken.net/doc 里面有 Messages API 的完整字段说明和流式事件类型表排障时对着查很快。配置三件套Base URL、Key、Model ID如果还没落地回到 https://taotoken.net/api-keys 拿 key再按第 2 节的 settings.json 写进去。Claude Code 的接入细节可以参考 https://taotoken.net/claude-code 里面有 settings 字段的完整列表。最后留一个实用技巧调试工具编排时把max_tokens调小到 1024这样模型返回的 tool_use 块更短SSE 事件更少肉眼更容易跟。等链路确认没问题再调回正常值。
