Claude Code Token 优化指南：用 /usage 降低成本并保持质量

Claude Code 的 token 优化不只是省钱。上下文变大以后，回复会变慢，旧假设会混入当前任务，Claude 也会反复读取已经没有价值的日志、diff 和讨论记录。真正的目标不是把 token 压到最低，而是在不牺牲交付质量的前提下，减少无关上下文。

截至 2026 年 6 月，更适合作为入口的命令是 /usage。官方命令文档把它描述为查看 session cost、plan usage limits 和 activity stats 的命令。/cost 与 /stats 现在是别名，所以不是完全不能用，但面向读者和团队规范时，用 /usage 更清晰。Pro、Max、Team、Enterprise 用户还可以看到 skill、subagent、plugin、MCP server 的使用归因。

本文按四层来讲：先观察使用量，再减少基础上下文，然后把嘈杂工作拆到更小的上下文，最后用监控把团队流程数字化。先说明几个词：hook 是“在固定生命周期自动执行的脚本或端点”；subagent 是“在独立上下文里完成窄任务的小代理”；harness 可以理解为“让代理安全、可重复工作的脚手架”。

flowchart LR
  A["观察: /usage 与 /context"] --> B["减少: CLAUDE.md 与输入范围"]
  B --> C["拆分: hooks / skills / subagents"]
  C --> D["度量: OpenTelemetry 与团队规则"]

从 /usage 开始

不需要每条 prompt 后都运行 /usage。更好的时机是：会话开始变慢、大型工具命令之后、准备交接任务之前、以及一次可复用流程结束后。再配合 /context，你可以判断成本来自当前任务、陈旧历史、memory 文件还是工具上下文。

账单层面要分清。/usage 里的 Session cost 是基于本机 token 计数的本地估算。API 用户应在 Claude Console 的 Usage 页面确认权威账单；订阅用户也不要把 session 的 dollar figure 直接当成实际收费，plan usage bar 和活动归因更适合日常判断。

# 在 Claude Code 会话中执行
/usage
/context

# 会话很长但任务还要继续时
/compact Preserve changed files, failing tests, decisions, and unresolved questions.

# 切换到无关任务时
/clear

/compact 和 /clear 不是一回事。前者保留重要状态并压缩历史，后者开始新的上下文。太早 clear 会丢失关键决策；从不 clear 则会让后面的任务继续为旧上下文付费。

让常驻记忆保持短小

token 不只来自刚输入的文字，还来自会话历史、CLAUDE.md、auto memory、日志、工具输出、MCP server 以及之前的调查记录。先把信息分成三类。

信息类型	放在哪里	例子
每次都需要	短 CLAUDE.md	build、test、硬性禁止项
这次任务需要	会话与 /compact	修改文件、失败测试、未决判断
看完即可丢弃	过滤后的命令输出	长日志、生成 diff、全量搜索结果

官方 memory 文档说明，CLAUDE.md 会作为上下文加载。文件越长，每次会话的固定成本越高；用 import 拆文件可以改善组织方式，但如果启动时仍然加载，就不能真正省 token。CLAUDE.md 应只放每天都需要的少量规则。

# CLAUDE.md

## Project commands
- Build: npm run build
- Test: npm run test
- Type check: npm run typecheck

## Fast navigation
- API code: src/api/
- UI components: src/components/
- Tests: tests/

## Avoid by default
- Do not scan node_modules/, dist/, coverage/, or generated clients.
- Do not paste full logs. Ask for the failing command and relevant lines.

## Compact instructions
When compacting, preserve changed files, failing tests, decisions, credentials policy, and next actions.

PR 审查清单、翻译规则、数据库迁移手册、发布流程等低频且很长的内容，更适合放进 skill 或单独文档。skill 可以在需要时加载，而 CLAUDE.md 从会话一开始就会进入上下文。

在 Claude 读取前过滤输入

最容易浪费 token 的做法，是把完整日志或完整 diff 直接贴进去。Claude 需要证据，不需要数据倾倒。把完整文件留在磁盘上，然后只把会影响下一步判断的片段交给 Claude。

# 给 request ID 和错误周边，不给整份生产日志
tail -n 800 logs/app.log | grep -E -n -C 4 "request_id=abc123|ERROR|WARN"

# 先看 PR 规模，再决定是否读取完整 diff
git diff --stat
git diff -- src/auth.ts tests/auth.test.ts

# 本地保留完整测试输出，只给 Claude 失败附近
npm test 2>&1 | tee test.log
grep -E -n -C 6 "FAIL|ERROR|Error|failed|Assertion" test.log | head -160

这不是隐藏信息，而是改变 Claude 首先看到的切片。如果切片不够，再补充下一段日志或下一个文件。这样做通常比“一开始全部读完”更快，也更容易 review。

谨慎使用 hooks

如果同一类过滤反复出现，可以用 hook 自动化。hook 不能用来隐藏失败，也不应该默认批准风险命令。先用 ask，检查改写后的命令，再决定是否在团队里推广。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

case "$cmd" in
  npm\ test*|pnpm\ test*|pytest*|go\ test*)
    filtered="$cmd 2>&1 | grep -E -n -C 6 '(FAIL|ERROR|Error|failed|Assertion)' | head -160"
    jq -n --arg command "$filtered" '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "Run test command with filtered output",
        updatedInput: { command: $command }
      }
    }'
    ;;
  *)
    echo '{}'
    ;;
esac

这个例子需要 jq。团队版最好把完整测试日志保存到文件，并保留原始 exit code。只有在“减少噪声但不减少证据”时，hook 才真的节省成本。

把冗长工作拆出去

subagent 适合处理嘈杂但结论很短的任务。例如：“阅读这些官方文档，只返回变化点”，“检查 10 个本地化文件，只返回阻塞问题”，“运行失败测试，只总结第一个可行动的 stack trace”。主会话需要的是结论、修改文件、证据链接和未解决问题。

不要因为可以创建 subagent 就到处创建。每个 subagent 都有自己的上下文、memory、工具和成本。它的价值在于保护主会话的判断上下文，而不是把模糊任务盲目并行化。skill 也是同理：把低频长流程从 CLAUDE.md 移出去，在需要时再加载。

用 OpenTelemetry 监控团队流程

单人使用时，/usage 和 /context 通常够用。团队重复使用时，OpenTelemetry 可以把成本、token 数、模型、时长和工具活动变成共同数据。先用 console exporter 观察，再接入正式 collector 或 dashboard。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

claude

不要只看 token。更合理的指标是使用量、修改轮次、验证是否通过、合并后是否需要补救。token 少了三成但 review 问题变多，并不是优化成功。

三个以上实用场景

日志调查

传 request ID、最新错误、时间戳、预期行为和前后几行。先让 Claude 基于小片段提出假设，证据不足时再扩大范围。

代码审查

先给 git diff --stat、变更文件、测试输出和审查重点。大型 PR 可以拆成安全、性能、兼容性几轮，减少反复读同一份 diff。

多语言发布

主会话只保留 canonical 文章的决策。翻译自然度、链接、description 长度、CTA 检查交给独立上下文，返回修改文件和验证结果即可。

团队培训日

培训时并发使用量会明显高于平时。给学员规定“先读五个文件”“失败日志最多 160 行”“扩大范围前说明理由”，同一套教材的 token 消耗会稳定很多。

需要避免的坑

• 只写 /cost。现在应以 /usage 为主，并说明 /cost、/stats 是别名。
• 把证据也删掉。复现步骤、期望输出、失败命令和关键决策必须保留。
• 把 CLAUDE.md 当运营笔记本。低频长流程应放到 skill 或单独文档。
• 启用过多 MCP server。用 /mcp 检查，简单任务能用 CLI 完成时优先用 CLI。
• hook 隐藏失败。完整日志要留在文件里，Claude 只先看过滤片段。
• 以为 subagent 一定更便宜。它能隔离噪声，但仍然会消耗自己的上下文。

小型交接脚本

下面的 Node.js 脚本不需要额外依赖，会把修改文件、diff 规模和测试失败行整理成一个短 brief。

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

function git(args) {
  return execFileSync("git", args, { encoding: "utf8" }).trim();
}

const testLogPath = process.argv[2];
const changedFiles = git(["diff", "--name-only"])
  .split(/\r?\n/)
  .filter(Boolean);
const diffStat = git(["diff", "--stat"]);
const testLog = testLogPath && existsSync(testLogPath)
  ? readFileSync(testLogPath, "utf8")
  : "";
const failures = testLog
  .split(/\r?\n/)
  .filter((line) => /(FAIL|ERROR|Error|failed|Assertion)/.test(line))
  .slice(0, 80);

console.log("# Claude handoff brief\n");
console.log("## Changed files");
console.log(changedFiles.length ? changedFiles.map((file) => `- ${file}`).join("\n") : "- None");
console.log("\n## Diff stat");
console.log(diffStat || "No diff");
console.log("\n## Test failures");
console.log(failures.length ? failures.map((line) => `- ${line}`).join("\n") : "- No matching failure lines");

node scripts/claude-brief.mjs test.log > claude-brief.md

已确认的官方文档

• Commands：确认 /usage、/context、/compact、/clear。
• Manage costs effectively：确认成本追踪、MCP、hooks、skills、subagents 和 model effort。
• How Claude remembers your project：确认 CLAUDE.md 与 auto memory 的行为。
• Hooks reference 与 Monitoring：确认 PreToolUse hook 与 OpenTelemetry。

相关内部文章可继续阅读 速度优化、权限指南 和 harness engineering 指南。

实际测试结果

这次重写时，我把日文作为 canonical，先核对官方文档，再更新 10 个语言版本。最有效的做法是把永久 memory、当前任务状态和一次性日志分开。只给 Claude 修改文件、失败行和验证状态，比直接粘贴完整测试输出更容易得到稳定答案。

如果需要可复用 prompt、设置模板和检查清单，可以从 ClaudeCodeLab 产品 开始。团队要整理权限、review policy、telemetry 和导入培训时，建议看 Claude Code 培训与咨询。