---
title: "Claude Code 成本优化实战：查、砍、保、控四步把 Token 账单打下来"
author: deletexiumu
pubDatetime: 2026-04-08T00:00:00+08:00
featured: false
draft: false
tags:
  - Claude Code
  - 教程
  - 效率
description: "Claude Code 成本优化四步法：CLAUDE.md 分层按需省 76% 固定输入，Prompt Cache 命中享 90% 折扣，加上预算护栏和使用习惯优化，附可直接复制的配置和 5 分钟体检清单。"
---

我的全局 CLAUDE.md 曾经把所有配置内联在一个文件里——服务器连接、数据库信息、Hive 配置、Notion 集成，加上规则和工作流指令，合计约 13,325 tokens。这意味着每次会话，无论我是在写代码还是问一个简单问题，Claude 都要先"读"完这一整坨指令，然后才开始干活。

后来我把参考资料拆到 `refs/` 目录，CLAUDE.md 只保留指针（"涉及相关任务时用 Read 读取 refs/xxx.md"），每会话固定加载降到约 3,225 tokens。**一次重构，每会话省掉 10,100 个输入 token，降幅 76%。**

这个数字让我意识到：Claude Code 的成本优化不是玄学，而是可以量化、可以操作的工程问题。本文把我实践过的优化手段整理成"查→砍→保→控"四步路径，每一步都有数据和可复制的配置。

---

## 第一步：查——先搞清楚 Token 花在了哪

不量就没法优化。Claude Code 提供了几个工具帮你看清账单。

### /cost：会话级成本快照

在对话中输入 `/cost`，会显示当前会话的 token 用量。v2.1.92 版本新增了 per-model 和 cache-hit breakdown，能看到每个模型分别消耗了多少，以及缓存命中的比例。API 用户可以直接看到成本；订阅用户（Pro/Max）的具体计费以订阅规则为准，但 `/cost` 同样适合分析用量结构。

关键看三个数字：**输入 token、输出 token、缓存命中 token**。缓存命中占比越高，说明你的用量结构越健康——缓存命中的输入 token 按 0.1x 计费，相当于打了一折。

### ccusage / cc-lens：历史趋势追踪

`/cost` 只看当前会话。要追踪历史趋势，需要第三方工具。

**ccusage** 是一个 CLI 工具，从本地 JSONL 日志分析 token 用量和成本：

```bash
npx ccusage@latest daily    # 按天统计
npx ccusage@latest monthly  # 月度汇总
npx ccusage@latest session  # 按会话分组
```

它会分别显示缓存创建和缓存读取的 token 数，支持 `--offline` 离线模式和 JSON 导出。

**cc-lens** 提供可视化 Dashboard，一条命令启动：

```bash
npx cc-lens
```

自动打开浏览器，展示 token 时间线、模型占比、缓存效率面板、session 回放等。数据每 5 秒刷新，适合挂在旁边当监控屏。

> *ccusage: [GitHub - ryoppippi/ccusage](https://github.com/ryoppippi/ccusage)*
>
> *cc-lens: [GitHub - Arindam200/cc-lens](https://github.com/Arindam200/cc-lens)*

### 输入 token 的三大来源

在看懂账单之前，先理解 token 从哪来：

**1. 持久规则**——CLAUDE.md 和 rules/ 目录中标记为自动加载的文件，每轮对话都会注入。Skills 按触发条件加载，refs/ 按需 Read。这部分是"月租"，砍一次受益永久。

**2. 对话历史**——上下文窗口里累积的消息。对话越长，每轮发送的 token 越多。

**3. 工具结果**——文件读取、Glob/Grep 搜索结果、MCP 服务器返回的数据。用 `/context` 命令可以查看各项占比，尤其注意未使用的 MCP 服务器是否在白白占用上下文空间。

---

## 第二步：砍——削减固定输入成本

固定输入是每轮都扣的"月租"。砍一次，后续所有会话都受益。

### CLAUDE.md 三层架构

我的实际配置分三层：

**顶层 CLAUDE.md**（每次会话必加载）——项目概览 + 核心规约，约 765 tokens。以下是节选：

```markdown
# Claude 全局指令

## 语言与风格
- 全局默认中文
- 使用简洁文言风格节省 token

## 全局规则（每次自动加载）
- 通用经验 → rules/lessons-learned.md
- Skill 开发偏好 → rules/skill-development.md

## 按需参考（涉及相关任务时用 Read 读取）
- 服务器信息 → ~/.claude/refs/servers.md
- 数据库连接 → ~/.claude/refs/database-connections.md
```

注意：`rules/` 里的文件放在 `~/.claude/rules/` 或项目的 `.claude/rules/` 目录下会被规则系统自动加载；`refs/` 里的文件只是文字指针，Claude 看到"用 Read 读取"这句话后才会主动去读，不会在启动时自动加载。

**rules/ 目录**（规则系统自动加载的文件）——按主题拆分，合计约 2,460 tokens：

| 文件 | 估算 tokens | 加载方式 |
|------|------------|---------|
| lessons-learned.md | ~1,600 | 每次自动加载 |
| skill-development.md | ~140 | 每次自动加载 |
| discernment.md | ~720 | 每次自动加载 |

**refs/ 目录**（纯按需加载，不涉及相关任务时零消耗）——6 个文件合计约 10,100 tokens：

| 文件 | 估算 tokens | 加载方式 |
|------|------------|---------|
| servers.md | ~2,400 | 按需 Read |
| database-connections.md | ~2,100 | 按需 Read |
| hive-connection.md | ~2,000 | 按需 Read |
| feishu-integration.md | ~1,700 | 按需 Read |
| gaussdb-ops.md | ~1,500 | 按需 Read |
| notion-integration.md | ~400 | 按需 Read |

对比一目了然：

| 方案 | 每次会话加载 tokens |
|------|-------------------|
| 全部内联 | ~13,325 |
| 分层按需 | ~3,225 |
| **节省** | **~10,100（76%）** |

关键操作就一句话：**把不是每次都用的内容从 CLAUDE.md 移到 refs/ 目录，然后在 CLAUDE.md 里写一行"涉及 XX 时用 Read 读取 refs/XX.md"。**

### 写作风格也是成本

CLAUDE.md 里的每个字都是 token。同样的规则，长短写法差异明显：

```markdown
# 冗长写法（~45 tokens）
When you are writing code, please make sure to use ES modules 
syntax (import/export) instead of CommonJS (require). 
This is important for consistency across the codebase.

# 精简写法（~15 tokens）
- 用 ES modules，不用 CommonJS
```

我在全局 CLAUDE.md 第一条就写了"使用简洁文言风格节省 token"——这条规则本身就是在省 token。

### 排除噪声文件

Claude Code 会索引项目文件，Glob/Grep 搜索时返回的无关结果都消耗 token。几种排除方式：

- **让 Glob 尊重 `.gitignore`**：默认情况下 Glob 会返回被 gitignore 的文件。设置环境变量 `CLAUDE_CODE_GLOB_NO_IGNORE=false` 可让 Glob 也排除 `.gitignore` 中的路径
- **`permissions.deny`**：在 `.claude/settings.json` 中配置 deny 规则，阻止 Claude 读取特定路径（硬性禁止）
- **禁用未用的 MCP 服务器**：用 `/context` 查看各 MCP 服务器占用的上下文空间，禁用不需要的

每次 Claude 本来要读 5,000 行 lock 文件的时候，这些规则就帮你省下了这些 token。

---

## 第三步：保——让 Prompt Cache 帮你打折

Prompt Cache 是 Claude API 的缓存机制：如果请求的前缀（系统提示 + 对话历史的前段）和上一次完全一致，这部分 token 按 **0.1x 计费**，即享受 90% 折扣。

对于 Claude Code 用户来说，这基本是"躺着省钱"——只要不频繁改动 CLAUDE.md 和系统配置，缓存更容易命中。但切换模型/effort、修改工具或 MCP 配置、超过 TTL 或前缀变化，都可能导致缓存 miss。

### 缓存命中的条件

- **前缀 100% 一致**：系统提示、工具定义、对话历史的前缀必须完全匹配
- **最小 token 数**：不同模型有不同门槛（Opus 4.6 / Haiku 4.5 为 4,096 tokens，Sonnet 4.6 为 2,048 tokens），未达门槛不会创建缓存
- **TTL**：默认 5 分钟，每次命中自动刷新。API 用户可通过 `cache_control.ttl` 延长到 1 小时，但写入成本从 1.25x 升至 2x

缓存定价一览（来源：[Anthropic 官方定价页](https://www.anthropic.com/pricing)）：

| 类型 | 倍率（相对 base input price） |
|------|-----|
| 5 分钟缓存写入 | 1.25x |
| 1 小时缓存写入 | 2x |
| 缓存命中/读取 | **0.1x** |

5 分钟缓存写入花 1.25x，**一次命中即回本**。

### 版本升级的隐藏红利

保持 Claude Code 版本最新，本身就是一种成本优化：

- **v2.1.72**：修复了 SDK `query()` 调用的缓存失效 bug。修复前，使用旧版 SDK 的 API 用户在该场景下输入 token 成本最高为修复后的 **12 倍**
- **v2.1.86**：移除工具描述中的动态内容，提升 Bedrock/Vertex/Foundry 用户的缓存命中率
- **v2.1.85**：启用 ToolSearch 时全局系统提示缓存生效（含 MCP 用户）
- **v2.1.90**：修复 `--resume` 恢复会话时首次请求因 deferred tools 导致的缓存完全未命中

一条命令确认版本：`claude --version`，确保 ≥ v2.1.72。

> *来源：[Claude Code 官方 Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)*

### Sub-agent 的成本真相

Claude Code 的子代理有三种执行模型，成本差异巨大：

- **Fork（普通 subagent）**——继承父上下文的字节级副本。社区源码分析认为 fork 可能复用主 agent 的缓存前缀，但实际效果以 `/cost` 或 ccusage 为准
- **Teammate（Agent Teams）**——各自维护独立上下文窗口，作为独立 Claude 实例运行。有开发者分析源码后估算，特定场景下 Agent Teams 约有 **7 倍 token 放大效应**
- **Worktree**——在独立 git worktree 中运行，同样维护独立上下文，成本特征与 Teammate 类似

结论很简单：**评估任务复杂度再决定是否用多代理。简单任务别开 team。**

> *来源：海外社区开发者的 Claude Code 源码分析*

---

## 第四步：控——预算护栏、习惯和工具

省 token 之外，还要防止"跑飞"。

### 预算护栏（print 模式 / API 自动化用户）

Claude Code 在 `-p`（print）模式下提供三个硬性控制：

```bash
# 单会话美元上限
claude -p --max-budget-usd 5.00 "your query"

# 限制最大交互轮次
claude -p --max-turns 3 "your query"

# 最小启动模式：跳过所有非必要加载项（hooks、LSP、插件同步、skill 扫描、自动记忆、CLAUDE.md、MCP 服务器发现）
claude --bare -p "your query"
```

`--bare` 模式到达 API 请求的速度比标准模式快约 14%（v2.1.83 数据），适合 CI/CD 脚本化调用场景。

### 思考深度控制（支持 extended thinking 的模型）

Opus 4.6 的思考 token 也是成本。两种控制方式：

**settings.json 全局设置**：

```json
{
  "effortLevel": "medium"
}
```

日常任务用 `medium`，复杂架构设计时再临时切 `high`。也可以在命令行用 `--effort low` 临时指定。注意 `effortLevel` 仅对支持 extended thinking 的模型生效（如 Opus 4.6）。

### 日常使用习惯（所有用户）

几个立刻见效的习惯：

**编辑原始消息而非追问**——Claude 每条新消息都会重新发送完整对话历史。一句"but can you also..."的追问，把整个历史又发了一遍。正确做法：回到原始消息编辑后重新生成，旧答案被替换而非堆叠，可显著减少重复 token 发送。

**手动检查点**——复杂任务中途用 `/compact` 主动压缩上下文。最佳时机是在上下文使用约 60% 时，此时 Claude 仍有完整访问权限，生成的摘要质量更高。我还写了一个 Hook，每 50 次工具调用自动提醒考虑 `/compact`：

```javascript
// suggest-compact.js 核心判断片段（非完整 Hook，需包装为 PreToolUse handler）
if (count === 50) {
  console.error(`[Compact] 50 次工具调用 — 如在阶段切换点，考虑 /compact`);
}
```

**换任务用 /clear**——不要在一个长会话里塞多个不相关任务。`/clear` 完全清除历史从零开始，`/compact` 总结历史但保留摘要。探索性会话（边想边问）和定向会话（目标明确直接执行）的 token 消耗差异可能非常大——明确范围再动手。

**用 /context 检查 MCP 噪声**——有时未使用的 MCP 服务器在白白占用上下文空间。禁用不需要的 MCP 服务器可能完全避免不必要的 compaction。

### Model-Mixing 策略（企业 / 团队用户）

当前推荐模型的 API 定价（来源：[Anthropic 官方定价页](https://www.anthropic.com/pricing)）：

| 模型 | Input ($/MTok) | Output ($/MTok) | Context Window |
|------|---------|----------|----------------|
| Haiku 4.5 | $1.00 | $5.00 | 200K |
| Sonnet 4.6 | $3.00 | $15.00 | 1M |
| Opus 4.6 | $5.00 | $25.00 | 1M |

简单任务（分类、摘要、格式化）路由到 Haiku，复杂推理和 agentic loop 用 Opus。Claude Code 内置了 `/model` 命令切换模型，也支持 `opusplan` 模式——计划阶段用 Opus 设计方案，执行阶段自动切换到 Sonnet 实现。

以 1M input + 100K output 的任务为例：

| 策略 | 总成本 |
|------|--------|
| 全用 Opus 4.6 | $7.50 |
| 全用 Sonnet 4.6 | $4.50 |
| 全用 Haiku 4.5 | $1.50 |
| Opus + 缓存命中 | $3.00 |

Batch API 额外提供 50% 折扣。极端组合（Batch + Cache）可将输入成本打到 **95% 折扣**——Opus 4.6 的 $5.00/MTok 降至 $0.25/MTok。具体叠加规则以官方文档为准。

> *来源：[Anthropic 官方定价页](https://www.anthropic.com/pricing)*

---

## 5 分钟成本体检清单

读完可以立刻做：

```
□ 跑一次 /cost，记录当前输入/输出/缓存命中比例
□ 升级到最新版本（claude --version 确认 ≥ v2.1.72）
□ CLAUDE.md 超过 1000 tokens？拆分到 rules/ 和 refs/
□ 确认 .gitignore 已排除 node_modules 等噪声目录
□ 安装 ccusage 开始追踪历史消耗趋势
```

---

## 成本对比总结

| 优化手段 | 节省效果 | 数据来源 | 难度 | 适用场景 |
|---------|---------|---------|------|---------|
| CLAUDE.md 分层按需 | 固定输入减少 76% | 个人实测 | 低 | 所有用户 |
| Prompt Cache 命中 | 命中部分享 90% 折扣 | Anthropic 官方定价 | 低 | 所有用户 |
| SDK cache bug 修复 | 修复前该场景最高 12x 浪费 | 官方 changelog | 低 | API 旧版用户 |
| 编辑原始消息 | 显著减少重复 token | 原理推导 | 低 | 所有用户 |
| --bare 模式 | 跳过非必要加载，启动快 14% | 官方 changelog | 低 | CI/CD 自动化 |
| effortLevel 降级 | 减少思考 token 消耗 | 官方文档 | 低 | 支持 effort 的模型 |
| Model-Mixing | Input 单价比 1:3:5（Haiku:Sonnet:Opus） | Anthropic 官方定价 | 高 | 企业/团队 |

---

## 相关阅读

- [Claude Code 上下文工程实战：从"碰运气"到"有体系"](/posts/context-engineering-in-practice/) — 上下文管理是成本优化的前置技能，理解上下文才能有效控制 token
- [Claude Code 装完之后，这 9 项设置让它从"能用"变"好用"](/posts/claude-code-essential-settings/) — 基础设置指南，包含 effortLevel 等配置的入门说明
- [踩坑实录：用国内模型跑 Claude Code 的缓存大坑](/posts/claude-code-cache-pitfall/) — Prompt Cache 的实际踩坑经验，与本文第三步互补