---
title: "Prompt cache 与上下文预算"
wiki: cli
category: "最佳实践"
slug: cache-and-context-budget
url: https://learnagent.wiki/cli/cards/cache-and-context-budget
tags: ["prompt cache", "上下文预算", "token", "Claude Code", "成本"]
last_updated: 2026-04-22
reading_time: 16
---

> > 写在前面：这张卡解决的不是"模型怎么变聪明"，而是"同一段对话，怎么少花一半的钱、少等一半的时间"。两个目标合在一起，本质上就一句话——**让模型尽量从缓存里读，而不是从头算**。

# Prompt cache 与上下文预算

> 写在前面：这张卡解决的不是"模型怎么变聪明"，而是"同一段对话，怎么少花一半的钱、少等一半的时间"。两个目标合在一起，本质上就一句话——**让模型尽量从缓存里读，而不是从头算**。

## 基础概念

### 什么是 prompt cache

Prompt cache（提示缓存）是模型厂商在推理侧加的一层"前缀复用"机制。它的思路非常朴素：**一次对话里，开头那一大段（system prompt、CLAUDE.md、工具定义、历史消息）几乎每轮都不变**，与其每次都让模型从头算一遍 KV cache，不如把这段前缀的中间状态存一会儿，下一轮直接挂回来。

Anthropic 的 Claude prompt cache 在 2024 年 8 月公测、2025 年正式 GA，现在是 Claude API 上最大的一个成本杠杆。它的关键参数（截至 2026 年 4 月）：

| 维度 | 取值 | 说明 |
|------|------|------|
| 默认 TTL | 5 分钟 | 每次命中自动续期，不另外计费 |
| 扩展 TTL | 1 小时 | 写入费用从 1.25× 提到 2× 基础输入价 |
| 写入价 | 1.25× 基础输入价（5 min）/ 2× 基础输入价（1 hr） | 写入比读多 25%~100% |
| 读取价 | 0.1× 基础输入价 | **缓存命中后只花十分之一** |
| 最小可缓存 token | Sonnet 4.6 = 2048；Opus 4.7 / 4.6 / Haiku 4.5 = 4096；Sonnet 4.5/3.7 = 1024 | 不到这个数静默不缓存，不报错 |
| 单请求最多 cache_control 断点 | 4 个 | 自动缓存额外占 1 个，留给开发者 3 个 |
| 工作区隔离 | 2026-02-05 起 cache 按 workspace 隔离（不再按 organization） | 多 workspace 团队需要重新评估命中率 |

为什么是 5 分钟？这是 Anthropic 在"GPU 显存成本"和"用户对话节奏"之间挑出来的一个折中——绝大多数交互式对话两轮之间间隔 < 1 分钟，5 分钟足够覆盖思考+打字的天然停顿；再长就要占用大量显存，定价就只能涨。

### 为什么 Claude Code 默认开 cache

Claude Code 是个"长会话、长前缀"的典型场景：CLAUDE.md 几十 KB、MCP 工具列表几十个、历史回合几十条——每条新消息上去前的前缀往往 50k~150k token。Claude Code 在底层 API 调用里**默认会自动放好 cache_control 断点**，把这部分变成可缓存前缀。这就是为什么社区博客经常出现「同样跑 30 分钟，账单从 $20 降到 $3」的截图——不是模型变便宜了，是命中率从 0% 拉到 90%+。

### 什么是上下文预算（context budget）

上下文预算说的是"这次对话里，**总共**能装多少 token"。它有两层口径：

- **物理上限（max context window）**：Sonnet 4.6 / Opus 4.7 现在都到 1M token；Sonnet 4.5、Sonnet 4 还是 200k。Claude Code 在 Max / Team / Enterprise 计划上默认会把 Opus 升到 1M 上下文。
- **可用预算**：物理上限 - 系统留白（auto-compact 阈值、安全余量、思考 token 预算）。Claude Code 会在接近窗口上限前触发 auto-compact，所以"实际能塞东西的部分"通常只有标称值的 70~80%。

把这两层和 prompt cache 放一起想，就能看清整张图：**预算决定你能装多少；cache 决定装的这些东西是不是几乎免费地复用**。两者一起优化才是省钱的正解。

```mermaid
flowchart LR
    A[新消息到达] --> B{前缀和上一轮<br/>是否完全一致?}
    B -->|是 + 距上次 < TTL| C[Cache HIT<br/>读价 = 0.1× 输入价]
    B -->|否，或前缀有改动| D[Cache MISS<br/>写价 = 1.25× 输入价]
    C --> E[模型生成回答]
    D --> F[把新前缀写入缓存<br/>下一轮可命中]
    F --> E
    E --> G{接近 context 上限?}
    G -->|是| H[auto-compact<br/>压缩历史, 整段重写 → 必然 cache miss]
    G -->|否| I[继续对话, 维持高命中率]
    style C fill:#d4f4dd
    style D fill:#fde2e2
    style H fill:#fff4cc
```

这张图里最容易被忽略的一格是 **H（auto-compact）**——压缩之后前缀整段被改写，下一轮 100% miss、需要重新写入缓存，是一次"隐性大额支出"。后面的"常见误区"会专门拆这点。

## 基础用法

### 1. 用 `/cost` 看真实账单和命中率

Claude Code 2.1.92 起 `/cost` 被重写过，会按模型分别给出：本次会话的输入/输出 token、cache write 与 cache read 的拆分、估算的美元开销，以及 rate-limit 占用。这是最快确认"cache 到底有没有在工作"的入口。

```bash
# 在 Claude Code 交互界面里直接输入
/cost
```

预期输出（Pro 用户）大致长这样：

```text
Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

Per-model breakdown:
  claude-opus-4-7
    Input:        12,430 tokens
    Output:        3,210 tokens
    Cache write:  86,540 tokens   (1.25× input)
    Cache read:  742,180 tokens   (0.10× input)   ← 这一行越大越好
```

判断命中率好不好的经验值：**cache read / (cache read + cache write + 普通 input) > 0.7** 就算良好；如果一直在 0.3 以下，多半是有人在频繁切话题或者 CLAUDE.md 经常被脚本改写。

> Max / Team / Enterprise 订阅用户的额度是包月的，`/cost` 数据不直接对应账单，这种场景看 `/stats` 更合适，但 cache 命中率字段一样有参考价值。

### 2. 用 `/context` 看上下文预算的占用

`/context` 会列出当前会话的 token 都被谁占了——CLAUDE.md、MCP 工具定义、对话历史、思考 token 各自占多少。它是回答"我离 auto-compact 还有多远"和"哪个 MCP server 把窗口吃掉了"的关键命令。

```bash
/context

# 预期输出（节选）
Context usage: 142,830 / 200,000 tokens (71%)
  System prompt + tools:  18,420 tokens
  CLAUDE.md:               4,310 tokens
  MCP tool definitions:   31,560 tokens   ← 偏大，考虑禁用未用 server
  Conversation history:   88,540 tokens
  Headroom before compact: ~57,170 tokens
```

把 `/context` 的产出塞进 statusline，可以在每条消息上方实时看到 token 消耗，省得每隔几轮手动敲一次（参见 `claude code statusline context` 配置）。

### 3. 在会话里"主动喂 cache"

Claude Code 默认已经会自动给前缀打 cache_control，但用户的对话节奏决定了命中率。两种典型节奏的差别：

```bash
# 反例：每条消息都让模型重新理解项目上下文
# （表面上每次都"补充背景"，其实都在 cache miss）
> 帮我看一下 src/auth/ 下的登录逻辑
> 我们项目用 Next.js 14 + Prisma，登录走的是 NextAuth.js
> 顺便帮我审查一下安全性，注意我们要符合 GDPR
> ……（每轮新背景信息插在最前面，把前缀打散）

# 正例：把背景信息一次性写到 CLAUDE.md，然后专注于本轮任务
> 看一下 src/auth/signin.ts，按 CLAUDE.md 里的安全规约审查
> 把发现的问题按严重程度列出来
> 第二条问题给一个最小修复 patch
# 前缀（CLAUDE.md + 工具定义 + 历史）几乎不变，每轮都命中
```

经验规则：**所有"几乎不变的项目背景"放 CLAUDE.md；所有"本次对话要用的临时上下文"放当前消息**。前者进缓存，后者算到本轮 input。

### 4. compact 与 cache 的"代价对换"

`/compact` 是把历史对话压缩成摘要再继续。它能把会话从 180k token 压回 30k，让你不撞 auto-compact，但**压缩当下会让前缀彻底改写，相当于丢掉所有缓存**。所以它是一次"用一次 cache miss 换接下来几十轮的低占用"的取舍。

```bash
# 在快撞 context 上限时主动 compact，并指定保留重点
/compact 保留最近 10 轮代码变更和当前任务的目标，丢掉早期探索性讨论

# 也可以在 CLAUDE.md 里固化压缩偏好
# Compact instructions
# When you are using compact, please focus on test output and code changes
```

判断 compact 时机的简单原则：**如果还能再撑 5 轮以上不撞 auto-compact，就别手动 compact**——cache 是按"前缀完全一致 + 5 分钟内"这两个条件命中的，每次 compact 都意味着接下来一整段时间都是新缓存，账单和延迟都会先抬一档。

## 同类工具对比

不同 CLI Agent 在 prompt cache / context 这条战线上的差异比想象中大，下面这张表只列三家最主流的厂商在 CLI 场景里的实际表现：

| 维度 | Claude Code（Anthropic） | Codex CLI（OpenAI） | Gemini CLI（Google） |
|------|--------------------------|---------------------|----------------------|
| Cache 触发方式 | 自动放 cache_control 断点（也允许显式） | 完全自动，不暴露任何控制 | 需要显式创建 `CachedContent` 对象（CLI 默认不开） |
| 默认 TTL | 5 分钟（可扩到 1 小时） | 5~10 分钟，闲时段会延长到 1 小时 | 1 小时（可自定义） |
| 最小可缓存 token | 2k(Sonnet 4.6) / 4k(Opus 4.7, Haiku 4.5) | 1,024 | 32,768 |
| 缓存读取折扣 | 输入价的 10%（≈ 节省 90%） | 输入价的 50% | 输入价的 25% |
| 是否对存储另外收费 | ❌ 不收 | ❌ 不收 | ✅ 按缓存大小 × 时长收存储费 |
| 命中率可见性 | `/cost`、`/context`、statusline | 无暴露，需要自己抓 API 响应里的 `cached_tokens` | 无暴露，需要自己读 SDK 返回 |
| 上下文窗口（CLI 默认模型） | Sonnet 4.6 / Opus 4.7 1M（Max+ 自动升 1M） | GPT-5 系列 200k~400k 不等 | Gemini 2.5 Pro 1M~2M |
| Auto-compact / 自动压缩 | 内置 auto-compact，可调 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`；也可手动 `/compact` | 默认无；超出窗口直接报错或丢老消息 | 内置长上下文，但无明确"压缩"动作；超长时由 SDK 截断 |

**核心区别一句话**：Anthropic 的策略是"显式缓存 + 大幅折扣"（90% off），适合 Claude Code 这种长前缀、自动布断点的场景；OpenAI 走"无感自动 + 中等折扣"路线，CLI 用户基本不用关心；Google 走"长 TTL + 收存储费"路线，更适合那种"一份大文档反复问几小时"的检索场景，CLI 里反而不是甜蜜点。

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为切话题不影响 cache | 切话题会导致前缀里多出一段新背景或多出一次 `/clear`，cache 命中链立即断掉。一个项目里如果连续聊三个不相关的小任务，建议每个任务起独立 session（`claude --rename` + `claude --resume`），不要都塞在一个会话里 |
| 以为 read 大文件无所谓 | 一次 `Read` 把 8000 行日志整个塞进对话，会让接下来每一轮都把这 8000 行作为前缀重新算（即便有 cache，也是写入价 1.25×；cache 过期之后还得再付一次写入）。改成"用 hook / grep 先过滤再读"是性价比最高的优化 |
| 以为 max context = 实际可用预算 | 物理 1M / 200k 是窗口上限；实际可用预算还要扣掉 system prompt、工具定义、auto-compact 留白、思考 token 预算。`/context` 报的"剩余 headroom"才是真预算 |
| 以为 `/compact` 是越早越好 | compact 自身会触发一次 100% cache miss + 全量重写，是有显著成本的。在还能撑 5 轮以上时主动 compact，反而是浪费 |
| 以为 cache TTL 永远 5 分钟 | 每次命中会自动续期；只有"5 分钟内一次都没读"才会过期。一段对话里 30 分钟连续操作，前缀其实可以一直在缓存里 |
| 以为 MCP 工具挂得越多越好 | MCP 工具定义会进入 system 前缀（即便每个工具仅几百 token），10+ MCP 服务挂上来很容易把工具定义膨胀到 30k token 以上，每轮都是固定开销。用 `/mcp` 关掉不用的，能让真正可用预算多出 15~30% |
| 以为 1M 上下文等于"随便塞" | 大窗口不会让单条 token 变便宜——cache miss 之后的每一个 token 都是按 1× 输入价算。1M 窗口的真正用途是"装得下大型代码库的关键文件 + 长时间不撞 compact"，不是"反正放得下就都塞进去" |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **省钱杠杆极大**：cache 读取只要 0.1× 输入价，长会话整体成本能压到没缓存场景的 20~30% | **命中条件苛刻**：前缀必须**逐字节一致**，CLAUDE.md 被脚本改一行、工具列表变一个、ttl 过期，全部 miss |
| **延迟也降一档**：cache 命中省掉 prefill 计算时间，长前缀会话首 token 延迟从几秒降到亚秒级 | **观察成本不低**：要理解 `/cost` 里 cache_write / cache_read 拆分，要看 `/context` 的细分占比，对新手不算友好 |
| **Claude Code 默认就开**：不用学协议、不用挂参数，自动放断点，自动续期 | **auto-compact 是隐性炸弹**：压缩瞬间清掉所有缓存，不少团队反复在长任务上踩这个坑 |
| **TTL 可扩到 1 小时**：长 agentic 任务（跑测试、等审查）期间不会把缓存等没了 | **1 小时 TTL 写入要 2× 基础价**：用得不对反而比 5min cache 更贵；要看任务节奏决定 |
| **多家厂商都有同类机制**：迁移到 Codex CLI / Gemini CLI 也能享受到（折扣比例不一样而已） | **跨 workspace 隔离**：2026-02 起 cache 按 workspace 隔离，组织内多 workspace 的命中率会下降，需要重新合并工作流 |

## 思考题

<details>
<summary>初级：为什么"在对话里频繁补充项目背景"反而比"一次性写到 CLAUDE.md"更费 token？</summary>

**参考答案：**

cache 命中的硬条件是"前缀完全一致 + 5 分钟内"。如果你每轮都在最新一条消息里补充背景，对模型来说每一轮的前缀都和上一轮不一样——更准确地说，**新加的背景信息会插在历史消息流的某个位置**，让从这条往后的所有内容跟之前缓存的版本对不上。

cache 用的是逐字节比对，对不上就只能从头写一份新缓存。本来 cache_read 价格是输入的 10%，结果一下子变成 cache_write 的 125%，**单价直接翻 12.5 倍**。

正确做法是把"几乎不变的项目背景"沉淀到 CLAUDE.md，让它进入会话的固定前缀；而每轮消息只写"本轮要做的事"。这样前缀稳定，每条新消息都能高命中。

</details>

<details>
<summary>中级：你正在做一个跑了 2 小时的重构任务，期间会反复让 Claude Code 读测试输出、改代码、再跑测试。怎么用 prompt cache + 上下文预算让这次任务尽量便宜？</summary>

**参考答案：**

按"开会前、开会中、开会后"三个阶段拆：

**开会前（设计 cache 友好的前缀）：**
- 把项目结构、规约、关键文件目录写进 CLAUDE.md，控制在 200 行 / 4k token 以内（一定要超过 Opus 4.7 的 4096 最小可缓存 token，否则白搭）。
- 关掉这次任务用不到的 MCP server（`/mcp`），让工具定义不要膨胀。
- 如果是 Opus 4.7 长任务、单轮间隔常常超过 5 分钟（要等测试），考虑显式声明 1h TTL：写入贵一倍，但命中率能涨非常多，整体收益正向。

**开会中（不打散前缀）：**
- 测试输出别整段贴进对话，用一个 PreToolUse hook 把它过滤成只剩 fail 的部分（官方文档给出过现成的 grep 例子）。
- 跑测试这种动辄几万行输出的事交给 subagent，让 verbose 输出留在子会话，主会话里只回一个摘要。
- `/context` 实时观察占用，接近 75% 时再考虑 `/compact`，同时给 compact 指令明确保留点（比如"保留当前 patch 的 hunks 和测试目标，丢掉早期探索过程"）。

**开会后（拆账）：**
- `/cost` 里 cache_read 占比应该明显大于 cache_write；如果不是，说明前缀变化太频繁，下次复盘哪一步把前缀打散了。
- 如果 1h TTL 写入价占比反而偏大，说明这次任务节奏没那么稀疏，下回降回 5min TTL 即可。

一句总结：**让前缀稳定、让 verbose 远离主会话、按节奏选 TTL，最后用 `/cost` 复盘**。

</details>

<details>
<summary>进阶：为什么 Anthropic 给出的 cache 读取折扣（10% 原价）比 OpenAI（50%）和 Gemini（25%）都激进得多？这种激进的定价对 CLI Agent 用户的策略意味着什么？</summary>

**参考答案：**

这是"产品定位 + 成本结构"两边一起决定的。

**产品定位侧**：Anthropic 把"长前缀、agentic 工作流"当作核心战略——Claude Code、Computer Use、Constitutional AI 评估这些场景共同点是"前缀很大、变化很慢"。给 cache 一个极激进的折扣，等于从定价层面把用户往这条路上赶：你越是把信息固化到 system / CLAUDE.md / 工具定义里，你越省钱。这跟 OpenAI 把 ChatGPT / Codex CLI 往"轻量交互、自动隐式优化"上推、Gemini 把 Vertex AI 往"长文档检索 + 收存储费"上推，是三种不同的定位。

**成本结构侧**：cache 读其实是把 KV cache 中间状态从显存里"挂回来"——主要消耗是显存占用和带宽，不是计算 FLOPs。一旦 GPU 利用率本来就高，多挂一个用户的缓存几乎是边际免费的。Anthropic 把折扣开到 10%，意味着他们已经把这部分成本摊薄到非常低。

**对 CLI Agent 用户的策略意味着**：

1. **CLAUDE.md 不再是"少写为好"**——只要它命中频率高，写得详细一点反而更便宜（前提是要超过 Opus 4.7 的 4096 最小可缓存 token）。
2. **工具定义沉淀到固定 system prompt**——MCP 工具定义会进入前缀，挂得稳定比挂得多更重要。
3. **会话节奏要顺着 cache 设计**——不要为了"开新话题更干净"频繁 `/clear`，能在同一会话里复用就复用，能用 `/compact` 续命就别新开。
4. **跑长任务考虑 1h TTL**——写入贵一倍，但只要命中超过 8 次就回本，agentic 工作流里非常常见。
5. **跨 workspace 工作流要改**：2026-02 起 cache 按 workspace 隔离，过去靠"组织内共享缓存"省钱的团队需要重新规划，把同一类长任务集中到一个 workspace。

更宏观地讲：**cache 折扣激进意味着"信息组织得好不好"开始直接对应"账单大不大"**。这跟过去"prompt 写得短就能省"的直觉不太一样——现在是"prompt 写得稳定（不变）才能省"。

</details>

## 参考资料

1. Anthropic Prompt Caching 官方文档：<https://platform.claude.com/docs/en/build-with-claude/prompt-caching>（查询日期 2026-04-22）
2. Claude Code 成本管理官方文档：<https://code.claude.com/docs/en/costs>（查询日期 2026-04-22）
3. Claude API 上下文窗口说明：<https://platform.claude.com/docs/en/build-with-claude/context-windows>（查询日期 2026-04-22）
4. Claude 模型定价：<https://platform.claude.com/docs/en/about-claude/pricing>
5. 1M context for Opus / Sonnet 4.6 GA 公告：<https://claude.com/blog/1m-context-ga>
6. OpenAI Prompt Caching 文档：<https://developers.openai.com/api/docs/guides/prompt-caching>
7. OpenAI Codex CLI 特性页（含自动 caching 行为）：<https://developers.openai.com/codex/cli/features>
8. 三家 prompt caching 横向对比：<https://dev.to/m_sea_bass/comparing-prompt-caching-openai-anthropic-and-gemini-2mfh>
9. 社区博客：Claude Code Token Optimization Full System Guide (2026)：<https://buildtolaunch.substack.com/p/claude-code-token-optimization>
10. Claude Code Context Buffer 33K-45K 问题分析：<https://claudefa.st/blog/guide/mechanics/context-buffer-management>

---
*Source: https://learnagent.wiki/cli/cards/cache-and-context-budget*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*