token-optimization

Token 优化 — Claude Code

概述

Claude Code 中 Token 消耗过多主要源于四个方面：

1. 缓存未命中 — 请求未缓存或缓存失效
2. 上下文膨胀 — 上下文窗口不必要地增长
3. 模型选择错误 / 推理力度不当 — 过度使用推理
4. 输入格式冗长 — 注入上下文的数据过于冗长

---

阶段 1：初始会话审计

开始任何工作前，运行以下两条命令：

/context   # Shows loaded MCPs and tokens already consumed
/plugin    # Lists active plugins

系统性操作：

• 禁用当前项目不需要的所有 MCP
• 禁用所有未使用的插件
• 一个项目 ≠ 一份全局配置 → 按项目自定义

实例：空会话中加载了 Canva + Gmail + Google Calendar MCP，首次敲击键盘前就已消耗 23,000 个 Token。

需检查的警示信号：

• 加载了超过 3 个 MCP
• 插件与当前工作无关
• 空会话中的基础 Token 数量 >10,000

---

阶段 2：缓存管理

原则

Claude Code 会缓存：系统指令（CLAUDE.md）、工具/MCP 列表和消息历史。会话期间的任何修改都会使此缓存失效，导致受影响的 Token 被重新计费。

必须遵守的规则

• 会话期间绝不添加工具、MCP 或模型。 请在开始前配置好所有内容，或在专用的设置会话中配置。
• 如果会话期间必须进行关键添加（大型技能、MCP、关键命令）：
  1. 压缩会话（/compact）
  2. 启动新会话，并以压缩后的摘要作为起点
• 将缓存视为 HTTP 缓存：更改某个标头会使其下游所有内容失效。

缓存失效层级

┌─────────────────────────────────────────────┐
│ BASE SYSTEM INSTRUCTIONS (CLAUDE.md + tools)│  ← Invalidated if tool added
├─────────────────────────────────────────────┤
│ SESSION STATE (project files, memory)       │  ← Invalidated if file changes
├─────────────────────────────────────────────┤
│ MESSAGE HISTORY                             │  ← Invalidated if message edited
│  msg 1 → msg 2 → msg 3 → ...                │     (invalidates everything after)
└─────────────────────────────────────────────┘

会导致缓存失效的操作：

操作	失效层	影响
会话期间添加 MCP	基础指令	非常高
添加工具（工具调用）	基础指令	非常高
修改 CLAUDE.md	基础指令	非常高
编辑历史中间的消息	消息历史（从该处开始）	中等
将新文件载入上下文	会话状态	中等

最佳会话策略：

1. Full configuration (MCP, tools, CLAUDE.md) → BEFORE starting
2. Work session → NEVER modify configuration
3. If modification needed → /compact → new session
4. Agents → context fork → isolated work → result only

有关缓存问题的技术详情，请参阅 references/cache-deep-dive.md。

---

阶段 3：上下文窗口优化

缩小默认上下文窗口

1M Token 的窗口很诱人，但也很危险：它会助长不良习惯，并让子 Agent 负担过重。

条件式建议：

• 小型/中型代码库 → 在 settings.json 中将上限设为约 200,000 个 Token：

  { "contextWindow": 200000 }
  

  （默认不会提交 — 使用本地文件）

• 超大型代码库 → 保持 1M，但要更加严格地优化下述实践。

RAM 类比：拥有 32GB RAM 并不意味着可以不良管理内存。限制窗口会促使人们养成更好的规范。

上下文分叉与隔离 Agent

Agent 在启动时会继承父级上下文。等待越久，它们启动时的负担就越重。

目标行为：

• 在分叉上下文中调用每个技能或 Agent（在参数中设置 context: fork）
• Agent 在独立窗口中工作 → 完成后只返回结果，而不是完整历史记录
• Agent 被销毁时，主上下文不会改变

适合隔离到子 Agent 中的系统性用例：

任务	隔离原因
网络搜索	访问过的页面的 Markdown 历史记录会污染主窗口
PDF / 音频转录	输出量大，放在主上下文中没有必要
规划 / 测试生成	工作耗时，有助于保持上下文整洁
代码库探索	原生 explore Agent（使用 IQ）已针对此任务进行优化

添加到 CLAUDE.md 的提示词：

For any web search, systematically delegate to isolated subagent.
Return only extracted relevant information, not full history.

压缩与回退

• 自动压缩：Agent 达到窗口容量约 80% 时触发。适合 Agent，不适合主会话。
• 回退（双击 Esc）：可以返回先前的对话并删除不必要的上下文分支。发现方向错误时立即使用。

---

阶段 4：模型与推理力度选择

推理投入

投入系统会围绕提示词循环，以验证回答质量。每轮 = 额外的 token。

情况	建议投入
清晰、定义明确的任务	中等（默认）
复杂推理、架构、设计	高
简单任务、已知命令	低 / 无（无需 think）

规则：如果你心里已经有清晰的答案，就使用 medium。让 Claude 与你一起思考，而不是代替你思考。

模型选择

• Claude Code 订阅 → 使用原生 Anthropic 模型（Sonnet / Opus）。不要使用代理。
  • Opus：尽管延迟较高，复杂任务仍优先使用
  • Sonnet：适用于快速任务和常见代码生成
• 代理到其他大模型（GLM、Kimi……）：仅在直接使用 SDK/API 时才相关，不适用于标准 Claude Code。代理不稳定且未经优化。

添加到 CLAUDE.md：

## Reasoning effort
- Simple task / known command → minimal effort, no `think`
- Design / architecture task → medium effort
- Complex unsolved problem → high effort only on explicit request
Never over-reason a simple task.

---

阶段 5：输入格式优化

浏览器自动化：优先使用 DOM，而不是屏幕截图

原生 Claude Code 浏览器 Agent 每一步都会截取屏幕截图 → 会消耗大量 token 和时间。

推荐替代方案：Stagehand / Agent Browser (Vercel)

• 直接操作 DOM（不可见，无需屏幕截图）
• 安装：打开新的 Claude Code 实例 → Install [stagehand URL]
• 结果：速度提升 10 倍，token 大幅减少

过滤冗长的 CLI 输出

git status、git diff 等命令的输出一旦注入上下文，就会变得极其冗长。

推荐工具：RTK（由法国开发者开发）

• 在命令输出注入上下文窗口前进行过滤

• 示例：git status 的输出从约 50 行缩减至约 5 行关键信息 → 该命令节省约 80%

• 全局安装：

  # Run in Claude Code
  npx rtk init --global
  

精简回答：Caveman Skill / CLAUDE.md

默认情况下，Claude Code 的回答非常冗长。大幅减少回答篇幅：

添加到 CLAUDE.md 的指令：

## Response style
Ultra-concise responses. Remove articles, politeness phrases, reformulations.
Get to the point. Format: short bullet points. No intro, no conclusion.

Caveman Skill（可在 GitHub 上获取，约 5 万颗星）：可直接集成到 CLAUDE.md 的现成指令。示例请参见 references/claude-md-templates.md。

明确指定文件路径

不要在命令中让 Claude 自行查找文件：

# ❌ Costly: Claude will list, explore, read
"Update project memory"

# ✅ Optimal: explicit paths in command
"Update ./docs/memory.md and ./CLAUDE.md with following items: ..."

记忆命令模板：

## Memory/Learning commands
`/learn` command: updates ONLY the following files:
- ./docs/project-memory.md
- ./CLAUDE.md (section "Project Context")
Do not scan other files unless explicitly instructed.

---

阶段 6：验证与监控

检查上下文消耗

实施优化后，进行验证：

/context    # Check current token count

成功标准：

• 基础会话 <5,000 个 token（仅启用必要的 MCP）
• 10 次交互后：<30,000 个 token
• 独立任务中，没有 Agent 超过 50,000 个 token

团队监控

对于需要跟踪消耗情况的团队：

• 本地仪表板工具（由参考文章作者创建）：显示会话、调用的模型及每个会话的 token 数
• 对管理者 / 负责人而言，比对独立开发者更有用
• 链接请参见下方参考资料

**有记录的具体结果：**通过这些优化，月支出从 $750 降至 $100（来源：参考视频中链接的文章）。

---

故障排查

优化后 token 数仍然很高

诊断步骤：

1. 运行 /context → 找出已加载的 MCP
2. 检查 settings.json → 确认 contextWindow 设置
3. 查看最近的命令 → 找出冗长的输出
4. 检查 Agent 派生情况 → 确认上下文分叉情况

常见解决方法：

• 禁用未使用的 MCP
• 为 git 命令添加 RTK 过滤
• 将研究任务交给子 Agent
• 如果代码库允许，调低 contextWindow

缓存频繁失效

诊断：

1. 检查是否在会话中途加载了技能
2. 确认 CLAUDE.md 没有发生变化
3. 查找会话中的工具新增情况

解决方法：

• 在会话开始时预加载所需的全部技能
• 锁定 CLAUDE.md 配置
• 使用专用的设置会话进行配置更改

Agent 消耗的 token 过多

诊断：

1. 检查 Agent 是否继承了臃肿的父级上下文
2. 确认 Agent 是否加载了不必要的 MCP
3. 查看 Agent 历史记录中是否有冗长的工具输出

修复方法：

• 提前启动 Agent（父级上下文更轻量）
• 使用 context: fork 参数
• 仅返回结果，而非完整的 Agent 历史记录

---

示例

示例 1：优化 token 的项目设置

用户说：“使用最佳 token 配置设置新项目”

操作：

1. 创建精简的 CLAUDE.md，其中包含简洁的回复指令
2. 根据代码库大小配置 contextWindow
3. 仅启用适用于项目类型的必要 MCP
4. 为 git 命令添加 RTK 过滤
5. 定义子 Agent 委派规则
6. 确认基础会话少于 5,000 个 token

**预期结果：**优化后的会话配置，并记录在项目 CLAUDE.md 中

示例 2：诊断 token 消耗过高的问题

用户说：“我的会话消耗了太多 token，请帮我诊断”

操作：

1. 运行 /context 审查当前状态
2. 检查已加载的 MCP 和插件
3. 查看近期命令输出是否冗长
4. 找出缓存失效模式
5. 生成优化建议
6. 按影响程度排序并实施修复

**预期结果：**找出根本原因、实施修复，并将 token 消耗降低 50–80%

示例 3：网络研究任务

用户说：“研究 React Server Components 的最佳实践”

操作：

1. 使用上下文分叉启动独立子 Agent
2. 子 Agent 执行网络搜索
3. 子 Agent 仅提取关键发现
4. 将摘要返回主上下文（而非完整搜索历史）
5. 主上下文接收约 500 个 token，而非约 5,000 个

**预期结果：**完成研究，相较于直接搜索节省 90% 的 token

---

参考资料

如需详细的技术信息：

• references/cache-deep-dive.md — 缓存行为和失效模式
• references/claude-md-templates.md — 可直接使用的 CLAUDE.md 配置块
• references/tools.md — 外部工具（Stagehand、RTK）设置指南

外部资源：

• Anthropic 提示缓存文档
• Stagehand 浏览器自动化
• RTK CLI 输出过滤器

---

质量检查清单

完成优化前：

• 基础会话少于 5,000 个 token
• 仅加载必要的 MCP
• CLAUDE.md 包含简洁的回复指令
• 已为研究任务配置上下文分叉
• 已为冗长命令安装 RTK 或同等过滤工具
• 已根据代码库大小适当设置 contextWindow
• 团队成员已接受缓存失效规则培训（如适用）