---
title: "Token caching"
description: "Gemini CLI token caching 的作用：减少重复上下文成本、提升长任务性能，以及使用前需要理解的边界。"
verifiedAt: "2026-05-09"
---

Token caching 用来减少重复上下文带来的成本或延迟。它适合长会话、重复读取大上下文、脚本化任务。

> [!IMPORTANT]
> Token caching 受认证方式影响。API key 和 Vertex AI 场景可用；OAuth / Code Assist API 场景不要把 cached token 当成必然存在。

官方文档里的限制很关键：token caching 只在 API key 认证或 Vertex AI 场景下可用。OAuth 用户，包括 Google Personal / Enterprise 账号走的 Code Assist API，目前不支持 cached content creation。

## 适合场景

- 多轮围绕同一大项目。
- 反复读取同一批文档。
- CI/headless 中重复上下文。
- 长时间任务需要稳定性能。

## 它缓存什么

Token caching 的目标不是缓存最终答案，而是复用前面已经处理过的系统指令和上下文。这样后续请求不需要重复为同样上下文付完整处理成本。

官方页面没有给出统一 TTL 或永久缓存承诺，所以教程里不要写“缓存会保留多久”。更稳的写法是教读者看 `/stats`，确认当前认证方式下是否真的出现 cached token。

适合缓存的内容通常是：

- 稳定系统指令。
- 项目规则。
- 长期不变的上下文。
- 多轮任务反复引用的文件摘要。

不适合依赖 caching 的内容包括实时日志、临时错误输出、频繁变化的 diff 和一次性输入。

| 内容 | 是否适合 caching | 原因 |
| --- | --- | --- |
| 项目规则 / system instructions | 适合 | 稳定且重复出现 |
| 长文档和 schema | 适合 | 多轮任务会重复引用 |
| 当前 diff | 不适合 | 变化快，容易误用旧上下文 |
| 测试失败日志 | 不适合 | 每次运行都可能不同 |
| 构建产物和依赖目录 | 不适合 | 应先 ignore 或裁剪 |

## 不适合把它当万能解法

如果任务描述混乱、项目规则缺失、验证命令不清楚，token caching 也救不了。先把上下文结构和任务边界做好。

也不要把 caching 理解成“所有 token 都免费”。它只是减少重复处理成本，不能替代上下文裁剪。

## 如何查看效果

在 Gemini CLI 会话里使用 `/stats` 查看 token usage。当 cached token 可用时，stats 输出里会显示相关节省情况。

如果 `/stats` 看不到 cached token，先确认当前认证方式是不是 Gemini API key 或 Vertex AI。如果你是 OAuth 登录，缺少 cached token 信息是预期行为。

这也是为什么团队复盘成本时要记录认证方式。

如果团队成员分别使用 OAuth、API key 和 Vertex AI，同一篇教程里的 caching 截图可能完全不同。商业教程建议把认证方式写在截图说明里，否则读者会以为自己配置错了。

## 成本优化建议

- 用 `.geminiignore` 排除构建产物、依赖目录、日志和大文件。
- 自动化任务要记录 `/stats`，否则很难判断成本变化来自缓存、模型切换还是上下文变化。
- 先减少无关上下文，再考虑 token caching。
- 团队场景要统一认证方式，否则不同成员看到的 caching 行为可能不同。

## 验证步骤

先准备一个稳定的大上下文任务，例如读取同一组 docs 或 schema。第一轮运行后看 `/stats`，第二轮用同一认证方式、同一模型和同一上下文再运行一次，再比较 cached token 是否出现。中间不要改 `GEMINI.md`、settings、模型或输入文件，否则你无法判断变化来自缓存还是输入漂移。

如果第二轮仍看不到 cached token，不要继续改 prompt。先确认认证方式、官方支持范围、模型是否支持 cached content creation，再判断是否需要改成本优化策略。

## 接下来去哪

<Cards>
  <Card title="ACP mode" description="继续看 IDE / 工具链通过协议控制 Gemini CLI 的运行方式。" href="/docs/gemini-cli/official/05-models-runtime/55-acp-mode" />
  <Card title=".geminiignore" description="缓存前先裁剪不该进入上下文的文件。" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="Quota and pricing" description="成本优化要和 quota、模型选择、认证方式一起看。" href="/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
</Cards>

## 官方来源

- [Gemini CLI token caching](https://google-gemini.github.io/gemini-cli/docs/cli/token-caching.html)
- [Gemini CLI token caching source](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md)
- [Gemini CLI core](https://google-gemini.github.io/gemini-cli/docs/core/)
