Claude Code/API 成本控制指南：Token 预算、告警与上限

把 Claude Code 放进日常开发后，真正需要解决的问题不是“Claude 贵不贵”，而是“这次任务大概会花多少钱，什么时候必须停”。费用不是一个固定数字，它取决于读取的文件、上下文长度、输出长度、模型选择、prompt cache 是否命中，以及你使用的是 Claude 订阅额度还是 Anthropic API 的按量计费。

本文在 2026-06-03 核对了官方资料：Anthropic API pricing、Claude Code cost management、Prompt caching、Token counting 和 Usage and Cost API。价格会变化，做采购或报价前一定要回到官方页面确认。

先理解成本公式

概念	通俗解释	对成本的影响
token	Claude 读取和写出的计量单位	文件、日志、提示词和生成代码越长，token 越多
上下文	会话历史、已读文件、CLAUDE.md、工具定义等工作材料	旧内容留着不清理，会在后续请求里继续消耗
prompt cache	复用前一次请求中相同的前缀	命中后重复输入会便宜很多
预算护栏	按任务、每天、每人或工作区设置上限	防止一次好用的流程变成无限开销

估算成本 = 输入 token * 输入单价
        + 缓存写入 token * 缓存写入单价
        + 缓存读取 token * 缓存读取单价
        + 输出 token * 输出单价

截至 2026-06-03，官方价格表中 Sonnet 4.6 为输入 $3/MTok、输出 $15/MTok；Haiku 4.5 为输入 $1/MTok、输出 $5/MTok；Opus 4.8/4.7/4.6 为输入 $5/MTok、输出 $25/MTok。prompt cache 读取是基础输入价的 10%，5 分钟缓存写入是基础输入价的 1.25 倍。MTok 表示 100 万 token。

很多账单不是因为读了太多，而是因为每次都让模型写太长。输出通常比输入贵几倍，所以“详细解释所有问题”应改成“按严重度列出最多 5 个问题”。

成本控制闭环

flowchart LR
  A["定义任务"] --> B["裁剪输入"]
  B --> C["选择模型"]
  C --> D["估算 token"]
  D --> E{"预算内?"}
  E -- "是" --> F["运行 Claude"]
  E -- "否" --> B
  F --> G["记录 usage"]
  G --> H{"超过阈值?"}
  H -- "是" --> I["停止、告警或降级模型"]
  H -- "否" --> A

在 Claude Code 中，先看 /usage 和 /context。切换到无关任务时使用 /clear，需要保留决策但不想拖着整段历史时使用 /compact。/usage 里的金额是本地估算，真正的账单仍要看 Console；团队场景还应使用官方 Usage and Cost API 做日次对账。

示例1：先估算月成本

这个脚本不会调用 API，只根据每天的 MTok 用量估算月成本。

// claude-cost-estimator.mjs
const RATES = {
  opus48: { input: 5, output: 25, cacheRead: 0.5 },
  sonnet46: { input: 3, output: 15, cacheRead: 0.3 },
  haiku45: { input: 1, output: 5, cacheRead: 0.1 },
};

const [model = "sonnet46", days = "22", input = "0.25", output = "0.06", cacheRead = "0.20"] =
  process.argv.slice(2);

if (!RATES[model]) {
  throw new Error(`Unknown model: ${model}`);
}

const rate = RATES[model];
const dailyUsd =
  Number(input) * rate.input +
  Number(output) * rate.output +
  Number(cacheRead) * rate.cacheRead;

console.log({
  model,
  workDays: Number(days),
  dailyUsd: Number(dailyUsd.toFixed(4)),
  monthlyUsd: Number((dailyUsd * Number(days)).toFixed(2)),
});

node claude-cost-estimator.mjs sonnet46 22 0.25 0.06 0.20
node claude-cost-estimator.mjs haiku45 22 0.25 0.06 0.20

这不是精确账单，而是帮助你判断一个流程更接近每月 $15、$50 还是 $500。实际使用时要为工具定义、重试、缓存写入和长输出预留 20% 到 30% 的缓冲。

示例2：每次 API 调用都带预算上限

下面的例子会先用 Token Count API 估算输入，再调用 Messages API，最后把实际 usage 写入 JSONL。当天预算快超时会直接停止。

npm init -y
npm i @anthropic-ai/sdk

// budgeted-message.mjs
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";
const maxTokens = Number(process.env.MAX_TOKENS ?? 700);
const dailyBudgetUsd = Number(process.env.DAILY_BUDGET_USD ?? 5);

const RATES = {
  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheRead: 0.5 },
  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheRead: 0.3 },
  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheRead: 0.1 },
};

function usdFromUsage(usage, rate) {
  return (
    (usage.input_tokens ?? 0) * rate.input +
    (usage.output_tokens ?? 0) * rate.output +
    (usage.cache_creation_input_tokens ?? 0) * rate.cacheWrite5m +
    (usage.cache_read_input_tokens ?? 0) * rate.cacheRead
  ) / 1_000_000;
}

function todayTotalUsd(path) {
  if (!fs.existsSync(path)) return 0;
  const today = new Date().toISOString().slice(0, 10);
  return fs.readFileSync(path, "utf8")
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line))
    .filter((row) => row.date === today)
    .reduce((sum, row) => sum + row.usd, 0);
}

const messages = [
  { role: "user", content: "List only the top three bug risks in this TypeScript function." },
];

const rate = RATES[model];
if (!rate) throw new Error(`No rate table for ${model}`);

const counted = await anthropic.messages.countTokens({ model, messages });
const worstCaseUsd = (counted.input_tokens * rate.input + maxTokens * rate.output) / 1_000_000;
const logPath = "claude-usage.jsonl";

if (todayTotalUsd(logPath) + worstCaseUsd > dailyBudgetUsd) {
  throw new Error(`Budget stop: projected daily spend exceeds $${dailyBudgetUsd}`);
}

const response = await anthropic.messages.create({
  model,
  max_tokens: maxTokens,
  cache_control: { type: "ephemeral" },
  system: "You are a concise senior code reviewer. Return only actionable findings.",
  messages,
});

const usd = usdFromUsage(response.usage, rate);
fs.appendFileSync(logPath, JSON.stringify({
  date: new Date().toISOString().slice(0, 10),
  model,
  usd: Number(usd.toFixed(6)),
  usage: response.usage,
}) + "\n");

console.log({ id: response.id, usd: Number(usd.toFixed(6)), usage: response.usage });

ANTHROPIC_API_KEY=sk-ant-...
DAILY_BUDGET_USD=5 node budgeted-message.mjs

给新人解释时，可以说这段代码做了三件事：发送前称重、发送后保存收据、超过当天预算前停止。

示例3：团队按天看用量

组织账号可以用 Admin Usage and Cost API 查看日次用量。它需要 Admin API key，普通个人账号不能使用。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-06-01T00:00:00Z&\
ending_at=2026-06-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

先看三个信号就够了。

信号	风险	处理
Opus 占比	简单任务也在用高价模型	摘要、翻译、格式化改用 Sonnet 或 Haiku
输出 token	回答默认过长	限制条目数、行数和 max_tokens
cache read	cache_read_input_tokens 接近 0	从缓存前缀中移除时间戳和随机值

三个实际场景

个人开发。 默认使用 Sonnet，只在架构判断、复杂调试、关键审查时切到 Opus。任务切换后清理上下文，避免旧文件继续被计费。

内容生产和本地化。 把风格指南、术语表和输出格式作为稳定前缀缓存，只替换正文。大量异步翻译或摘要可以评估 Batch API 的 50% 折扣。

培训和团队落地。 培训日会出现平时没有的并发高峰。提前设置日预算、阈值和 TPM/RPM 预期，并教大家只传失败日志的最后几十行。需要成体系的团队教材时，可以参考 /training/。

常见坑

环境变量导致意外按 API 计费。 官方帮助说明，ANTHROPIC_API_KEY 会优先于 Claude Code 中已登录的订阅账号。想使用订阅额度时，先用 /status 确认认证方式。

以为缓存一定命中。 缓存依赖稳定的 prompt 前缀。system prompt 里的当前时间、UUID 或动态文件列表都会破坏命中率。

不限制输出。 代码审查应限制最多几条发现，摘要应限制长度，生成代码应限制文件范围。max_tokens 是保险，不是唯一控制手段。

复制过期价格。 模型名和价格会更新。发布报价器、培训材料或客户估算前，必须重新核对官方价格页。

使用无法审计的低价代理。 如果服务方不能说明模型来源、日志保留和凭据处理，折扣可能只是把风险转移到数据和账号上。

相关内容

• Claude Code token optimization
• Claude Code pricing guide
• Claude Code context management
• Claude Code permission budget loop

可复用的预算表、提示词模板和审查清单放在 /products/。

实测结果

在 ClaudeCodeLab 的内容流程中，最有效的不是复杂技巧，而是稳定的基本控制：缓存共通规则，把翻译和格式化交给 Haiku/Sonnet，只让 Opus 处理高判断任务，并把每次 API 调用的 usage 写入 JSONL。先做到 80% 告警、100% 停止、任务切换就清理上下文，账单就会从“事后惊讶”变成“事前可解释”。