1. Claude Code 账单为什么总是压不下来如果你已经在用 Claude Code 写代码大概率遇到过这种困惑明明只是改个 bug、加个函数一天下来账单却几十刀同一个项目同事月费几十你月费几百。问题往往不在你写得多而在 Prompt Cache 没配好、没命中。Claude Code 和普通聊天 API 的调用结构完全不同。普通对话输入输出大致 1:1prompt 很短缓存收益有限。Claude Code 是反过来的一次「改个 bug」的请求输出可能只有 200 token但输入要带上系统提示词约 3000 token包含全部工具定义、CLAUDE.md 项目指令、历史对话、当前文件内容。典型一次请求输入 15K token、输出 500 token输入是输出的 30 倍。这种结构下输入 token 的单价几乎决定了你的总账单。而 Prompt Cache 对命中部分只收 10% 的价格也就是 90% 折扣。配好它输入成本能降一大截配错它缓存全失效账单直接翻倍。这篇就围绕 Claude Code 的 Prompt Cache把原理、可复制的 settings.json 配置、缓存失效排查清单以及通过 TaoToken 统一 Key/API 通道接入后的验证动作讲清楚目标是让你稳定命中缓存、把重复提示词开销压下去。2. Prompt Cache 原理与 Claude Code 的缓存层级2.1 不是「重复内容打折」而是前缀精确匹配很多教程把 Prompt Cache 说成「系统检测到重复内容就打折」这是错的。真实机制是服务端保存你最近发送的 prompt 前缀下次请求时只要前缀完全一致一字不差就从缓存读取跳过重新计算。关键点在于前缀任何一处变化后面所有内容的缓存全部失效。举个例子请求1[系统提示][工具定义][CLAUDE.md][对话历史1-5][新消息] 请求2[系统提示][工具定义][CLAUDE.md][对话历史1-6][新消息]如果请求 1 和请求 2 的「系统提示 工具定义 CLAUDE.md 对话历史 1-5」完全相同这部分命中缓存只有「对话历史 6 新消息」按全价计费。但如果你在请求 2 中间给 CLAUDE.md 加了一行那么从 CLAUDE.md 之后的所有内容包括之前已缓存的对话历史全部失效重新按全价算。2.2 Claude Code 的三层缓存Claude Code 自动配置了多层缓存理解它们的位置很关键缓存层内容大小复用频率L1系统提示词 内置工具定义约 3000 token整个会话L2CLAUDE.md通过 system-reminder 注入几百到几千 token整个会话L3对话历史每轮追加累积增长同一会话一个容易忽略的细节CLAUDE.md 不在 system prompt 里而是通过system-reminderXML 标签注入到 messages 数组中。这个设计让所有用户共享 system prompt 缓存同版本 Claude Code 系统提示词完全一致同时让你的 CLAUDE.md 单独缓存。所以改 CLAUDE.md 会破坏 L2 及其之后的所有缓存而 system prompt 本身不受影响。2.3 5min 与 1h 两档 TTL 怎么选Anthropic 提供两档缓存 TTL写入和读取价格不同档位写入价格读取价格适用场景5 分钟1.25× 基础输入价0.1× 基础输入价高频连续工作1 小时2× 基础输入价0.1× 基础输入价间断使用、长任务回本计算很简单5min 档写入溢价 0.25×一次缓存读取节省 0.9×就回本1h 档写入溢价 1×两次缓存读取就回本。Claude Code 默认让系统提示词和工具定义走 5min 缓存高频复用用户上下文根据 session 长度自动选择档位。你不需要手动指定但要保证前缀稳定否则档位再优也白搭。3. 通过 TaoToken 接入 Claude Code 的前置配置3.1 为什么用统一 Key/API 通道Claude Code 默认直连官方 API但国内开发者常遇到网络与结算问题。TaoToken 提供统一的 Key/API 通道把模型调用收敛到一个入口方便你在 Claude Code、其他编码工具之间复用同一套凭证也便于集中查看用量。它的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。需要强调的是Prompt Cache 是否生效取决于通道是否透明转发官方 API。透明转发会完整透传cache_creation_input_tokens和cache_read_input_tokens字段缓存行为与官方一致。下面配置完成后我们会专门验证这两个字段。3.2 获取 Key 与确认接入方式先到控制台创建 API Key入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。创建后复制 Key形如sk-...不要提交到 Git。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 Claude Code 的配置示例。如果你还想先验证模型是否可用可以用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条测试消息确认 Key 有效再进 Claude Code。4. 可复制的 settings.json 配置骨架4.1 基础配置Claude Code 读取~/.claude/settings.json。把 BASE_URL 指向 TaoToken 的 API 地址AUTH_TOKEN 填你的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, effortLevel: medium }effortLevel: medium适合大部分日常任务配合缓存能再降 20%–30% token 消耗。如果你做的是长期编码或 Agent 类任务可以考虑 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它更适合持续、高频的编码场景。4.2 CLAUDE.md 写法当索引不当文档CLAUDE.md 是缓存失效的头号来源写法要克制做保持 50 行以内当「索引」用列出关键文件路径、命令、约定只写项目核心约束比如「用 pnpm 不用 npm」写一次就稳定下来。不做写大段文档应该放进docs/让 Claude Code 主动 Read频繁修改写动态内容。# 项目约定 - 包管理器pnpm - 测试命令pnpm test - 关键目录src/core, src/api - 代码风格见 docs/style.md4.3 工作节奏配置把节奏固定下来缓存命中率会明显提升开新任务 → /new清空并建立新缓存 连续对话 → 利用缓存命中 任务做完 → /new 切换下一个 上下文臃肿 → /compact接受这一轮全价 绝不中途 → 改 CLAUDE.md / 切模型 / 加时间戳5. 验证请求与成功结果5.1 发起一次请求并查看 usage配置好后在 Claude Code 里发一条简单消息比如「读一下 README 第一段」。然后在响应或后台账单里查看 usage 字段{ usage: { input_tokens: 245, cache_creation_input_tokens: 3120, cache_read_input_tokens: 8450, output_tokens: 412 } }判断标准很直接有cache_creation_input_tokens和cache_read_input_tokens字段说明通道支持 Cache完全没有这两个字段说明不支持建议更换接入方式。第一次请求通常是cache_creation较大、cache_read为 0第二次起cache_read应该显著增长。5.2 用 curl 直接验证通道想绕过 Claude Code 单独验证可以直接打 APIcurl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-6, max_tokens: 128, system: [ {type: text, text: 你是一个简洁的助手。, cache_control: {type: ephemeral}} ], messages: [ {role: user, content: 只回复两个字收到} ] }连续执行两次第二次的返回里cache_read_input_tokens应该大于 0。如果两次都是 0检查cache_control是否加在了前缀末尾、前缀是否完全一致。5.3 实测节省幅度参考在长 session 持续工作场景下缓存命中率做到 80%–90% 时输入 token 成本下降 75%–80% 是可达的日常使用平均节省 40%–50%。100 轮编程会话不开缓存输入成本可能 50–100 美元开启缓存后能降到 10–19 美元区间。这些数字会随模型和官方价格调整变化但量级关系稳定。6. 缓存失效排查清单6.1 五大失效陷阱陷阱 1中途修改 CLAUDE.md。修改前[Sys][Tools][CLAUDE.md v1][对话1-10]命中修改后[Sys][Tools][CLAUDE.md v2][对话1-10]全部重新计算。对策session 开始前配好开始后不改。陷阱 2动态时间戳或随机内容。像「当前时间是 2026-05-04 15:23:45请…」这种塞进 system prompt 的内容会让缓存命中率归零。对策动态信息放 messages 末尾不要混进 system prompt 或前置工具描述。陷阱 3中途切换模型。请求 1 用claude-opus-4-7写入缓存 A请求 2 换claude-sonnet-4-6缓存 A 完全失效。对策同一任务保持模型一致需要切换时开新 session。陷阱 4/compact的隐藏成本。它触发的总结请求使用不同的 system prompt且通常不带工具前缀从第一个 token 就不同整个对话历史按全价计费一次。对策只在上下文确实臃肿时用重要子任务做完立即压缩而不是积累十几轮才压只想清空就直接/new。陷阱 5/resume恢复会话破坏缓存。恢复后前几轮请求按全价计费可能导致成本暴增。对策长任务尽量在一个连续 session 完成不得不中断时宁可在新 session 简短复述上下文。6.2 排查顺序遇到「明明开了缓存却不省钱」按这个顺序查1. 响应里有没有 cache_read_input_tokens 字段没有 → 通道不支持 Cache 2. 有字段但一直是 0 → 前缀不稳定检查 CLAUDE.md 是否被改 3. 前缀稳定但命中率低 → 检查是否混入时间戳/随机 ID 4. 命中率正常但账单高 → 检查是否频繁 /compact 或 /resume 5. 以上都正常 → 检查是否中途切了模型6.3 常见报错与处理如果请求返回 401检查ANTHROPIC_AUTH_TOKEN是否填错或过期重新到 API Keys 页生成。返回 404 通常是 BASE_URL 写错确认是https://taotoken.net/api而不是带路径的地址。返回 429 是限流降低并发或稍后重试。如果 Claude Code 启动时报配置解析错误用python -m json.tool ~/.claude/settings.json校验 JSON 格式。7. 把成本压到更低的组合策略把 Prompt Cache 和其他优化叠加是重度用户能做到的低成本配置优化层节省幅度累积成本相对官方原价基础官方直连—100%统一 Key/API 通道汇率差异约 33%–50%Prompt Cache 命中 60%输入端再降 50%约 16%–25%effortLevel: mediumtoken 总量降 25%约 12%–19%/new 控制上下文输入再降 30%约 8%–13%三条核心原则记住就行保持前缀稳定别中途改 CLAUDE.md、加时间戳、切模型同任务一气呵成长 session 比频繁 resume 更划算选对通道只有透明转发官方 API 的通道才支持 Cache。如果你还没接入可以先到模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite验证模型可用再到 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite生成 Key按本文的 settings.json 骨架配置。长期编码或 Agent 任务走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite更合适。配置完第一件事就是发一条请求确认返回里有cache_read_input_tokens且第二次大于 0——这一步过了后面的省钱才有意义。
Claude Code Prompt Cache 配置教程：原理详解+避坑指南+实测节省80%
1. Claude Code 账单为什么总是压不下来如果你已经在用 Claude Code 写代码大概率遇到过这种困惑明明只是改个 bug、加个函数一天下来账单却几十刀同一个项目同事月费几十你月费几百。问题往往不在你写得多而在 Prompt Cache 没配好、没命中。Claude Code 和普通聊天 API 的调用结构完全不同。普通对话输入输出大致 1:1prompt 很短缓存收益有限。Claude Code 是反过来的一次「改个 bug」的请求输出可能只有 200 token但输入要带上系统提示词约 3000 token包含全部工具定义、CLAUDE.md 项目指令、历史对话、当前文件内容。典型一次请求输入 15K token、输出 500 token输入是输出的 30 倍。这种结构下输入 token 的单价几乎决定了你的总账单。而 Prompt Cache 对命中部分只收 10% 的价格也就是 90% 折扣。配好它输入成本能降一大截配错它缓存全失效账单直接翻倍。这篇就围绕 Claude Code 的 Prompt Cache把原理、可复制的 settings.json 配置、缓存失效排查清单以及通过 TaoToken 统一 Key/API 通道接入后的验证动作讲清楚目标是让你稳定命中缓存、把重复提示词开销压下去。2. Prompt Cache 原理与 Claude Code 的缓存层级2.1 不是「重复内容打折」而是前缀精确匹配很多教程把 Prompt Cache 说成「系统检测到重复内容就打折」这是错的。真实机制是服务端保存你最近发送的 prompt 前缀下次请求时只要前缀完全一致一字不差就从缓存读取跳过重新计算。关键点在于前缀任何一处变化后面所有内容的缓存全部失效。举个例子请求1[系统提示][工具定义][CLAUDE.md][对话历史1-5][新消息] 请求2[系统提示][工具定义][CLAUDE.md][对话历史1-6][新消息]如果请求 1 和请求 2 的「系统提示 工具定义 CLAUDE.md 对话历史 1-5」完全相同这部分命中缓存只有「对话历史 6 新消息」按全价计费。但如果你在请求 2 中间给 CLAUDE.md 加了一行那么从 CLAUDE.md 之后的所有内容包括之前已缓存的对话历史全部失效重新按全价算。2.2 Claude Code 的三层缓存Claude Code 自动配置了多层缓存理解它们的位置很关键缓存层内容大小复用频率L1系统提示词 内置工具定义约 3000 token整个会话L2CLAUDE.md通过 system-reminder 注入几百到几千 token整个会话L3对话历史每轮追加累积增长同一会话一个容易忽略的细节CLAUDE.md 不在 system prompt 里而是通过system-reminderXML 标签注入到 messages 数组中。这个设计让所有用户共享 system prompt 缓存同版本 Claude Code 系统提示词完全一致同时让你的 CLAUDE.md 单独缓存。所以改 CLAUDE.md 会破坏 L2 及其之后的所有缓存而 system prompt 本身不受影响。2.3 5min 与 1h 两档 TTL 怎么选Anthropic 提供两档缓存 TTL写入和读取价格不同档位写入价格读取价格适用场景5 分钟1.25× 基础输入价0.1× 基础输入价高频连续工作1 小时2× 基础输入价0.1× 基础输入价间断使用、长任务回本计算很简单5min 档写入溢价 0.25×一次缓存读取节省 0.9×就回本1h 档写入溢价 1×两次缓存读取就回本。Claude Code 默认让系统提示词和工具定义走 5min 缓存高频复用用户上下文根据 session 长度自动选择档位。你不需要手动指定但要保证前缀稳定否则档位再优也白搭。3. 通过 TaoToken 接入 Claude Code 的前置配置3.1 为什么用统一 Key/API 通道Claude Code 默认直连官方 API但国内开发者常遇到网络与结算问题。TaoToken 提供统一的 Key/API 通道把模型调用收敛到一个入口方便你在 Claude Code、其他编码工具之间复用同一套凭证也便于集中查看用量。它的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。需要强调的是Prompt Cache 是否生效取决于通道是否透明转发官方 API。透明转发会完整透传cache_creation_input_tokens和cache_read_input_tokens字段缓存行为与官方一致。下面配置完成后我们会专门验证这两个字段。3.2 获取 Key 与确认接入方式先到控制台创建 API Key入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。创建后复制 Key形如sk-...不要提交到 Git。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 Claude Code 的配置示例。如果你还想先验证模型是否可用可以用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条测试消息确认 Key 有效再进 Claude Code。4. 可复制的 settings.json 配置骨架4.1 基础配置Claude Code 读取~/.claude/settings.json。把 BASE_URL 指向 TaoToken 的 API 地址AUTH_TOKEN 填你的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, effortLevel: medium }effortLevel: medium适合大部分日常任务配合缓存能再降 20%–30% token 消耗。如果你做的是长期编码或 Agent 类任务可以考虑 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它更适合持续、高频的编码场景。4.2 CLAUDE.md 写法当索引不当文档CLAUDE.md 是缓存失效的头号来源写法要克制做保持 50 行以内当「索引」用列出关键文件路径、命令、约定只写项目核心约束比如「用 pnpm 不用 npm」写一次就稳定下来。不做写大段文档应该放进docs/让 Claude Code 主动 Read频繁修改写动态内容。# 项目约定 - 包管理器pnpm - 测试命令pnpm test - 关键目录src/core, src/api - 代码风格见 docs/style.md4.3 工作节奏配置把节奏固定下来缓存命中率会明显提升开新任务 → /new清空并建立新缓存 连续对话 → 利用缓存命中 任务做完 → /new 切换下一个 上下文臃肿 → /compact接受这一轮全价 绝不中途 → 改 CLAUDE.md / 切模型 / 加时间戳5. 验证请求与成功结果5.1 发起一次请求并查看 usage配置好后在 Claude Code 里发一条简单消息比如「读一下 README 第一段」。然后在响应或后台账单里查看 usage 字段{ usage: { input_tokens: 245, cache_creation_input_tokens: 3120, cache_read_input_tokens: 8450, output_tokens: 412 } }判断标准很直接有cache_creation_input_tokens和cache_read_input_tokens字段说明通道支持 Cache完全没有这两个字段说明不支持建议更换接入方式。第一次请求通常是cache_creation较大、cache_read为 0第二次起cache_read应该显著增长。5.2 用 curl 直接验证通道想绕过 Claude Code 单独验证可以直接打 APIcurl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-6, max_tokens: 128, system: [ {type: text, text: 你是一个简洁的助手。, cache_control: {type: ephemeral}} ], messages: [ {role: user, content: 只回复两个字收到} ] }连续执行两次第二次的返回里cache_read_input_tokens应该大于 0。如果两次都是 0检查cache_control是否加在了前缀末尾、前缀是否完全一致。5.3 实测节省幅度参考在长 session 持续工作场景下缓存命中率做到 80%–90% 时输入 token 成本下降 75%–80% 是可达的日常使用平均节省 40%–50%。100 轮编程会话不开缓存输入成本可能 50–100 美元开启缓存后能降到 10–19 美元区间。这些数字会随模型和官方价格调整变化但量级关系稳定。6. 缓存失效排查清单6.1 五大失效陷阱陷阱 1中途修改 CLAUDE.md。修改前[Sys][Tools][CLAUDE.md v1][对话1-10]命中修改后[Sys][Tools][CLAUDE.md v2][对话1-10]全部重新计算。对策session 开始前配好开始后不改。陷阱 2动态时间戳或随机内容。像「当前时间是 2026-05-04 15:23:45请…」这种塞进 system prompt 的内容会让缓存命中率归零。对策动态信息放 messages 末尾不要混进 system prompt 或前置工具描述。陷阱 3中途切换模型。请求 1 用claude-opus-4-7写入缓存 A请求 2 换claude-sonnet-4-6缓存 A 完全失效。对策同一任务保持模型一致需要切换时开新 session。陷阱 4/compact的隐藏成本。它触发的总结请求使用不同的 system prompt且通常不带工具前缀从第一个 token 就不同整个对话历史按全价计费一次。对策只在上下文确实臃肿时用重要子任务做完立即压缩而不是积累十几轮才压只想清空就直接/new。陷阱 5/resume恢复会话破坏缓存。恢复后前几轮请求按全价计费可能导致成本暴增。对策长任务尽量在一个连续 session 完成不得不中断时宁可在新 session 简短复述上下文。6.2 排查顺序遇到「明明开了缓存却不省钱」按这个顺序查1. 响应里有没有 cache_read_input_tokens 字段没有 → 通道不支持 Cache 2. 有字段但一直是 0 → 前缀不稳定检查 CLAUDE.md 是否被改 3. 前缀稳定但命中率低 → 检查是否混入时间戳/随机 ID 4. 命中率正常但账单高 → 检查是否频繁 /compact 或 /resume 5. 以上都正常 → 检查是否中途切了模型6.3 常见报错与处理如果请求返回 401检查ANTHROPIC_AUTH_TOKEN是否填错或过期重新到 API Keys 页生成。返回 404 通常是 BASE_URL 写错确认是https://taotoken.net/api而不是带路径的地址。返回 429 是限流降低并发或稍后重试。如果 Claude Code 启动时报配置解析错误用python -m json.tool ~/.claude/settings.json校验 JSON 格式。7. 把成本压到更低的组合策略把 Prompt Cache 和其他优化叠加是重度用户能做到的低成本配置优化层节省幅度累积成本相对官方原价基础官方直连—100%统一 Key/API 通道汇率差异约 33%–50%Prompt Cache 命中 60%输入端再降 50%约 16%–25%effortLevel: mediumtoken 总量降 25%约 12%–19%/new 控制上下文输入再降 30%约 8%–13%三条核心原则记住就行保持前缀稳定别中途改 CLAUDE.md、加时间戳、切模型同任务一气呵成长 session 比频繁 resume 更划算选对通道只有透明转发官方 API 的通道才支持 Cache。如果你还没接入可以先到模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite验证模型可用再到 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite生成 Key按本文的 settings.json 骨架配置。长期编码或 Agent 任务走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite更合适。配置完第一件事就是发一条请求确认返回里有cache_read_input_tokens且第二次大于 0——这一步过了后面的省钱才有意义。
