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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。前置准备分三步。第一步在 TaoToken 控制台创建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完成后到 API Keys 页面复制地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二步确认你要用的模型 ID可以在模型对话页面先做一次简单验证地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。第三步把 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_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合持续性的编码场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写清楚了 Base URL 和鉴权头的填法。如果你用的是 Claude Code 的 Anthropic 兼容模式参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。把这三件套——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 变化会打破前缀缓存messagesCLAUDE.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.mdUser 在~/.claude/CLAUDE.mdProject 在项目根目录或上级目录的CLAUDE.md、.claude/CLAUDE.md或.claude/rules/*.mdLocal 在项目根目录的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 users 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 (users 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 Todays 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_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在 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_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。三件套——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_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果模型对话正常但 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_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 确认配置项。如果你用的是 CC Switch、Cline MCP 或 Codex 的 auth.json记住三件套必须写全Base URL 填https://taotoken.net/apiKey 填 TaoToken 控制台的 KeyModel 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_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 想先验证模型就去 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 长期编码场景可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入细节都在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到 Anthropic 兼容模式的问题就查 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。最后留一个实用技巧每次改完 CLAUDE.md 或调整工具配置后重新抓一次请求体对比system和tools字段有没有变化。如果变了说明前缀缓存可能失效下一轮请求的延迟和成本会上升。把稳定内容尽量前置、动态内容尽量后移是让 Claude Code 跑得又稳又省的关键。