1. 为什么我盯着请求体看了整整一下午
Claude Code 每次调用 API 时，上下文是怎么“拼”出来的？这个问题看起来抽象，但只要你抓一次真实请求体，就会发现它其实是一套非常工程化的分层组装逻辑。简单说，Claude Code 发给模型的 payload 由三块组成：System Prompt 定义 Agent 的身份、行为规范和安全边界；Tools 是工具 schema 列表，告诉模型有哪些能力可用；Messages 是对话消息流，包含用户指令、CLAUDE.md 配置、工具执行结果和各类附加上下文。这三块在 Agent Loop 里每轮都会传给模型，但它们的来源和更新频率完全不同。
这套机制适合谁看？如果你正在用 Claude Code 做日常开发，或者想搞清楚为什么改了 CLAUDE.md 之后模型行为变了、为什么工具多了之后响应变慢、为什么某些请求会命中缓存而另一些不会，那这篇文章就是写给你的。我会结合 TaoToken 统一 Key 通道，把请求体结构拆开给你看，给出可复制的抓包配置和字段对照表，再演示一次完整请求的验证步骤。
核心约束只有一条：System Prompt 和 Tools 是缓存敏感的前缀层，Messages 才是持续增长的动态层。模型 API 会尽量复用稳定请求前缀，如果 System Prompt 或工具 schema 在中途变化，前缀缓存就会失效。这个约束直接决定了 Claude Code 的上下文组装架构——稳定前缀，动态内容后移。适合缓存的内容尽量放在前缀里保持稳定，运行时变化则尽量移到 Messages、attachment 附加上下文或延迟工具加载里。
我试过把一轮完整请求的 payload 打印出来逐字段对照，发现真正随每轮工具执行不断追加、更新的只有 Messages。Agent Loop 的核心机制就是模型返回工具调用请求，系统执行工具并把结果追加进 Messages，再进入下一轮模型调用，直到任务完成。下面按实际拆解顺序展开。
2. TaoToken 统一 Key 通道：把请求体看清楚的前置准备
要观察 Claude Code 的上下文组装，最直接的办法是让它走一个你能控制的 API 通道，然后抓取请求体。TaoToken 在这里的作用是提供统一的 Key 和 API 入口，让你不用分别配置多个模型供应商的凭证，就能在同一个通道里观察 Claude Code 发出的请求结构。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。
前置准备分三步。第一步，在 TaoToken 控制台创建一个 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完成后到 API Keys 页面复制，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。第二步，确认你要用的模型 ID，可以在模型对话页面先做一次简单验证，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。第三步，把 Claude Code 的 Base URL 指向 TaoToken 的 API 入口，Key 填刚创建的那串，Model ID 填你验证过的那个。
这里有个关键点：Claude Code 的请求体结构不会因为你换了通道就改变，System Prompt、Tools、Messages 的组装逻辑仍然由 Claude Code 自己决定。TaoToken 统一 Key 通道的价值在于，你只需要维护一套凭证，就能在同一个入口观察不同模型下的请求差异，同时避免在多个供应商之间来回切换配置。如果你打算长期用 Claude Code 做编码或 Agent 任务，可以了解 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它更适合持续性的编码场景。
接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面写清楚了 Base URL 和鉴权头的填法。如果你用的是 Claude Code 的 Anthropic 兼容模式，参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 。把这三件套——Base URL、Key、Model ID——配好之后，Claude Code 发出的每一轮请求都会经过这个通道，你就有机会看到它的真实结构了。
3. 可复制配置：抓包环境与字段对照
要让 Claude Code 走 TaoToken 通道并留下可观察的请求体，最省事的办法是在本地起一个转发记录层。下面给出一份可复制的配置片段，路径和字段名保持和实际使用一致。先配置 Claude Code 的 settings，把 Base URL 和 Key 指向 TaoToken：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "你的ModelID" } }这份 settings 放在 Claude Code 的配置目录里，具体路径按你的系统来。配好之后，Claude Code 的模型调用就会走 TaoToken 的 API 入口。接下来，如果你想在本地看到请求体，可以在中间加一层记录代理。下面是一个用 Node.js 写的极简转发脚本，它把请求体写到本地文件再转发出去：
// proxy-log.js const http = require('http'); const https = require('https'); const fs = require('fs'); const TARGET = 'https://taotoken.net'; http.createServer((req, res) => { let body = ''; req.on('data', chunk => { body += chunk; }); req.on('end', () => { // 把请求体落盘，方便逐字段对照 fs.appendFileSync('requests.log', body + '\n---\n'); const url = new URL(req.url, TARGET); const proxyReq = https.request({ hostname: url.hostname, path: url.pathname + url.search, method: req.method, headers: { ...req.headers, host: url.hostname } }, proxyRes => { res.writeHead(proxyRes.statusCode, proxyRes.headers); proxyRes.pipe(res); }); proxyReq.on('error', err => { res.writeHead(502); res.end('proxy error: ' + err.message); }); proxyReq.write(body); proxyReq.end(); }); }).listen(8787, () => console.log('logging proxy on 8787'));启动这个脚本后，把 Claude Code 的 Base URL 临时改成http://127.0.0.1:8787，请求体就会先落到requests.log。注意，这个代理只用于本地观察，不要把它当成生产链路。抓到的请求体里，你会看到三个顶层字段：system、tools、messages。下面这张对照表帮你快速定位每个字段的来源和更新频率：
| 字段 | 来源 | 更新频率 | 是否缓存敏感前缀 |
|---|---|---|---|
| system | 静态段落 + 动态段落数组拼接 | 会话内基本稳定，动态段落 memoized | 是，边界前尽量 byte-level 稳定 |
| tools | 内置工具 + MCP + Skill 候选池过滤 | 直接传入部分稳定，长尾走延迟加载 | 是，schema 变化会打破前缀缓存 |
| messages | CLAUDE.md + 用户输入 + attachment + 工具结果 | 每轮持续增长 | 否，动态层 |
System Prompt 不是一个巨大的字符串，而是一个字符串数组。每个元素是一个独立段落，在发送给 API 之前才拼接成最终形式。静态段落放在前面，动态段落放在SYSTEM_PROMPT_DYNAMIC_BOUNDARY标记之后。静态段落包括身份声明、系统规则、任务执行准则、操作安全、工具使用偏好、沟通风格、输出效率，内容占比大约 60% 以上。动态段落包括 session_guidance、memory、env_info_simple、language、output_style、mcp_instructions，它们因用户环境、配置、记忆不同而变化，但在单个会话内部大部分会被 memoized。
Tools 部分不是会话开始后永远不变。Claude Code 维护一个候选工具池，再决定哪些工具直接进入本轮模型请求，哪些通过 Tool Search 延迟加载。直接传入的工具 schema 属于缓存敏感前缀的一部分，通常是高频、基础、需要立即可见的工具；deferred tools 不直接进入前缀，通过 Tool Search 在需要时暴露，避免工具 schema 把稳定前缀撑大或频繁打破缓存。
Messages 的初始组装由三部分组成：CLAUDE.md 通过prependUserContext()包装为 user message 插入数组最前面，用户输入包装为 UserMessage，@提及的文件、IDE 选中代码、hook 注入内容包装为 AttachmentMessage 跟在后面。CLAUDE.md 按优先级从低到高加载：Managed 在/etc/claude-code/CLAUDE.md，User 在~/.claude/CLAUDE.md，Project 在项目根目录或上级目录的CLAUDE.md、.claude/CLAUDE.md或.claude/rules/*.md，Local 在项目根目录的CLAUDE.local.md。高优先级文件的内容排在低优先级之后，因为模型从上到下阅读 messages，后出现的指令通常会被优先遵循。
4. 验证请求：一次完整调用的字段观察步骤
配置好之后，怎么确认你看到的请求体结构是对的？下面给出一套可跟做的验证步骤。第一步，启动本地记录代理，确认requests.log文件已创建。第二步，在 Claude Code 里发一条最简单的指令，比如让它读一个文件。第三步，等这一轮工具执行完成后，打开requests.log，找到对应的请求体。
你会看到第一轮请求的messages数组大致是这样的结构：第一条是 CLAUDE.md 包装成的 user message，内容被<system-reminder>标签包裹；第二条是用户原始输入；后面跟着若干 AttachmentMessage，比如attachment:file、attachment:diagnostics。注意，这里的<system-reminder>是 user message 内容里的 XML-like 标签，不等同于 API 的 system role。CLAUDE.md 注入的示意内容如下：
<system-reminder> As you answer the user's questions, you can use the following context: # claudeMd Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written. Contents of ~/.claude/CLAUDE.md (user's private global instructions for all projects): # 全局偏好 - 默认使用中文回复 - commit message 使用英文 Contents of CLAUDE.md (project instructions, checked into the codebase): # 项目规范 - 所有接口必须返回统一的 `{ code, data, message }` 结构 - 错误处理使用 AppError 类，不要直接 throw Error # currentDate Today's date is 2026-05-17. </system-reminder>第四步，观察第二轮请求。当模型返回工具调用请求后，系统执行工具并把结果追加进 Messages，然后进入下一轮模型调用。这时候你再打开requests.log，会看到messages数组变长了：新增了 assistant 消息（包含 tool_use 块）和 tool result 消息。同时，system和tools字段基本没变，这就是稳定前缀的体现。
第五步，对照 token 分布。你可以用 TaoToken 的模型对话页面做一次简单请求，观察返回的 usage 字段，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。在 Claude Code 的请求里，System Prompt 和 Tools 占用的 token 相对固定，Messages 的 token 会随着工具执行轮次增加而增长。如果你发现某一轮system字段突然变了，那大概率是动态段落里的 mcp_instructions 或 session_guidance 被重新计算了，这时候前缀缓存可能失效。
第六步，验证 CLAUDE.md 的注入位置。在项目根目录新建一个CLAUDE.md，写一条明显的指令，比如“所有回复末尾加上 DONE”。然后重新发一条指令，观察requests.log里 CLAUDE.md 的内容是否出现在 messages 最前面。你会发现，prependUserContext()在每轮调用模型前都会执行，因此 CLAUDE.md 在每一轮对话中都位于 messages 的最前面。这个排序只描述同为 CLAUDE.md 上下文时的工程策略，不代表 Project 级内容可以覆盖 System Prompt 或安全边界。
整个验证过程的核心是看清楚三件事：哪些内容稳定、哪些内容按需装配、哪些内容会随着工具执行继续增量补进下一轮 Messages。System Prompt 管“模型该如何被约束”，CLAUDE.md 管“这个项目希望模型知道什么”。把这两者分开理解，你就能明白为什么改 CLAUDE.md 比改 System Prompt 更安全，也更灵活。
5. 常见报错排查：401、local proxy failed 与 reading choices
在抓包和验证过程中，最容易遇到的几个报错我都踩过。下面按真实报错逐条对照，给出排查路径。
第一个是 401 鉴权失败。如果你在requests.log里看到请求发出去了，但返回 401，先检查ANTHROPIC_API_KEY是否填的是 TaoToken 控制台创建的 Key，而不是其他供应商的 Key。然后确认ANTHROPIC_BASE_URL是否指向https://taotoken.net/api，注意不要多加路径后缀。如果用的是 Claude Code 的 Anthropic 兼容模式，参考接入文档确认鉴权头的字段名，地址是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。三件套——Base URL、Key、Model ID——任何一个填错都会导致 401 或 404。
第二个是 local proxy failed。这个报错通常出现在你用了本地记录代理但代理没启动，或者端口被占用。先确认proxy-log.js是否在运行，8787端口是否被其他进程占用。如果代理脚本报proxy error，检查它转发到的目标地址是否正确。注意，本地代理只用于观察，不要把它配置成长期链路，否则一旦代理进程挂掉，Claude Code 的所有请求都会失败。
第三个是 reading choices 相关报错。这个通常出现在响应体解析阶段，说明请求发出去了、也返回了，但返回结构不符合预期。先检查 Model ID 是否填对，可以在模型对话页面单独验证一次，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。如果模型对话正常但 Claude Code 报错，检查requests.log里的tools字段是否有异常 schema，比如某个 MCP 工具注册失败导致 schema 不完整。
第四个是 OAuth 相关报错。如果你在 Claude Code 里同时配置了 OAuth 登录和 API Key，可能会出现凭证冲突。排查方法是先确认当前使用的是 API Key 模式，检查 settings 里是否有残留的 OAuth 配置。如果用的是 Claude Code 的 Anthropic 兼容模式，参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 确认配置项。
如果你用的是 CC Switch、Cline MCP 或 Codex 的 auth.json，记住三件套必须写全：Base URL 填https://taotoken.net/api，Key 填 TaoToken 控制台的 Key，Model ID 填你验证过的模型。任何一项缺失都会导致请求失败。排查顺序建议是：先看requests.log确认请求体是否正常生成，再看返回状态码定位是鉴权问题还是模型问题，最后对照接入文档检查配置项。
6. 把上下文组装逻辑用起来
理解 Claude Code 的上下文组装，核心不是记住某一个固定 prompt 长什么样，而是看清楚分层组装、分阶段更新的机制。System Prompt 承载稳定规则和动态段落边界，尽量让可缓存的前缀保持稳定；Tools 根据内置工具、MCP、Agent、Skill 等来源组装，并在必要时通过延迟加载降低上下文负担；Messages 是 Agent Loop 中持续变化的主体，用户输入、模型回复、工具调用结果和 attachment 附加上下文都会按顺序进入消息流。
实际用起来，你可以把稳定规则写进 System Prompt 或项目级 CLAUDE.md，把运行时变化交给 Messages 和 attachment。如果你想让模型知道当前工作目录、操作系统、Shell 类型，这些会通过 env_info_simple 动态段落注入；如果你想让模型知道可用技能和 Agent 类型，这些会通过 session_guidance 和 skill_discovery 注入。真正需要每轮变化的内容，尽量后移到 Messages、增量 attachment 或延迟工具加载里，避免直接改动可缓存前缀。
如果你打算长期用 Claude Code 做编码或 Agent 任务，建议把 Base URL、Key、Model ID 三件套固定下来，用 TaoToken 统一 Key 通道减少配置切换成本。需要创建 Key 就去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，想先验证模型就去 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，长期编码场景可以看 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。接入细节都在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到 Anthropic 兼容模式的问题就查 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 。
最后留一个实用技巧：每次改完 CLAUDE.md 或调整工具配置后，重新抓一次请求体，对比system和tools字段有没有变化。如果变了，说明前缀缓存可能失效，下一轮请求的延迟和成本会上升。把稳定内容尽量前置、动态内容尽量后移，是让 Claude Code 跑得又稳又省的关键。
