Token caching
Gemini CLI token caching 的作用：减少重复上下文成本、提升长任务性能，以及使用前需要理解的边界。
Token caching 用来减少重复上下文带来的成本或延迟。它适合长会话、重复读取大上下文、脚本化任务。
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，再判断是否需要改成本优化策略。
接下来去哪
ACP mode
继续看 IDE / 工具链通过协议控制 Gemini CLI 的运行方式。
.geminiignore
缓存前先裁剪不该进入上下文的文件。
Quota and pricing
成本优化要和 quota、模型选择、认证方式一起看。