Claude Code API 配置指南：API Key、Base URL 与模型别名设置

最短路径：三条环境变量

Claude Code 的配置说到底就三件事——凭证、端点、模型名，三样都能用环境变量给。

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_BASE_URL="https://<你的端点>"
export ANTHROPIC_MODEL="<服务端支持的模型名>"

如果用的是 Anthropic 官方端点，第二行不要设：不设就是默认的 api.anthropic.com。设了却填错，比不设更容易出问题。

启动 claude 进入交互会话后，先执行 /status。它会显示当前生效的认证方式、Key 或 Token 的来源，以及会话配置。配置完先看这一眼，比反复试错找 401 的原因快得多。

凭证：ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 不是一回事

两个变量都常被笼统叫“API Key”，但请求头完全不同：

ANTHROPIC_API_KEY 走 X-Api-Key 头。环境里存在这个变量时，Claude Code 会优先用它，请求计到对应 Console 组织的 API 账单上，不走 claude.ai 网页订阅。交互模式下它会先提示你确认这次审批，确认后跳过浏览器登录。
ANTHROPIC_AUTH_TOKEN 走 Authorization: Bearer 头。用于采用 Bearer 鉴权的网关、代理或中转端点。

最典型的坑，是把端点发给你的 Bearer Token 填进了 ANTHROPIC_API_KEY：凭证本身没错，只是放错了请求头，结果就是 401。反过来也一样。接入前先问清楚端点要哪一种鉴权。

还有一个容易误判的点：订阅和 API Key 是两套计费。已经用 claude.ai 订阅登录过的人，一旦环境里出现 ANTHROPIC_API_KEY，计费就会切到 API 账单。想继续走订阅，就别设它。

端点：先确认协议，再填 URL

ANTHROPIC_BASE_URL 的作用是把请求从官方地址重定向到私有网关、企业代理或第三方端点。

这里有一条硬前提：Claude Code 说的是 Anthropic Messages 协议，原生只对接 Anthropic 官方 API 以及 Bedrock、Vertex 这类云厂商的原生适配器。如果目标端点只暴露标准的 OpenAI 格式 /v1/chat/completions，又没有配 Anthropic 协议转换层，那把地址填进 ANTHROPIC_BASE_URL 会在请求发出这一步就失败，报错出现在协议层而不是鉴权层。换个 Key、换个模型名都救不回来。

所以挑端点的顺序是：先问“有没有 Anthropic 兼容的 Messages 端点”，再问模型名，最后才谈价格。协议这一关过不了，后面全是白搭。两套协议的请求格式差异，站内《Claude 和 GPT API 对比》已经拆开讲过一遍。

决定长期用哪个端点时，除了协议，还有几项值得在接入前就问清楚：限速和配额是否公开、多人协作用的是不是按 Key 隔离（配额、权限、用量账单各自独立），以及对话内容是否留存。比如 NexAIX 的模型清单里，逐个模型标注了它属于哪种供给方式——自有算力部署的开源权重模型，还是厂商官方授权渠道的闭源模型；端点和 Key 从官网导航的「文档」与「获取 API Key」获取，官网同时写明不记录对话内容、请求结束即释放。这些信息能不能提前拿到，本身就是判断依据。

模型名：Claude Code 内部不止用一个模型

Claude Code 是按角色分档取模型的：主对话、后台轻任务、子代理，各用各的。换成第三方端点后，服务端的模型名几乎不可能和官方默认一致，于是需要重写：

ANTHROPIC_MODEL：主模型
ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL：分别覆盖 opus / sonnet / haiku 三档别名
CLAUDE_CODE_SUBAGENT_MODEL：子代理任务使用的模型

这套别名有两种实际用法。一是服务端只提供一两个模型时，把三档都指到同一个，免得 Claude Code 按档位去找一个不存在的名字。二是把 haiku 档指到更便宜的小模型，让它去干读文件、起标题这类轻活，主档保持在强模型上。

名字写错一般会被服务端以“模型不存在”拒绝（通常是 4xx），这类报错反而好定位；如果响应里出现的模型标识和你设的对不上，那要往端点侧查，而不是反复改本地变量。

让配置持久化：settings.json 的优先级高于 shell

export 只活在当前终端窗口里。要长期生效，就把配置写进 ~/.claude/settings.json 的 env 对象：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<你的端点>",
    "ANTHROPIC_API_KEY": "sk-...",
    "ANTHROPIC_MODEL": "<模型名>"
  }
}

settings.json 的 env 与 shell 环境变量的优先级关系

关键在优先级：settings.json 里的 env 会覆盖你当前 shell 导出的同名变量。这是排查时最难想到的一类问题——在终端里改了 ANTHROPIC_BASE_URL，重启 Claude Code 却没变化，多半是这里有一份更高优先级的配置压着。

如果 Key 由外部系统下发、需要定期轮换，可以用 apiKeyHelper 字段指向一个脚本，让 Claude Code 运行时去取，不必把明文留在配置文件里。本地、CI、生产多套环境并用时，这一点比手改文件省事。Key 的存放和拆分方式，站内《AI API Key 怎么拿、怎么存、怎么分》有更细的讨论。

怎么确认配置真的生效

启动后执行 /status，核对认证方式、Key/Token 来源和当前端点。那三行环境变量到底有没有被读进去，这里最清楚。
行为不符预期时，先把 settings.json 和 shell 变量一起看一遍，确认没有第二份配置在生效——优先级搞反了，改哪一份都白改。
怀疑模型被换掉，别只看界面文字，拿实际请求核对：看响应里的模型标识，以及长输入是不是按你预期的上下文长度处理。从 401、404、429 到超时、截断的分段排查顺序，站内《AI API 故障排查》里是现成的路线。
想把“没有被降配”这条坐实，可以按官网列的四条承诺与对应验证方法逐条对照，比凭感觉判断可靠。