Claude Code Token 成本优化：从上下文管理到工程配置

很多人第一次用 Claude Code 的感受是“惊艳之后，账单疼”。

在 AI 编程工具已经逐渐普及的当下，Claude Code 这类终端 Agent 工具的价值并不难理解——它把“你写代码”变成“你指挥 Agent 写代码”，甚至在多文件改造、测试补全、重构等任务上能一口气完成多个步骤。但随之而来的问题也很现实：每一次交互都在消耗 Token，每一次“让它再改一下”都可能意味着几千甚至上万 Token 的额外开销。如果不加控制，一次看似简单的功能调整，最终消耗可能远超预期。

这篇文章的主要目的不是教你“怎么省到极致”，而是帮你建立一套可执行的 Token 成本管理方法。我会先拆解 Claude Code 的 Token 都花在了哪里，再给出环境准备、配置优化、代码实现和验证手段，最后补充常见的成本陷阱和工程建议。你会得到一套“从工具使用习惯到项目工程配置”的完整优化思路，而不是零散的小技巧。

1. Token 消耗的真实构成：钱到底花在哪里

在谈优化之前，必须先搞清楚一个关键问题：Claude Code 生成一次回复，Token 成本由哪些部分组成？

从成本构成看，一次会话的成本并不是“你输入了多少字 + AI 输出了多少字”这么简单。Claude Code 作为一个终端 Agent，它背后至少发生了这些消耗：

• 系统提示词（System Prompt）：Agent 工具内置的指令序列，用于定义角色、行为边界、工具调用规则。这部分每次请求都会随请求发给模型，是固定开销。
• 对话历史（Context）：你与 Agent 之间过往的问答、代码片段、终端输出，都会作为上下文继续发送。对话越长，开销越大。
• CLAUDE.md 记忆文件：Claude Code 会把项目根目录和用户目录下的 CLAUDE.md 自动注入上下文，作为长期记忆。
• 工具调用与工具结果：Agent 读取文件、搜索代码、运行命令时，工具返回的内容会被塞进上下文。
• 模型输出（Completion）：模型生成的文本、代码、工具调用指令。

本质上是“一个不断增长的上下文窗口，每次请求都要重新发送一次历史内容”。这意味着成本不是线性增长，而是随着对话轮次变长而加速增长。这也是为什么单纯靠“省着点用”无法根治问题，必须从工程层面控制上下文膨胀。

在正式进入优化手段前，有一个判断值得明确：Token 成本优化不是让你少用 AI，而是让你每一次请求携带更少的无用上下文，同时让 Agent 更少地犯错、更少地返工。一次准确的调用，远胜过十次“近似正确”的折腾，后者不仅费 Token，还费时间。

2. 优化的核心思路：并不是所有 Token 都值得省

聊成本优化，最怕陷入“唯 Token 论”。如果你把文章读到这里，建议先建立一个全局优化观：优先减少无意义 Token，而不是压缩必要信息。

哪些 Token 属于“无意义”？

• 已经读完但不再需要的文件内容残留在上下文中。
• 项目里大量无关文件的扫描结果。
• 过长的对话历史中反复出现的旧版本代码。
• 没有明确目标的“闲聊式”指令，导致 Agent 反复试探性生成。

真正的优化体现在三条路径上：

1. 输入侧压缩：减少注入上下文的文件内容、压缩历史、缩小任务范围。
2. 输出侧控制：通过设置最大输出 Token、要求精简回答，减少无关生成。
3. 缓存复用：利用 Anthropic 的 Prompt Caching 机制，让相同前缀内容在短时间内不必重复计费。

不过这里要明确一点：Prompt Caching 是 API 层面的机制，Claude Code 是否在内部自动启用、不同套餐的计费口径如何，需要以官方文档和实际账单为准。 更稳妥的做法是，在项目层面主动减少每次都完整传输的大文件，这样无论缓存机制如何，你都不会额外吃亏。

基于这套思路，下面从环境准备开始，逐步落地。

3. 环境准备与基础配置

3.1 安装与鉴权

Claude Code 的安装方式在不同阶段可能有调整，官方普遍建议通过 npm 安装：

bash复制npm install -g @anthropic-ai/claude-code

安装完成后，需要配置 API 访问凭证。如果你使用的是 Anthropic API，需要设置环境变量：

bash复制export ANTHROPIC_API_KEY=你的Key

在 Windows 环境可以执行：

powershell复制$env:ANTHROPIC_API_KEY="你的Key"

如果你使用的是其他兼容 Claude API 的服务，则可能需要额外配置 ANTHROPIC_BASE_URL 指向对应的接口地址。这个变量用于修改 API 请求的 Base URL，具体值以服务商提供的为准。

3.2 确认版本与配置目录

运行以下命令验证安装是否成功：

bash复制claude --version

配置信息通常存储在用户主目录下的 .claude 目录中，项目级配置则位于项目根目录的 .claude 目录。实际项目中可能存在多个版本的配置管理方式，建议以 claude --help 的输出为准。

关键文件有三类：

3.3 理解 settings.json 的基础能力

.claude/settings.json 是一个官方支持的配置文件，可以用来控制权限、环境变量等行为。下面是一个典型的结构示例：

json复制{
  "permissions": {
    "allow": ["Read", "Glob", "Bash(claude --version)"],
    "deny": ["Bash(rm -rf *)"]
  },
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "4096"
  }
}

权限配置的意义不只是在安全层面，它也影响 Token 效率：如果你明确限制了 Agent 可以执行哪些命令，它就不需要反复向用户确认，减少了“请求确认”这一来回的上下文轮次。确认交互看起来不费多少 Token，但一次误操作导致的级联步骤往往比想象中更贵。

4. 利用 CLAUDE.md 注入高质量约束

CLAUDE.md 是 Claude Code 中提升输出质量、同时控制成本的最直接手段。

它的原理是：在每轮对话开始时，Claude Code 会把 CLAUDE.md 的内容注入上下文，相当于给 Agent 一份“项目操作手册”。如果你的手册写得好，Agent 第一次生成的代码就接近预期，返工次数大幅下降；如果你的手册是流水账，Agent 会频繁追问项目背景，或者给出与项目结构不一致的方案。

一个经济且高效的 CLAUDE.md 应该包含下面几个部分：

• 项目简介：用三到五行说明项目是什么、技术栈、目录结构。
• 命令规范：如何安装依赖、如何运行测试、如何构建。
• 代码风格约定：命名风格、错误处理方式、组件组织方式。
• 禁止事项：不要修改哪些文件、不要动哪些目录。

不要把所有信息都塞进去。CLAUDE.md 越长，每轮请求的系统级开销就越大。 它应该是“高频、稳定、能减少返工”的信息，而不是“把整个 README 抄一遍”。

示例：

markdown复制# 项目记忆

## 技术栈
- Python 3.11 + FastAPI
- PostgreSQL 15
- 前端使用 React + Vite

## 常见命令
- 依赖安装：pip install -r requirements.txt
- 启动开发服务：uvicorn app.main:app --reload
- 运行测试：pytest tests/

## 代码约定
- 所有 API 路由放在 app/routes/ 目录下
- 数据库操作用 SQLAlchemy 2.x 语法
- 禁止直接修改 migrations/ 下的历史迁移文件

## 当前任务上下文
- 正在实现订单导出接口，相关模型在 app/models/order.py

特别注意“当前任务上下文”这个区域。在实际项目中，与其频繁切换任务让 Agent 每次都重新理解上下文，不如在做大任务前把相关文件路径和背景写进 CLAUDE.md，完成后再清理。 这个技巧对长任务的 Token 节省非常明显，因为 Agent 不需要反复去搜索代码库。

5. 控制文件读取与上下文膨胀

Claude Code 的 File 读取类工具会在需要时读取文件内容，但问题在于：一次大型重构会让 Agent 反复读取多个文件，而这些文件的全部内容都会留在对话历史的上下文里。 即使后续不再需要某个文件，只要对话没有清空，这个文件的内容就会持续占用 Token 预算。

5.1 尽量让 Agent 只读取代码的关键片段

在提问时，用清晰的指令约束读取范围。比如：

code复制请阅读 src/services/order_service.py 中 get_order 函数，然后基于这个函数新增一个批量查询接口。

相比“帮我在订单服务里新增一个批量查询接口”，这种说法的优势是：Agent 不需要经过多轮搜索、读多个文件来定位目标代码。搜索和文件读取本身不可怕，可怕的是它读了一大堆文件后，其中大部分内容都不是你需要的。

5.2 用 ignore 规则过滤噪音

Claude Code 天然会遵守一些项目配置文件中的忽略规则。如果你的仓库里有大量构建产物、锁文件、日志文件，应该保证它们不会被 Agent 扫描。常见的做法是确认 .gitignore 覆盖这些目录，同时可以在 .claude/settings.json 中通过权限的 deny 规则限制某些文件的操作。

5.3 谨慎使用“全库扫描”类指令

“帮我找一下所有用到这个函数的位置”这类指令会触发大量路径搜索和文件读取。对于大型代码库，这个操作的 Token 成本可能高到让你意外。更经济的做法是：

code复制请先只搜索 src/ 目录下 import 了 order_export 的 Python 文件，列出文件路径和行号，不要读取完整内容。

搜索路径和行号的开销远小于读取所有文件内容。

6. 用好 /clear、/compact 与任务拆分

Claude Code 提供了一些会话管理命令，正确使用它们可以在维持上下文质量的前提下大幅削减历史 Token。

这里有一个许多新手容易犯的错误：总是让 Agent 在同一会话里连续完成两个毫无关联的功能。 上一个功能的所有对话历史会成为下一个功能的无用开销。更合理的方式是完成一个功能点后执行 /clear，再进入下一个功能点。

另一个常见误解：/compact 不是万能的。压缩会丢失部分细节，如果压缩后的摘要没有保留关键文件的路径和决策原因，后续效果可能反而变差。所以压缩前越早建立 CLAUDE.md 中的“当前任务上下文”，压缩后继续工作的损耗就越小。

7. 通过配置与命令限制输出体量

除了控制输入，输出侧也可以做限制。

7.1 设置最大输出 Token

Claude Code 支持通过环境变量 CLAUDE_CODE_MAX_OUTPUT_TOKENS 控制单次输出的最大 Token 数量。例如：

bash复制export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2048

设置之后，输出会被截断到指定长度。如果任务是一个小函数改造，2048 基本够用；如果任务是大段代码生成，这个限制可能反而不利于完成。建议不要设置到低于 1024，否则会频繁出现截断，反而导致返工。

7.2 在指令中明确要求的输出格式

有些 Agent 默认会输出解释性文字，这些文字也会消耗 Token。你可以通过指令压缩这部分开销：

code复制请直接给出修改后的代码，并只列出三行以内的差异说明，不要展示分析过程。

对于“代码审查”类任务，可以要求：

code复制请列出问题清单，每条问题一行，格式为：文件路径:行号 - 问题描述 - 建议。

输出格式约束的直接收益是让生成内容更紧凑，间接收益是后续对话中这些精简内容占用的历史空间更小。

7.3 合理选择模型

如果你是 API 计费用户，不同模型的单价差异是客观存在的。Claude Code 通常可以通过环境变量指定模型：

bash复制export ANTHROPIC_MODEL=claude-3-5-haiku-latest

不同模型的推理能力不同、价格不同。如果任务只是改几行配置、写一个简单的脚本，用高配模型等于花冤枉钱；但如果任务是复杂架构设计，用低配模型可能导致反复失败，那才是真正的浪费。选择模型是在“能力”和“成本”之间寻找平衡点，不是无脑买最贵的，也不是一味省到最便宜。

8. 一个完整的优化实战示例

下面用一个典型场景来串起前面的优化手段：给一个 FastAPI 项目新增一个“订单批量导出”接口。

8.1 项目结构

code复制order-service/
├── app/
│   ├── main.py
│   ├── models/
│   │   └── order.py
│   ├── routes/
│   │   └── order.py
│   ├── services/
│   │   └── order_service.py
│   └── schemas/
│       └── order.py
├── tests/
│   └── test_orders.py
└── CLAUDE.md

8.2 第一步：写好 CLAUDE.md

在项目根目录创建 CLAUDE.md：

markdown复制# 订单服务项目

## 技术栈
- Python 3.11 + FastAPI
- SQLAlchemy 2.x + PostgreSQL
- Pydantic v2

## 命令
- 启动：uvicorn app.main:app --reload
- 测试：pytest tests/ -v

## 约定
- 路由只负责参数校验和响应，业务逻辑放 services/
- 所有数据库查询使用 async session
- 使用 app/schemas/ 下的 Pydantic 模型定义请求响应

## 当前任务
- 为订单服务新增批量导出接口
- 订单模型位于 app/models/order.py
- 已有订单查询逻辑位于 app/services/order_service.py

这样 Agent 的第一轮请求就携带了足够少但足够准确的背景信息，它会沿着正确路径动手，而不是到处搜索。

8.3 第二步：启动会话并下发精准任务

执行：

bash复制claude

然后在交互中输入：

code复制请实现订单批量导出接口：
1. 参考 app/services/order_service.py 中的 get_order 方法，新增 export_orders 方法，支持按订单 ID 列表批量查询。
2. 在 app/routes/order.py 中新增 POST /orders/export 端点，接收 {"order_ids": []}。
3. 返回 CSV 格式内容，不落库。
4. 只修改上述两个文件，不要改动 models 和 schemas。
5. 修改后执行 pytest tests/test_orders.py -k export 验证，如果测试不存在则跳过。

这个指令的价值在于：

• 明确了文件边界，避免 Agent 无意义扫描。
• 明确“只修改两个文件”，缩窄了影响范围。
• 明确验证方式，让 Agent 在正确方向走到最后。
• 没有让 Agent 输出大段解释。

8.4 第三步：单次任务完成后清理

注意观察拦截输出中是否有“读取了哪个文件、搜索了多少个文件”的信息。如果任务已完成，保存代码后执行：

code复制/clear

这一步把该任务的全部历史从上下文中移除，下一个任务不会背着旧账。

8.5 第四步：用脚本统计配置是否生效

在实际的 Token 成本计算中，你更依赖的是服务商的 API 用量报表。但本地可以做一个简单脚本，读取当前目录下 .claude 和 CLAUDE.md 的总字符数，作为“基础上下文体积”的粗略参考：

python复制# 文件路径：tools/context_size_check.py
import os
import pathlib

def get_file_size(path: str) -> int:
    p = pathlib.Path(path)
    if p.exists():
        return len(p.read_text(encoding="utf-8"))
    return 0

base_dirs = [
    os.path.expanduser("~/.claude/CLAUDE.md"),
    "./CLAUDE.md",
    "./.claude/CLAUDE.md",
]

total = 0
for f in base_dirs:
    size = get_file_size(f)
    print(f"{f}: {size} chars")
    total += size

print(f"total context file size: {total} chars")

bash复制python tools/context_size_check.py

输出示例：

code复制~/.claude/CLAUDE.md: 0 chars
./CLAUDE.md: 612 chars
./.claude/CLAUDE.md: 0 chars
total context file size: 612 chars

这里计算的是“每次请求都会携带的基础文本量”。字符数越小，说明每轮请求的固定开销越低。这是一个近似指标，真正的 Token 数还取决于模型分词器，但它足以帮助你控制 CLAUDE.md 的膨胀。

9. 运行结果与效果验证

做完上述优化后，怎么判断自己真的省下了成本？

你可以从三个层面验证：

9.1 会话层验证

观察同一任务下的会话轮次数量。如果你按“精准指令 + 最小文件范围 + 明确验证命令”的方式提交任务，一个中型功能的会话轮次通常会稳定在一个合理范围。如果类似任务要对话十次以上才能完成，说明上下文约束不足，Agent 频繁靠试错修正方向。

9.2 字符层验证

用上面的脚本对比优化前后 CLAUDE.md 与配置文件的字符量。从材料看，项目级 CLAUDE.md 保持在几百字符、最多一千多字符是比较健康的范围。当一个文件超过两千字符时，建议重新审视是否真的每条记录都对任务推进有帮助。

9.3 账单层验证

如果你使用的是 API 计费，服务商后台的 Token 用量统计是最准确的口径。在优化前先记录一个基线任务（比如“给某个服务新增一个查询接口”）的平均 Token 消耗，优化后再用相同任务测试，对比差值。这里不给出具体数字，因为不同模型、不同代码库差异太大，但“相同任务对比”的方法是可复用的。

如果觉得“对比统计”成本太高，一个更轻量的验证标准是：同一个 Task 描述，优化后的首次生成结果是否明显更接近预期，后续修正轮次是否减少。 修正轮次减少是成本降低最直接的信号。

10. 常见问题与排查方法

在实际使用 Claude Code 时，有些问题表面上是“功能不正常”，根子却在上下文管理上。下面用表格整理高频问题：

一个比较容易被忽略的排查技巧：当你觉得 Claude Code “越用越贵”时，先看自己是不是养成了“开着对话不放”的习惯。对话时间跨度越长、中间穿插的无关问题越多，历史上下文越大，成本越高。一次会话只解决一个好问题是省成本最朴素也最有效的方法。

11. 成本优化的最佳实践与工程建议

结合前面的内容，这里给出一套可以直接落地的工程建议清单：

1. 把 CLAUDE.md 当作项目核心配置来管理。它不只是给 AI 看的说明文档，也是项目的关键上下文入口。每次新任务开始时更新“当前任务”区域，任务结束后清理，避免过时信息误导 Agent。
2. 为大任务提前拆分并写清验收标准。不要让 Agent 在一个超长对话里尝试完成整个模块。把它拆成“实现数据访问层”“实现路由层”“补充测试”三个阶段，每个阶段结束后用 /clear 隔离历史。
3. 按任务难度选择模型与输出上限。修改几行配置用轻量模式；复杂架构设计或大规模重构时，再用更强模型，同时调高输出上限。
4. 控制仓库噪音。确保构建产物、生成文件、第三方依赖都不进入 Agent 的扫描范围。一个干净的仓库不仅让 Agent 更准确，也直接减少搜索 Token 的浪费。
5. 让 Agent 给出文件路径与行号，而不总是粘贴大段代码。在跨文件定位问题时，搜索结构和引用关系通常比读取全部文件内容更省。
6. 建立团队级成本基线。如果团队多人使用 Claude Code，可以让每个人记录“典型任务”平均会话轮次、平均字符量，定期对比。从团队角度看，成本优化的收益往往来自最差的几个使用习惯，而不是某个人的极限微调。
7. 定期审视 CLAUDE.md 中每一条规则的 ROI。如果某条规则在整个项目生命周期里只触发过一两次，而且从未阻止过错误发生，那它就是一条值得删除的高成本记录。

需要特别提醒的是：涉及生产环境、数据库操作、权限变更时，不要过度追求“让 Agent 全自动”。即使用了成本优化，也应该在 CLI 权限配置中保留必要的确认机制。省 Token 不能以牺牲安全边界为代价。 在 settings.json 中限制危险命令，是对成本和风险的双重保护。

12. 总结与后续学习方向

Claude Code 的 Token 成本优化，本质是一场“上下文卫生”管理。你不需要掌握复杂的计费公式，也不需要刻意少用 AI，只要记住三条主线：减少注入上下文的噪音、缩小单次任务边界、划分清晰的会话生命周期。

这篇文章讲清楚了四个层面的内容：Token 的构成逻辑、CLAUDE.md 的高效写法、文件读取与输出体量的控制手段，以及一套可复用的“从任务拆解到效果验证”的流程。读者现在可以回到自己的项目，先写一个几百字符的 CLAUDE.md，再跑通一个明确边界的小任务，最后用会话轮次和账单数据对比优化前后的差异。

下一步值得继续深入的方向有两个：一是研究 Claude Code 的 MCP（Model Context Protocol）集成方式，理解外部工具调用如何影响 Token 流转；二是在团队内推广统一的 CLI 配置模板和 CLAUDE.md 规范。前者解决“Agent 如何更聪明地使用外部信息”，后者解决“多人使用时成本与风格失控”的问题。

最后保留一条判断：AI 编程工具的 Token 成本不是“使用的代价”，而是“上下文的租金”。 你无法完全避免租金，但完全可以决定自己租用的空间有多大。把项目背景写得准、把任务描述收得窄、把会话历史断得干净，这三个习惯一旦建立，省下的不只是账单金额，还有你排查无意义返工的时间成本。