Claude Code 成本优化:25 项可执行清单

给 system prompt 启用 cache_control

如果你直接调用 API,把 system prompt(或任何在多次请求间复用的大块上下文)包入一个 cache_control: {"type": "ephemeral"} 块。命中缓存的 token 仅按未缓存输入的 10% 计价。一段 1 万 token 的 system prompt,每天复用 50 次,等于每天节省 450 万 token。

system=[{
  "type": "text",
  "text": your_large_system_prompt,
  "cache_control": {"type": "ephemeral"}
}]

对反复查询的同一文档,先缓存再查

如果你要对同一份文档(代码库片段、规范文档、PDF)跑多个 prompt,首次请求时把文档缓存下来。后续每次命中缓存,文档部分只付 10%。盈亏平衡在第 2 次请求,3 次以上就净赚。

从响应头监控缓存命中率

读取每次 API 响应中的 usage.cache_read_input_tokens。如果你的应用以 system prompt 为主、命中率却低于 60%,说明缓存在你下次复用之前就过期了。短期缓存(ephemeral)生命周期为 5 分钟,务必让请求落在这个窗口内。

把可缓存内容放在 prompt 顶部

缓存按内容与位置共同生成 key。如果你把动态内容(用户消息、当前日期)放在 system prompt 之前,缓存就不会命中。把静态、大块内容放最前,把动态内容放最后。

大型稳定上下文使用 1 小时 TTL 的扩展缓存

标准短期缓存仅 5 分钟。如果你的上下文很大(完整的代码库索引)且变动不频繁,Anthropic 提供 1 小时 TTL 的扩展缓存,缓存写入价稍高、但每小时摊下来的读取价更低。对超过 10 万 token 的上下文非常划算。

在长 Claude Code 会话中缓存 CLAUDE.md 内容

Claude Code 会话中,CLAUDE.md 内容会前置到每条消息前。如果你的 CLAUDE.md 是 5,000 token,每个回合就额外计费 5,000 token。请把 CLAUDE.md 保持精简,并考虑把项目相关的细节拆到一个独立文件,仅在需要时引用,而不是每个回合都塞进去。

分类与路由任务交给 Haiku

Haiku 3.5 每百万输入 token 0.25 美元,而 Sonnet 4.5 是 3 美元。本质是模式匹配的任务(分类错误、归类工单、判断文本是否符合若干条件),Haiku 与 Sonnet 质量相当,价格只有 1/12。请清点你的子代理 —— 任何"3 回合上限 + 分类式输出"的子代理,都应当跑在 Haiku 上。

仅在需要推理时才用 Sonnet

Sonnet 在以下场景值得多花的钱:代码评审、安全审计、多步推理、需要综合相互冲突信息的任务。它在以下场景不值这个价:文档生成、变更日志、结构化数据抽取,以及任何输出格式确定的工作。

给每个代理设保守的 max_tokens

API 按生成 token 计费,而非请求 token。但当你预留过高的 max_tokens 时,Claude 可能会生成超出实际需要的输出。对结构化输出(JSON、YAML、表格),较低的 max_tokens 还会迫使输出更精炼。请审视每个代理的实际产出长度,把 max_tokens 设为 p95 观测值的 120%。

长输出用流式;够用就提前取消

使用流式响应时,你可以在拿到足够信息后中途取消。API 对流式响应只按已生成的 token 计费,而非整个 max_tokens。对于"通常只需要长输出前一部分"的应用,流式 + 提前终止可削减 40–70% 的输出 token 成本。

Sonnet 能搞定的任务,别上 Opus

Opus 每百万输入 token 15 美元,是 Sonnet 的 5 倍。Opus 与 Sonnet 的质量差异在开放式创作与复杂多步推理上确实显著;但对编程任务、结构化输出和大多数开发者工作流,Sonnet 的质量与 Opus 持平,价格只有 1/5。默认上 Opus 之前,先做一次基准测试。

长会话漂到 5 万 token 之前先跑一次 /compact

Claude Code 的 /compact 命令会把会话上下文摘要化,再用压缩版替换原文。一段 10 万 token 的会话能压缩到约 5,000 token。任务连续性几乎无损,成本节省却非常显著。活跃会话每 2 小时跑一次。

用 Grep 与 Read 定向引导,别让 Claude 自己摸索代码库

没有指引时,Claude 为了理解上下文会读大量文件。先把它指向相关文件("读 app/api/users.ts 与 User 模型"),上下文消耗能下降一个数量级。让 Claude 读文件之前,先用 Grep 定位。

CLAUDE.md 控制在 300 行以内

CLAUDE.md 的每一行都会前置到 Claude Code 会话的每条消息前。3,000 行的 CLAUDE.md 大约给每回合多加 4,500 token;300 行的版本只多加约 450 token。3000 行 CLAUDE.md 问题一文详细说明了在不丢失覆盖度的前提下如何重构。

子代理工具权限收窄到刚好够用

一个能访问全部工具的子代理,迟早会用上全部工具。一个只配 [Read, Grep] 的子代理,无法启动 Bash 进程、把一个 10MB 的日志文件灌进上下文。工具范围限制既是成本护栏,也是安全护栏。

评审代理只接收 diff,不接收整文件

跑代码评审代理时,把 git diff HEAD~1 的输出而非整文件内容传给它。一个 2,000 行的文件里只有 40 行变更:传整文件要 2,000 token,传 diff 只要 200 token。对评审工作流而言,几乎总是 diff 就够。

非时效性工作负载一律走 Batch API

Anthropic Batch API 单 token 价比实时 API 便宜 50%。单批最多接受 10,000 个请求,24 小时内处理完。如果你的场景不要求 60 秒内出结果,Batch API 才是正确选择。文档分析、测试生成、变更日志撰写 —— 都是 batch 候选。

请求发往 API 之前先去重

如果你的应用可能对同一 prompt(完全相同的用户查询、完全相同的文档分析)发出两次请求,在调用 API 之前用本地哈希做一次比对。SHA-256(模型 + system_prompt + user_message)足以识别重复;把响应按哈希值缓存,后续命中即复用。高流量应用中 5% 的重复率,一个月下来就是显著的省幅。

同类请求合并为单个多文档 prompt

如果你需要对 20 份文档执行同一操作(摘要、分类、抽取),通常一次"多文档"请求比 20 次单文档请求便宜 —— 因为 system prompt 只付一次。请用实际 token 数学验证一下:批太大可能突破上下文上限,反而被迫拆分。

对相同的并发查询做请求合并(coalescing)

高流量应用中,多个用户可能同时触发同一个底层 API 调用(同一份报告、同一份分析)。请求合并的做法:当一个请求在飞行中时,后续的相同请求等待并复用首条响应。节省的 API 调用量与你的流量峰值形态成正比。

把 batch 任务排到非高峰时段以获得 Batch API 优先级

Batch API 的处理时长随 Anthropic 的负载波动。在低流量时段(UTC 02:00–08:00)提交的 batch,通常完成更快、价格不变。对 24 小时窗口的 batch 而言,凌晨提交、早上拿结果是一个稳定的节奏。

用 PreToolUse Hook 设单会话与单日预算上限

PreToolUse Hook 在每次工具调用之前触发。一段 30 行的 Hook 脚本读取 ~/.claude/projects/ 下当前会话的累计成本,超过 10 美元就中止 —— 足以拦下 Tokenocalypse 级别的事故。Hook 在 API 调用离开你的机器之前就已触发,没有比这更硬的拦截点。

所有子代理都设 max_turns

没有 max_turns 限制的子代理可以无限循环。多数代理设 max_turns: 10,任务简单且边界清晰的设 max_turns: 5。一个跑到 50 回合的失控子代理,代价是同任务规范子代理的 5–10 倍。

不仅看月度总账,还要对成本异常做日级告警

月度账单告警只能在 Tokenocalypse 事件已经造成损失之后才提醒你。日级成本告警(单日花费超过基线 2 倍时邮件或 Slack Webhook 通知)能在你来得及干预的时候提醒。Anthropic 控制台支持日级花费阈值告警,把它打开。

及时清理僵尸会话

一个开着不管的 Claude Code 会话,在它内部的子代理调用工具时仍会扣费。用 claude sessions list 查看活动会话,把不再使用的杀掉。在多名开发者共用的机器上,僵尸会话是显著且隐蔽的成本来源。