日常在 Claude Code 里写代码时，Claude Pro 或 Max 登录通常不需要 API Key；一旦本机设置了 ANTHROPIC_API_KEY，Claude Code 可能优先走 API 账户，并把用量记到 Claude Console 的 API 账单。达到计划内用量后，如果你主动启用 usage credits，后续用量也会按标准 API 价格另行计费。关键不是“哪条路一定更便宜”，而是当前会话到底走哪条计费路由。
先运行 /status，再看环境变量、/usage 和 Console 用量。交互式写代码优先用订阅登录；CI、SDK、后端服务、无人值守任务才适合 API Key；usage credits 只应作为你明确同意的续用或 API 路由余额，而不是 Pro 或 Max 订阅的隐藏额度。
| 你的情况 | 建议路由 | 由谁计费 | 第一项检查 |
|---|---|---|---|
| 本地终端里交互式写代码、改仓库、做 review | 订阅登录 | Claude Pro 或 Max 计划用量 | /status 显示订阅账户 |
设置了 ANTHROPIC_API_KEY 或跑自动化 | API Key 路由 | Claude Console 的 API 用量 | 检查环境变量和 Console Usage |
| 达到计划限制后启用了 usage credits | usage-credit 续用 | 按标准 API 价格另行计费 | 查看 Settings > Usage 和 Console Billing |
| 已有订阅却看到 API 花费 | 先诊断，不先升级 | 可能是 API Key 抢走路由 | /status 和 echo "$ANTHROPIC_API_KEY" |
先确认当前走哪条路
Claude Code 可以通过 Claude 账号登录，也可以通过 API Key 进入 API 路由。这两种方式可以在同一台机器上共存，但计费主体不同。订阅登录面向个人交互式使用，API Key 面向 Console 项目、SDK、CI 和服务端任务。
如果你在终端里让 Claude Code 读代码、解释报错、重构文件、做本地 review，默认应该使用 Pro 或 Max 订阅登录。这个路径对应的是 Claude 计划的使用限制，而不是按 token 逐笔扣 API credits。
API Key 适合另一类工作：程序要自己调用模型，CI 要无人值守运行，团队要把费用归到某个 Console 项目，或者你需要用 Console 的 usage ledger 做审计。此时 API Key 是正确工具，但它会改变账单归属。
Usage credits 则是第三个概念。它们可以让 Pro、Max 5x 或 Max 20x 用户在计划内用量用完后继续工作，但后续用量会按标准 API 价格另行计费，并且应该和计划内用量分开显示。它们不会自动变成 Pro 或 Max 订阅额度，切换到 credit 续用也不应该是无感发生的。
为什么有订阅还会出现 API 账单
最常见原因是本地环境已经设置了 ANTHROPIC_API_KEY。Claude Code 支持 API Key 环境变量；当这个变量存在时，会话可能被导向 API 账户。你看到的不是“订阅被额外收费”，而是工具切到了另一个计费合同。
第二类原因是自动化场景。CI、批处理脚本、容器、devcontainer 或启动器通常不能依赖某个人的浏览器登录状态。它们更适合使用 API Key，但对应的费用应该在 Console 里预算和监控。
第三类原因是 usage credits 或 Console 自动充值打开了，却没有把计划内用量、credit 续用和 API Key 路由分清。结果是有人以为自己还在单纯消耗订阅额度，实际后续用量已经按 API 价格结算。
判断时不要先买 Max，也不要先删除 Console Key。先证明当前路由：
bashclaude /status echo "$ANTHROPIC_API_KEY"
如果 /status 指向订阅登录，就按订阅限制排查；如果它指向 API 路由，就去看环境变量、项目配置和 Console Usage。
/status、/usage、/cost 和 Console 分别看什么
/status 是第一入口。它告诉你当前 Claude Code 会话绑定的是哪个账户和哪条路由。只要路由没确认，后面的数字都容易被误读。
/usage 更适合订阅用户理解计划用量条、usage-credit 消耗和 Claude Code 里的使用习惯。如果你的安装版本或团队习惯仍说 /stats，也要把它当成使用模式视图，而不是 Claude Console 的 API 发票。
/cost 或 usage 输出里的美元数字更像 API 风格的 token 成本估算。对订阅登录来说，它不应被当成 Pro 或 Max 的最终账单。对 API 路由来说，最终仍应回到 Console Usage 确认。
Claude 的 Settings > Usage 用来区分计划内用量和 usage-credit 消耗。Claude Console Billing 和 Usage 是 API 账户的权威账本；自动充值、项目级消费、API 路由下的 Claude Code 花费，都应该在这里核对。
团队 runbook 里最好同时记录 /status 路由和 Settings 或 Console 账本，因为这两项能分别证明当前路径和实际账单 owner。
什么时候应该用 API Key
API Key 适合 API 型工作，而不是“订阅不够用时随手打开”的替代品。只要你的任务需要程序化访问、项目级归属、无人值守运行，API Key 就有明确价值。
可以用 API Key 的典型情况包括：
- 后端服务或 SDK 集成需要调用 Claude API
- CI 或 scheduled job 需要无人登录运行
- 团队希望费用进入某个 Console project
- 自动化 agent 需要可审计的 usage ledger
- 你愿意按当前 Claude API 价格为模型 token 付费
如果只是本地写代码时频繁碰到计划限制，先看 Claude Code Pro vs Max。如果问题是限制，不要把它误判成 API Key 设置问题；如果问题是账单归属，不要只靠升级订阅解决。
Usage Credits 和价格边界
Usage credits 可以让付费 Claude 计划用户在计划内用量到达限制后继续使用 Claude 和 Claude Code，但它们按标准 API 价格另行计费。Console 里的 API 余额和自动充值仍然属于 API 路由管理范围，和 Claude Pro 或 Max 的订阅费不是同一件事。
截至 2026 年 5 月 25 日，Anthropic 公共价格页按模型列出输入和输出 token 价格。例如 Claude Sonnet 4.6 标示为每百万输入 token 3 美元、每百万输出 token 15 美元；Claude Opus 4.7 标示为每百万输入 token 5 美元、每百万输出 token 25 美元。这些是日期绑定的价格例子，实际计费要以你查看时的官方价格页和 Console 为准。
所以问题不是“API 一定更便宜”或“订阅一定更便宜”。本地长时间交互式编码通常更适合订阅路由；CI、后端、批处理和团队自动化通常更适合 API 路由。想查 API 是否有免费额度，应单独看 Claude API Key 免费额度指南，不要把它和订阅额度混在一起。
如何切回订阅登录
如果你本来想用订阅，却发现 API 账户有消费，先在当前 shell 里临时移除环境变量，再重新登录：
bashunset ANTHROPIC_API_KEY claude logout claude login claude /status
这不会删除 Console 里的 API Key，只会让当前终端不再用这个变量启动 Claude Code。重新登录后必须再跑 /status，确认会话已经回到订阅账户。
如果新开终端后 Key 又出现，说明它写在了更持久的位置。检查 .zshrc、.bashrc、项目 .env、终端 profile、devcontainer、CI secret、launcher script。团队环境里最好把规则写清楚：本地交互用订阅，自动化用 API Key，API 花费只看 Console。
不要混淆的几件事
不要说“Claude Code 免费”，也不要说“Pro 包含 API 调用”。Pro 或 Max 可以让你用 Claude 账号连接 Claude Code，但通用 API 调用属于 Console 的 API 计费合同。
不要把 /cost 或本地美元估算当成订阅账单。它能帮助理解 token 成本，但订阅使用、usage credits 和 API 花费要分别看 /status、/usage、Settings > Usage 和 Console Usage。
不要把真实 API Key 粘贴到工单、聊天、截图或排障提示里。你只需要证明变量是否存在，以及 /status 显示哪条路由。
不要用社区帖子替代官方账单边界。论坛能说明困惑很常见，但最新合同应以 Claude 和 Anthropic 官方文档为准。
团队里怎么定这条规则
如果这不是个人电脑，而是团队环境，最好把 Claude Code 的计费路由写成一条小规则，而不是靠每个人记住。最简单的写法是：本地交互式编码用订阅登录；仓库机器人、CI、server-side agent、SDK demo 和批处理用 API Key；任何 usage credits 或 Console auto-reload 都必须有预算 owner。这样新人看到 /cost 或 Console 花费时，先问“这是哪条路由”，而不是先问“是不是该升级 Max”。
团队还应该分清两种余额。Paid-plan usage credits 是用户在计划内额度用完后继续 Claude 或 Claude Code 的显式付费续用；Console API credits 是 API、Workbench 和 API 路由下 Claude Code 的账户余额。两者都可能显示为 credit 或 cost，但它们不应该被写成同一张账单。文档里可以直接列一个 owner 表：订阅登录归个人 Claude 计划，usage credits 归个人付费计划的额外使用，API Key 归 Console project，自动化任务归项目预算。
排查时保留证据也要克制。不要截图完整 Console、不要贴出真实 key、不要把 .env 发到群里。安全的证据是 /status 输出里的账户/路由描述、echo "$ANTHROPIC_API_KEY" 是否为空、Settings > Usage 的计划内/credit 消耗分区，以及 Console Usage 里的项目和时间范围。客服或队友要定位账单时，这些足够判断方向；真实 secret 应该轮换或隐藏，而不是作为诊断材料传播。
最后，把“是否买 credits”和“是否升订阅”拆成两个会议问题。usage credits 解决的是当前计划内额度用完后是否继续付费工作；升级 Pro/Max 解决的是交互式用量和中断成本；API Key 解决的是程序化运行和项目账本。只有当 /status 和使用场景都证明是同一个问题时，才把它们放在同一个预算讨论里。
还可以给长任务加一个启动前检查。开始大仓库重构、批量 review、生成 release note 或运行自动化 agent 之前，先记录三件事：当前 /status、当前 shell 是否存在 ANTHROPIC_API_KEY、这次任务预计归属于个人计划还是 Console project。如果三项互相矛盾，例如任务写着“个人订阅”，但环境变量里有 API Key，就先修环境再开跑。这样做比任务结束后追账单便宜得多。
对个人用户也是同理。看到 usage credits 提示时，不要把它当成系统自动赠送的续命按钮。先问自己：我是在赶一个必须现在完成的交互式任务，还是可以等计划窗口重置？如果是 CI、SDK 或后端调用，就不要借个人订阅解释成本；如果是本地 coding session，就不要因为 /cost 出现估算数字而马上断定订阅失效。
这套规则的目的不是多加流程，而是让每次排查都有同一个入口。只要先确认路由，后面的动作就会自然分开：订阅路线看计划窗口和 /usage，API Key 路线看 Console project 和预算，usage credits 路线看是否接受标准 API 价格。没有这个入口，团队很容易把三个问题混成一个“Claude Code 太贵”。
如果需要给队友一句话结论，就写：先看 /status，再决定是订阅问题、API Key 问题，还是 credits 问题。
这也是最容易复用的排障口径之一。
验证路径
本文的账单和路由边界基于 2026 年 5 月 25 日核对的 Claude Help、Claude Code docs、Anthropic billing 和 Anthropic pricing 文档。
你自己排查时也按同样顺序做：先 /status，再检查 ANTHROPIC_API_KEY，最后看 Settings > Usage 或 Console Usage。这样能先拿到路由答案，再决定是调整登录、删除本地变量、管理 usage credits，还是比较订阅计划。
常见问题
Claude Code 一定需要 API Key 吗？
不需要。用 Claude Pro 或 Max 做正常交互式编码时，Claude Code 可以通过 Claude 账号登录。API Key 适合 SDK、CI、后端服务、无人值守任务或 Console 项目归属明确的场景。
为什么我有 Pro 或 Max，还出现 API 计费？
先看 /status，再检查 ANTHROPIC_API_KEY。如果环境变量存在，Claude Code 可能正在走 API 路由，费用就会进入 Console，而不是订阅计划。
Usage credits 是订阅额度吗？
不是。Usage credits 让付费计划用户在计划内用量用完后继续使用，但会按标准 API 价格另行计费。Pro 或 Max 订阅有自己的计划内用量和重置规则。
订阅不够用时应该改用 API 吗？
只有任务本身是 API 型工作时才应该改用 API。交互式写代码遇到限制，先看 Claude Code 使用限制排查 和 Pro/Max 差异。
/cost 显示的是我的订阅账单吗？
不是。把 /cost 看成 API 风格的成本估算。订阅用户更应该先用 /status 确认路由，用 /usage 看计划内用量和 usage-credit 消耗，API 用户再用 Console Usage 对账。
如何停止 Claude Code 使用 API Key？
在启动 Claude Code 的同一个环境里运行 unset ANTHROPIC_API_KEY，重新 claude logout 和 claude login，最后用 /status 确认。如果 Key 反复出现，就去 shell 配置、项目环境文件或 CI secret 里移除。