Claude Code API 配置：先选路由，再设置 Key、模型和网关

Claude Code 直连 Anthropic API 的关键配置是 ANTHROPIC_API_KEY；连接企业网关时，还要设置 ANTHROPIC_BASE_URL，并按网关要求选择 Key 或 Bearer token。 在交互模式中，API Key 需要批准使用；claude -p 非交互模式在存在该变量时使用它。这些规则有云平台、企业策略和 Claude apps gateway 等例外，不能只凭“终端里有 Key”判断实际认证方式。官方认证说明

先确定你拿到的凭据属于哪个入口，再照对应步骤配置：

以下操作供已获授权的读者在自己的环境中使用。示例依据 2026 年 10 月 6 日核对的文档；本次没有运行真实 Claude 会话、登录或收费 API 调用。

直接使用 Anthropic API Key

准备好已有的 Console Key、可用 API 额度和 Claude Code CLI。尚未安装 CLI 时，先按官方快速入门完成安装。不要把网关 token、Claude 登录 cookie 或 Azure Key 当成 Anthropic Console Key。

先在一个 Bash 终端中临时设置 Key，验证成功后再决定如何长期保存。下面用隐藏输入避免将真实 Key 直接写进命令历史；这是 Bash 写法，macOS 默认 zsh 的 read 参数不同，可先进入 Bash 再使用。

read -r -s -p "输入已有的 Anthropic API Key：" ANTHROPIC_API_KEY
printf '\n'
if [ -n "$ANTHROPIC_API_KEY" ]; then
  export ANTHROPIC_API_KEY
  claude
else
  printf '未输入 Key，未启动 Claude Code。\n'
fi

交互启动时，如果出现使用环境变量 API Key 的确认，选择批准。这个选择会保存；以后要更改，可在终端版 /config 中调整 Use custom API key。进入会话后运行 /status，核对正在使用的凭据来源，再发送一条简短测试消息。API 请求可能产生费用。认证与批准规则

自动化任务使用的是另一种行为：在没有更高优先级认证或策略接管的情况下，ANTHROPIC_API_KEY 已设置时，claude -p 使用该 Key，不沿用交互模式拒绝 Key 的选择。例如，在上述变量已成功导出的同一个终端内，可以进行一次简短调用：

claude -p "只回复：配置测试成功"

这会发送真实请求，不是纯本地检查。先确认请求应记入哪个 Console 组织或 workspace，再运行；不要用它试探未知来源的 Key。

如果结果仍显示订阅登录，先检查是否曾拒绝使用 Key、变量是否到达当前进程，以及 settings 文件是否设置了同名变量。若显示别的 provider，转到后面的凭据优先级检查。关闭这个终端后，临时导出不会自动进入新的终端。

没有 API Key，也能使用 Console 登录吗？

可以。CLI 从 v2.1.242 起支持无需创建 API Key 的 Console 登录，并使用 Anthropic profile；该方式要求没有设置 ANTHROPIC_API_KEY。服务器托管设置还涉及 v2.1.257 起的支持，企业组织也可能限制登录方式。它与 Claude 订阅登录、手工导出 Key 是不同入口。Console 登录条件

若你已经选定 Console 无 Key 登录，先确认当前终端和 settings 中没有残留的 API Key 配置，再按 CLI 登录选项操作。切换账号可能退出原有登录；不要为了解决配置问题直接删除凭据文件或清空 Keychain。

settings.json 应该改哪一层

临时终端变量适合先验证；需要多个项目使用同一配置时，可编辑用户设置，需要仅在某个项目使用时，可编辑本地项目设置。合并到已有 JSON 中，不要用一条覆盖写入命令替换整个文件。

通常优先级为：托管设置 → 命令行 → 本地项目 → 共享项目 → 用户设置。env 内的变量逐个按设置优先级合并；同一个变量同时出现在 shell 和设置文件的 env 中时，设置文件值生效。权限列表等数组通常合并，不能把所有字段理解为“高层整个覆盖低层”。设置优先级、环境变量加载规则

下面是一个用户或本地项目设置的结构示例，地址和 token 都是占位值，需换成管理员提供的真实值；不要将这段带秘密的配置放进共享项目文件：

{
  "model": "sonnet",
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_YOUR_GATEWAY_TOKEN"
  }
}

Claude Code 的 settings 文件要求严格 JSON，不接受注释或末尾多余逗号。已有 env 对象时，在对象中增加或修改相应键，保留其他设置。将本地文件加入 .gitignore 只能减少误提交风险，不会加密文件；仍需按团队要求保护凭据。

多数设置支持修改后重新加载，但 model 等启动设置应重新启动会话，或用对应会话命令调整。/status 可以显示加载的设置来源，却不会逐项列出每个键最终被哪一层覆盖；/config 是终端配置菜单，也不是查看全部 JSON 的通用命令。设置加载与编辑说明

在 Git 项目中，本地设置查找还可能涉及仓库根目录和主 worktree；不要以为换了子目录或 worktree，就一定拥有完全独立的配置。排查时以当前会话报告的来源为起点，再检查你有权限查看的对应设置。

中转网关：地址、认证方式和模型要一起匹配

拿到网关地址后，先向管理员确认三个信息：基础地址、凭据放在哪个 HTTP header、允许使用的模型名称。只设置 ANTHROPIC_BASE_URL 不会自动切换成 API Key 计费；原有登录仍可能作为请求凭据，需要网关支持相应 OAuth 转发。网关认证与计费边界

例如，管理员明确提供的是 Bearer token，就可以在 Bash 中临时输入凭据并从同一终端启动：

export ANTHROPIC_BASE_URL="https://gateway.example.com"
read -r -s -p "输入已有的网关 Bearer token：" ANTHROPIC_AUTH_TOKEN
printf '\n'
if [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then
  export ANTHROPIC_AUTH_TOKEN
  claude
else
  printf '未输入 token，未启动 Claude Code。\n'
fi

将地址换成你的真实网关基础地址。若网关明确要求 x-api-key，改用前面的 API Key 输入方式，同时设置该地址；不要同时随意填入两种凭据。网关连接配置

网关还必须支持 Claude Code 所需的接口格式。常规 Anthropic Messages 接口使用 /v1/messages，并需要正确处理版本、beta header 和请求内容；Bedrock 与 Google Cloud 格式有另外的开关和协议要求。仅提供 OpenAI /v1/chat/completions 地址，不能证明能接入 Claude Code；地址可访问也不能证明任意非 Claude 模型兼容。 网关协议要求 遇到 system、developer 或工具角色不受支持的 400，按消息角色与协议排查检查实际请求字段和位置。

配置好后，核对 /status 中的基础地址与认证来源，再发送真实消息。地址不对，先检查设置覆盖和环境继承；出现 401，检查凭据是否有效、header 是否匹配；模型错误则核对允许的模型名称。一个未知模型错误或 404 本身不足以证明推理成功。成功响应之后，如需确认费用归属，还要查看对应网关或上游用量记录。

凭据优先级：为什么有 Key 却走了别的入口

对普通本地 CLI 会话，官方认证规则需要结合开关和当前模式来看：

这张表用于排查普通 CLI 配置，不能套到所有入口。已经登录的 Claude apps gateway 位于这条普通选择链之外，并可优先于云平台；Anthropic 托管的 cloud session 也不按本机 Key 环境变量切换认证。 组织的 forceLoginMethod、allowedProviders 等策略还可能限制本地选择。完整认证规则与例外

在你自己的 Bash 终端中，可以只检查常见变量是否非空，避免输出值：

for name in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL \
  CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX CLAUDE_CODE_USE_FOUNDRY; do
  if [ -n "${!name}" ]; then
    printf '%s：已设置\n' "$name"
  else
    printf '%s：未设置或为空\n' "$name"
  fi
done

这只检查当前 shell，不能发现所有 settings、helper 或管理员下发的配置，也不能证明云平台开关值为 1。结合 /status 查看当前会话。确认某项是你不再需要的个人临时配置后，再移除或调整它；不要为了抢占优先级绕过企业策略、删除全部配置或清空登录存储。

模型怎么设置，怎样只改本次会话

修改网关地址不会自动修改模型名称。API 直连使用可访问的模型 ID；Bedrock 可能使用 inference profile ARN；Foundry 使用实际部署名称；Google Cloud 使用对应平台的模型版本标识。sonnet 等别名解析结果可能随 provider 和 CLI 版本变化，部署时应核对实际可用名称。模型配置说明

通常选择顺序是当前会话的 /model、启动参数 --model、ANTHROPIC_MODEL、settings 的 model，最后才是 ANTHROPIC_DEFAULT_MODEL。default 表示返回账号或运行环境的默认选择，不是一个固定模型 ID；availableModels 等组织限制仍有效。恢复历史会话时还可能涉及已保存的会话模型，不能单凭新终端中的环境变量推断最终结果。当前模型选择与保存规则

Bedrock、Vertex 和 Foundry 的配置入口

如果公司已经提供云平台访问权限，按对应平台配置，不要把三者都写成普通网关 Key。以下是已有授权和可用模型前提下的必要字段方向，完整账号、区域与权限准备见各平台文档。

来源：Bedrock 配置、Google Cloud 配置、Foundry 配置。这些配置不能授予账号本来没有的模型访问权，也不保证所有模型在每个区域可用。

Foundry 的认证优先级是 ANTHROPIC_FOUNDRY_AUTH_TOKEN、ANTHROPIC_FOUNDRY_API_KEY，再到 Azure SDK 默认凭据链；Bearer token 方式要求 v2.1.203 或更高版本。它没有启动时的模型检查，默认模型不在你的部署中时，首条请求仍会失败，所以应使用真实部署名称。Foundry 认证与部署配置

终端能用，VS Code 或 Desktop 为什么仍要求登录

从 Dock 或开始菜单打开的编辑器不会自动继承另一个终端临时导出的变量。更关键的是，不同入口有自己的凭据检查与网关配置位置。

VS Code 扩展的凭据预检

打开命令面板，选择 Preferences: Open User Settings (JSON)，在 VS Code 自己的用户设置中合并 claudeCode.environmentVariables。例如：

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "REPLACE_WITH_YOUR_GATEWAY_TOKEN" }
  ]
}

把占位值换成你获准使用的网关配置；若网关使用 x-api-key，相应改用 ANTHROPIC_API_KEY。该入口影响扩展启动前的凭据检查；单独写入 ~/.claude/settings.json 的 env 虽可传给子进程，却不会被扩展自己的登录预检读取。VS Code 网关配置

Desktop 的第三方推理设置

网关使用应用自己的第三方推理配置，不读取 CLI 的 ANTHROPIC_BASE_URL 或 settings 文件作为网关入口。未由管理员下发配置的设备，可通过 Help → Troubleshooting → Enable Developer Mode 重启应用，再打开 Developer → Configure Third-Party Inference 填写网关地址；管理员配置优先。启用后仅支持本地会话，SSH、云环境和 Remote Control 有限制。Desktop 网关设置与限制

怎么确认 API 配置真的生效

依次确认三个结果，每一步回答的问题不同：

1. 配置加载正确。 CLI 的 /status 显示预期 provider、认证来源和基础地址；模型与设置来源也符合预期。这里只证明当前配置选择。
2. 真实请求正常。 在这个会话中发一条简短消息，得到正常模型响应；需要编码能力时，再在可恢复的测试项目中检查必要工具操作。仅启动成功、地址可达或返回模型错误都不够。
3. 用量归属正确。 对照 Console、网关或云平台的实际记录，确认请求进入预期组织、项目或部署。模型响应不会单独证明该扣哪本账。

常见症状可按下表继续处理：

若组织明确禁止某个 provider 或自定义地址，就把结果交给管理员处理。配置排查的终点是预期入口完成真实请求并可核对用量，不是为了出现“已连接”而不断删除认证或放宽权限。官方网关验证步骤

常见问题

Claude Code 必须购买订阅才能使用 API Key 吗？

不必把订阅登录作为 API Key 使用的前提。API Key 是独立的认证方式，需要 Console API 使用资格与额度；交互式 CLI 使用环境变量 Key 时需要批准。Console 无 Key 登录还提供另一条按 API 入口使用的方式。认证入口

ANTHROPIC_API_KEY 一设置就会覆盖订阅吗？

交互模式需要批准使用，并保存选择；-p 非交互模式在存在 Key 时使用它，但仍需考虑更高优先级认证、企业策略和特殊入口。用 /status 确认当前凭据来源，再核对实际用量记录。API Key 行为

ANTHROPIC_BASE_URL 能直接接任意模型吗？

不能这样推断。它改变请求目标，模型名称仍需单独配置；目标网关必须支持所需协议和 Claude Code 工作流。仅有 OpenAI 格式地址或网关宣传“兼容”，不足以证明任意模型可用。网关兼容要求

/model 只影响当前会话吗？

当前文档中，普通选择确认和 /model <名称> 会保存用户默认值；只改当前会话应在选择器中按 s，只改本次启动则用 --model。后续启动仍受项目配置和组织限制影响。模型保存规则