Claude Code API 配置不要从粘贴 Key 开始。先确认这次会话应该走哪条路：订阅登录、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 加 ANTHROPIC_BASE_URL 的中转网关、apiKeyHelper，还是 Bedrock、Vertex、Foundry 这样的云厂商路由。
安全顺序是：先选路由，再选配置范围，再定模型，最后验证。只要 /status、/config 和 /model 没确认，就不要把当前会话当成已经配置成功。
| 目标 | 放在哪里 | 先验证什么 |
|---|---|---|
| 日常交互式 Claude Code | 订阅登录和用户/项目设置 | /status 应显示预期账户 |
| 直接 Anthropic API Key | 本地 shell 或本地私有设置里的 ANTHROPIC_API_KEY | 环境变量存在且路由正确 |
| 中转或兼容网关 | 本地范围里的 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL | Base URL、模型名和信任边界 |
| Bedrock、Vertex、Foundry | 云厂商凭证和路由变量 | 提供商、区域、模型名 |
先判断 Claude Code 当前路由
Claude Code 看起来只是一个终端工具，但实际可能由不同合同接管。订阅登录适合人在终端里改仓库、查错误、做 review；直接 API Key 适合 CI、SDK、无人值守任务和需要 Console 账本的工作；中转网关适合有明确信任边界和模型兼容约定的场景；云厂商路由则由 AWS、Google Cloud 或 Azure 侧的凭证和配额控制。
如果你还没装好 CLI，先看 Claude Code 安装教程。如果问题是 API Key 会不会改变账单归属，看 Claude Code API Key 和订阅计费。配置工作本身只解决一件事：让预期路由真正生效，并且能被验证。
凭证优先级：谁会赢
截至 2026 年 4 月 21 日的官方文档检查，Claude Code 的凭证优先级是云厂商凭证、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper、OAuth token，最后才是 /login 订阅登录。这个顺序决定了很多“配置了但没生效”的问题。
| 出现的凭证 | 可能结果 | 处理方式 |
|---|---|---|
| 云厂商变量 | Bedrock、Vertex 或 Foundry 接管 | 先查区域、项目和模型名 |
ANTHROPIC_AUTH_TOKEN | Bearer 网关优先 | 同时检查 ANTHROPIC_BASE_URL |
ANTHROPIC_API_KEY | 直接 API 路由覆盖订阅预期 | 用 /status 和 Console 账本确认 |
apiKeyHelper | CLI 会话通过 helper 取 Key | 审计 helper 输出和权限 |
不要把真实密钥打印出来。可以只检查是否存在：
bashtest -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set" printenv ANTHROPIC_BASE_URL
settings.json 应该改哪一层
共享项目设置适合团队行为，不适合放秘密。用户设置适合个人默认值，本地项目设置适合个人机器上的覆盖，shell 环境适合临时凭证，命令行参数适合一次性会话。
| 范围 | 常见位置 | 适合 | 不适合 |
|---|---|---|---|
| 用户设置 | ~/.claude/settings.json | 个人默认行为 | 团队强制策略 |
| 共享项目设置 | .claude/settings.json | 权限、命令白名单、非秘密默认值 | API Key 或网关 token |
| 本地项目设置 | .claude/settings.local.json | 机器私有覆盖 | 需要提交给团队的规则 |
| shell 环境 | 当前终端、CI secret、启动脚本 | 凭证和路由变量 | 难以追踪的团队默认值 |
直接 API Key 和中转网关
直接 Anthropic API Key 用 ANTHROPIC_API_KEY。临时测试可以放在当前 shell：
bashexport ANTHROPIC_API_KEY="$YOUR_ANTHROPIC_API_KEY" claude /status
中转或兼容网关应成对设置 token 和 host：
bashexport ANTHROPIC_AUTH_TOKEN="$YOUR_GATEWAY_TOKEN" export ANTHROPIC_BASE_URL="https://gateway.example.com" claude /status
中转不是官方直连 API。使用前要确认 host、token、模型名、header 保留、日志和数据边界。如果你是在选择中转服务，而不是配置本机变量，转到 Claude 网关选择指南。
模型和云厂商路由
模型优先级是 /model、启动时 --model、ANTHROPIC_MODEL，再到 settings 里的 model。如果 settings 写了模型但会话仍然不对，先看是不是 /model 或环境变量覆盖了它。
Bedrock 需要类似 CLAUDE_CODE_USE_BEDROCK=1 和 AWS_REGION 的变量；Vertex 需要 CLAUDE_CODE_USE_VERTEX=1、区域或项目变量以及 Google Cloud 凭证。云厂商接管认证后，不要再用普通 /login 思路解释会话。
验证清单
每次换路由后都跑一轮：
text/status /config /model
然后在 shell 里只检查变量是否存在，不输出密钥。若 /status 不是预期路由，先清理更高优先级变量，再重启终端会话。若模型不对，按 /model、--model、ANTHROPIC_MODEL、settings 的顺序排查。
安全和下一步
不要提交真实 Key，不要把 token 写进共享 .claude/settings.json，不要把网关 host 和 token 截图给别人。提交前至少运行 git diff -- .claude/settings.json .claude/settings.local.json。
下一步按问题分流：安装看 安装教程，计费看 API Key 和订阅计费，Key 可用性看 Claude API Key 免费层，限制问题看 Claude Code 使用限制排查。
常见问题
Claude Code 必须设置 API Key 吗？
不一定。日常交互式使用通常可以走订阅登录。只有 CI、SDK、自动化或明确 API 账本需求时，才应该设置 ANTHROPIC_API_KEY。
ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 有什么区别？
ANTHROPIC_AUTH_TOKEN 是 Bearer token，常与 ANTHROPIC_BASE_URL 一起用于兼容网关；ANTHROPIC_API_KEY 是直接 Anthropic API Key 路由。
怎么确认配置真的生效？
在 Claude Code 里运行 /status、/config、/model，再在 shell 里检查相关变量是否存在。不要用记忆里的设置判断当前会话。