Claude Code Token消耗优化指南

- 一、现象描述
- - [1.1 总体数据](#1.1 总体数据)
  - [1.2 Token 分解](#1.2 Token 分解)
  - [1.3 头部会话异常](#1.3 头部会话异常)
- 二、根因分析
- - [2.1 缓存读取 3.3B 的本质](#2.1 缓存读取 3.3B 的本质)
  - [2.2 三大核心问题](#2.2 三大核心问题)
  - - [问题 1：AI Agent 死循环](#问题 1：AI Agent 死循环)
    - [问题 2：超长上下文不重置](#问题 2：超长上下文不重置)
    - [问题 3：全局代码库永久加载](#问题 3：全局代码库永久加载)
  - [2.3 模型选择加剧费用](#2.3 模型选择加剧费用)
- 三、诊断过程
- - [3.1 本地数据排查](#3.1 本地数据排查)
  - [3.2 项目规模分析](#3.2 项目规模分析)
  - [3.3 RTK 状态检查](#3.3 RTK 状态检查)
- 四、解决方案（可直接照搬）
- - [4.1 立即生效（今天完成）](#4.1 立即生效（今天完成）)
  - - [步骤 1：创建 `.claudeignore`（项目根目录）](#步骤 1：创建 .claudeignore（项目根目录）)
    - [步骤 2：配置 `settings.json`（全局）](#步骤 2：配置 settings.json（全局）)
    - [步骤 3：禁用 memory MCP](#步骤 3：禁用 memory MCP)
    - [步骤 4：启用 RTK Hook](#步骤 4：启用 RTK Hook)
  - [4.2 工作流调整（本周养成习惯）](#4.2 工作流调整（本周养成习惯）)
  - - [原则 1：短会话](#原则 1：短会话)
    - [原则 2：显式上下文](#原则 2：显式上下文)
    - [原则 3：模型降级](#原则 3：模型降级)
    - [原则 4：产物驱动](#原则 4：产物驱动)
    - [原则 5：并行模式选择](#原则 5：并行模式选择)
  - [4.3 项目级优化（可选，效果最佳）](#4.3 项目级优化（可选，效果最佳）)
  - - [创建 `PROJECT_SUMMARY.md`](#创建 PROJECT_SUMMARY.md)
- 五、验证清单
- 六、预期效果
- 七、常见问题
- - [Q1: RTK 安装后不在 PATH？](#Q1: RTK 安装后不在 PATH？)
  - [Q2: 禁用 memory MCP 后如何查看历史？](#Q2: 禁用 memory MCP 后如何查看历史？)
  - [Q3: 会话被强制清理怎么办？](#Q3: 会话被强制清理怎么办？)
  - [Q4: 如何确认 `.claudeignore` 生效？](#Q4: 如何确认 .claudeignore 生效？)
- 八、相关文件

一、现象描述

1.1 总体数据

指标	数值
总消费	$13,603.43
总会话数	300
总 Token 数	3.9B
平均消费/会话	$45.34

1.2 Token 分解

类型	数量	占比
输入	42.7M	1.1%
输出	9.5M	0.2%
缓存写入	622.0M	15.9%
缓存读取	3.3B	84.8%

1.3 头部会话异常

排名	会话 ID	日期	模型	Tokens	费用
1	3d0e69b0	4/21	opus-4-7	301.6M	$1,573
2	6d900f57	6天前	opus-4-7	125.2M	$670
3	d7d5b0fa	4/21	opus-4-7	179.2M	$638
4	478b4e2a	4/20	opus-4-6	63.0M	$521
5	77523f53	6天前	opus-4-7	130.9M	$465

关键发现：前 20 会话占总费用的 60%+，单会话最高达 301M tokens。

二、根因分析

2.1 缓存读取 3.3B 的本质

Claude Code 使用 Prompt Caching 机制：

历史上下文存入缓存
每次请求重复读取缓存
缓存读取按 token 计费，不是免费的

输入:缓存比 = 1:77，每输入 1 个 token，附带 77 个缓存 token。

2.2 三大核心问题

问题 1：AI Agent 死循环

无终止条件，自动自查、改代码、重试
Agent 来回调用工具，无限消耗 token
典型模式：出错 → 重试 → 再错 → 再试...

证据：会话 3d0e69b0 仅 36 条历史记录，却消耗 301M tokens，说明单轮携带上下文极大，存在内部循环。

问题 2：超长上下文不重置

一个会话使用多天，历史不断累积
每次提问携带全部历史 + 项目上下文
单轮输入可达几万 token

证据：

会话 3d0e69b0：36 条消息 → 301M tokens（单条平均 8M+）
缓存读取 3.3B vs 实际输入 42.7M = 77:1

问题 3：全局代码库永久加载

项目自动索引，每次请求注入全仓库代码
node_modules/、target/ 等依赖目录被索引
项目 750MB，实际源码仅 275KB

证据：

7161 个文件被索引，排除依赖后仅 428 个（94% 是垃圾）
CLAUDE.md + 项目规范 + 记忆 MCP 每次全量注入

2.3 模型选择加剧费用

模型	缓存读取单价	前 20 会话出现次数
opus-4-7	最高	6 次
opus-4-6	高	14 次
sonnet-4-6	中	少量

opus-4-7 缓存单价是 sonnet-4-6 的 3-5 倍，但 6 个会话却占总费用 40%+。

三、诊断过程

3.1 本地数据排查

bash 复制代码

# 检查历史会话数
grep -c "sessionId" ~/.claude/history.jsonl
# 结果：3258 条记录

# 找出最活跃的会话
grep "sessionId" ~/.claude/history.jsonl | sort | uniq -c | sort -rn | head
# 结果：最高单会话 58 条记录，但 token 消耗极高

# 检查计划任务（死循环嫌疑）
cat ~/.claude/scheduled_tasks.json
# 结果：无计划任务

# 检查记忆 MCP
ls ~/.claude/projects/*/memory/
# 结果：3 个项目有记忆文件，总计 32KB

3.2 项目规模分析

bash 复制代码

# 总项目大小
du -sh .
# 750MB

# 源码文件数
find . -type f \( -name "*.java" -o -name "*.ts" -o -name "*.vue" \) | wc -l
# 7161 个

# 排除依赖后
find . -type f ... -not -path "*/node_modules/*" ... | wc -l
# 428 个（排除 94%）

3.3 RTK 状态检查

bash 复制代码

where rtk
# RTK not in PATH

rtk gain
# No tracking data yet

rtk discover
# No hook installed

结论：RTK 已安装但未启用 hook，无法自动压缩上下文。

四、解决方案（可直接照搬）

4.1 立即生效（今天完成）

步骤 1：创建 `.claudeignore`（项目根目录）

文件路径：{项目根目录}/.claudeignore

gitignore 复制代码

# Dependencies
node_modules/
target/
dist/
build/
*.jar
*.war

# IDE
.idea/
.vscode/
*.iml

# Logs
logs/
*.log

# OS
.DS_Store
Thumbs.db

# Large generated files
*.min.js
*.min.css
*.map

# Docker volumes
data/

效果：排除 94% 无关文件，索引从 750MB 降至 ~200KB。

步骤 2：配置 `settings.json`（全局）

文件路径：C:\Users\{用户名}\.claude\settings.json

在根对象下添加：

json 复制代码

{
  "contextWindow": {
    "maxTokens": 100000,
    "autoClearThreshold": 0.85
  },
  "session": {
    "maxDurationMinutes": 120,
    "warnBeforeClear": true
  }
}

效果：

单会话上限 100K tokens
子代理默认使用 sonnet 模型（性价比最高）
2 小时强制重置会话

步骤 3：禁用 memory MCP

在 settings.json 中：

json 复制代码

{
  "disabledMcpServers": ["memory"]
}

效果：每次请求减少 ~8K tokens 注入。

步骤 4：启用 RTK Hook

前提：已安装 RTK（rtk --version 有输出）

4.4.1 确保 RTK 在 PATH（Windows 关键步骤）

Claude Code 的 Bash 环境不继承系统 PATH，必须在 settings.json 中显式配置：

json 复制代码

{
  "env": {
    "PATH": "C:\\nvm4w\\nodejs;D:\\rtk;%PATH%"
  }
}

注意：D:\rtk 是 rtk.exe 所在目录，不是文件路径。多个路径用 ; 分隔。

验证：

bash 复制代码

which rtk
# 应输出 /d/rtk/rtk

4.4.2 初始化 RTK

bash 复制代码

# 如果 rtk 在 PATH
rtk init -g

# 或绝对路径
D:\rtk\rtk.exe init -g

4.4.3 添加 Hook 到 settings.json

在 hooks.PreToolUse 数组最前面添加：

json 复制代码

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "rtk hook claude"
    }
  ]
}

常见陷阱 ：rtk init -g 可能生成嵌套结构，需手动修正：

json 复制代码

// ❌ 错误 --- 嵌套了一层 hooks
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "rtk hook claude"}]
    }]
  }
}

// ✅ 正确 --- 平级结构
{
  "matcher": "Bash",
  "hooks": [
    {"type": "command", "command": "rtk hook claude"}
  ]
}

4.4.3 验证 RTK

重启 Claude Code 后执行：

bash 复制代码

git status
rtk gain

应显示节省统计。

效果：自动压缩 Bash 命令输出，节省 60-90% tokens。

4.2 工作流调整（本周养成习惯）

原则 1：短会话

反模式	正模式
一个会话改 10 个文件	10 个会话，每会话 1-2 个文件
会话运行 8 小时	每 30-60 分钟 `/clear` 或重启
依赖历史上下文	每轮显式声明关键信息

操作：

大任务拆分为子任务
每子任务一个会话
会话结束后 /clear 或退出重进

原则 2：显式上下文

反模式	正模式
"看看代码库"	`@file src/api/module.ts`
"帮我改下登录"	"修改 `AuthController.login` 方法，添加验证码校验"
让 AI 自己找文件	直接提供文件路径

操作：

使用 @file 精确引用
提供具体的类名、方法名
减少 AI 的搜索范围

原则 3：模型降级

任务类型	推荐模型	理由
改配置、格式化、简单问答	haiku-4-5	最便宜
代码生成、重构、Debug	sonnet-4-6	性价比最高
复杂架构设计、深度推理	opus-4-7	必要才用

操作：

默认使用 sonnet-4-6
明确需要深度推理时才用 opus-4-7
简单任务用 haiku-4-5

原则 4：产物驱动

复制代码

会话 1：设计 API
  → 输出 `docs/api-design.md`

会话 2：实现后端
  → 读取 `docs/api-design.md`
  → 输出 Java 代码

会话 3：实现前端
  → 读取 `docs/api-design.md`
  → 输出 Vue 组件

操作：

每会话产出文件
下会话读取产物而非历史
减少上下文依赖

原则 5：并行模式选择

独立任务并行时，选择正确的并行模式：

模式	工具	适用场景	不适用
subagent 并行	`Agent` 工具，同消息发多个	后端/前端/SQL 同时改	需要代理间协作
team 协作	`TeamCreate` + 任务列表	大型重构、多阶段项目	简单独立任务
多终端并行	开多个 Claude Code 窗口	完全独立的模块开发	同文件修改

经验：

简单并行（A改后端、B改前端、C写SQL）→ 用 subagent，同一条消息发多个 Agent 调用
复杂项目（10+文件重构，需代理间协调）→ 用 team 模式，共享任务列表
避免多会话同时改同一个文件，防止冲突

示例 --- subagent 并行：

json 复制代码

// 同一条消息中并行启动
{"description": "后端接口", "prompt": "实现 License 多 MAC 后端..."}
{"description": "前端页面", "prompt": "实现 License 多 MAC 前端..."}
{"description": "SQL脚本", "prompt": "写数据库迁移脚本..."}

4.3 项目级优化（可选，效果最佳）

创建 `PROJECT_SUMMARY.md`

文件路径：{项目根目录}/PROJECT_SUMMARY.md

markdown 复制代码

# {项目名} 摘要

## 架构
- 前端: {技术栈}
- 后端: {技术栈}
- 构建: {工具}

## 关键目录
- `src/api/` - API 层
- `src/views/` - 页面
- `src/service/` - 业务逻辑

## 常用命令
npm run dev      # 启动开发
npm run build    # 构建

## 最近改动
- {简要描述}

效果：替代自动索引，每次请求减少 20-50K tokens。

五、验证清单

完成所有配置后，逐项检查：

六、预期效果

指标	优化前	优化后	节省
月均费用	$13,603	~$3,000-5,000	65-75%
缓存读取/请求	50-100K	10-30K	70%
单会话最大	301M	<10M	97%
项目索引大小	750MB	~200KB	99.9%

七、常见问题

Q1: RTK 安装后不在 PATH？

A: 分两步解决：

在 settings.json 的 env.PATH 中添加 RTK 目录：

json 复制代码

{
  "env": {
    "PATH": "C:\\nvm4w\\nodejs;D:\\rtk;%PATH%"
  }
}

hook 中直接用 rtk（不用绝对路径）：

json 复制代码

{
  "matcher": "Bash",
  "hooks": [{"type": "command", "command": "rtk hook claude"}]
}

原因：Claude Code 的 Bash 环境不继承 Windows 系统 PATH，必须通过 settings.json 的 env.PATH 注入。

Q2: 禁用 memory MCP 后如何查看历史？

A: 手动读取记忆文件：

复制代码

Read ~/.claude/projects/{项目}/memory/MEMORY.md

Q3: 会话被强制清理怎么办？

A: 这是预期行为。大任务拆分为多会话，用产物文件交接。

Q4: 如何确认 `.claudeignore` 生效？

A: 执行：

bash 复制代码

find . -type f -name "*.js" | wc -l
# 应大幅减少（排除 node_modules 后）

八、相关文件

文件	路径	说明
本指南	`docs/token-optimization-guide.md`	优化完整方案
项目摘要模板	`PROJECT_SUMMARY.md`	按需创建
忽略配置	`.claudeignore`	项目根目录
全局配置	`~/.claude/settings.json`	Claude Code 配置
RTK 文档	`~/.claude/RTK.md`	RTK 使用说明

Claude Code Token消耗优化指南

目录

一、现象描述

1.1 总体数据

1.2 Token 分解

1.3 头部会话异常

二、根因分析

2.1 缓存读取 3.3B 的本质

2.2 三大核心问题

问题 1：AI Agent 死循环

问题 2：超长上下文不重置

问题 3：全局代码库永久加载

2.3 模型选择加剧费用

三、诊断过程

3.1 本地数据排查

3.2 项目规模分析

3.3 RTK 状态检查

四、解决方案（可直接照搬）

4.1 立即生效（今天完成）

步骤 1：创建 .claudeignore（项目根目录）

步骤 2：配置 settings.json（全局）

步骤 3：禁用 memory MCP

步骤 4：启用 RTK Hook

4.2 工作流调整（本周养成习惯）

原则 1：短会话

原则 2：显式上下文

原则 3：模型降级

原则 4：产物驱动

原则 5：并行模式选择

4.3 项目级优化（可选，效果最佳）

创建 PROJECT_SUMMARY.md

五、验证清单

六、预期效果

七、常见问题

Q1: RTK 安装后不在 PATH？

Q2: 禁用 memory MCP 后如何查看历史？

Q3: 会话被强制清理怎么办？

Q4: 如何确认 .claudeignore 生效？

八、相关文件

步骤 1：创建 `.claudeignore`（项目根目录）

步骤 2：配置 `settings.json`（全局）

创建 `PROJECT_SUMMARY.md`

Q4: 如何确认 `.claudeignore` 生效？