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

> 已有 Anthropic API Key，就设置 ANTHROPIC_API_KEY 并在交互模式批准使用；已有企业网关，就按其认证方式配置地址和凭据。settings 文件可能覆盖终端变量，模型与 VS Code、Desktop 入口还需分别设置。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-api-configuration
- Published: 2026-04-21
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, Claude API, Anthropic, API Configuration, Developer Tools

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

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

| 你已有的入口或凭据 | 应怎样配置 |
| --- | --- |
| Anthropic Console API Key | 设置 `ANTHROPIC_API_KEY`；交互启动后批准使用 |
| Claude 订阅账号 | 使用 Claude 账号登录；不需要为了启动 CLI 再创建 API Key |
| Console 账号，但没有创建 Key | 当前 CLI 支持 Console 登录生成 Anthropic profile，需满足版本与组织策略条件 |
| 公司网关地址和凭据 | 设置地址，并按 `Authorization: Bearer` 或 `x-api-key` 选择变量 |
| AWS、Google Cloud 或 Azure 的 Claude 访问权限 | 使用对应云平台开关、凭据和模型标识，不能只填 Anthropic Key |

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

## 直接使用 Anthropic API Key

准备好已有的 Console Key、可用 API 额度和 Claude Code CLI。尚未安装 CLI 时，先按[官方快速入门](https://code.claude.com/docs/en/quickstart)完成安装。不要把网关 token、Claude 登录 cookie 或 Azure Key 当成 Anthropic Console Key。

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

~~~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 请求可能产生费用。[认证与批准规则](https://code.claude.com/docs/en/authentication)

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

~~~bash
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 登录条件](https://code.claude.com/docs/en/authentication)

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

## settings.json 应该改哪一层

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

![Claude Code 从管理员托管到用户设置的通常优先级，以及同名 env 变量和共享秘密的注意事项](https://blog.laozhang.ai/posts/zh/claude-code-api-configuration/img/settings-precedence.webp)

| 设置范围 | 文档中的路径或入口 | 适合存放什么 |
| --- | --- | --- |
| 用户设置 | `~/.claude/settings.json`；Windows 为 `%USERPROFILE%\.claude\settings.json` | 个人默认模型及经组织允许的个人配置 |
| 共享项目设置 | `.claude/settings.json` | 团队共享的非秘密配置 |
| 本地项目设置 | `.claude/settings.local.json` | 个人在该项目的配置；手工创建时先排除 Git 跟踪 |
| 命令行参数 | 如 `--model`、`--settings` | 一次启动的配置覆盖，不能设置所有管理类字段 |
| 管理员托管设置 | 组织下发 | 强制策略、允许的 provider 或网关等 |

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

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

~~~json
{
  "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 的通用命令。[设置加载与编辑说明](https://code.claude.com/docs/en/settings)

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

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

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

| 网关要求的认证方式 | Claude Code 中的配置 |
| --- | --- |
| `Authorization: Bearer …` | `ANTHROPIC_AUTH_TOKEN` |
| `x-api-key: …` | `ANTHROPIC_API_KEY`，交互模式仍有 Key 批准步骤 |
| 由凭据库动态获取 | 按组织方案配置 `apiKeyHelper`；它发送两种 header |

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

~~~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 输入方式，同时设置该地址；不要同时随意填入两种凭据。[网关连接配置](https://code.claude.com/docs/en/llm-gateway-connect)

网关还必须支持 Claude Code 所需的接口格式。常规 Anthropic Messages 接口使用 `/v1/messages`，并需要正确处理版本、beta header 和请求内容；Bedrock 与 Google Cloud 格式有另外的开关和协议要求。**仅提供 OpenAI `/v1/chat/completions` 地址，不能证明能接入 Claude Code；地址可访问也不能证明任意非 Claude 模型兼容。** [网关协议要求](https://code.claude.com/docs/en/llm-gateway-protocol) 遇到 `system`、`developer` 或工具角色不受支持的 `400`，按[消息角色与协议排查](https://blog.laozhang.ai/zh/posts/api-400-role-system-is-not-supported-on-this-model)检查实际请求字段和位置。

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

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

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

| 存在的配置 | 何时影响当前会话 |
| --- | --- |
| Bedrock、Vertex 或 Foundry 凭据 | 设置对应 `CLAUDE_CODE_USE_*` 开关后，才选择该云平台认证 |
| `ANTHROPIC_AUTH_TOKEN` | 以 Bearer token 认证，通常先于 API Key 和已保存登录 |
| `ANTHROPIC_API_KEY` | 交互模式按已保存的批准选择使用；`-p` 模式在存在时使用 |
| `apiKeyHelper` | 在更高优先级来源没有接管时，按配置获取凭据 |
| OAuth token、profile 或账号登录 | 还受 profile 类型、是否显式选择及企业策略影响 |

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

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

~~~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 版本变化，部署时应核对实际可用名称。[模型配置说明](https://code.claude.com/docs/en/model-config)

| 你的目的 | 使用方式 | 是否保存为后续默认值 |
| --- | --- | --- |
| 交互中更换并保存默认模型 | `/model` 选择后按 Enter，或 `/model <模型名>` | 会保存用户默认值 |
| 只修改当前会话 | `/model` 选择器中按 `s` | 不保存默认值 |
| 只指定本次启动 | `claude --model <模型名>` | 不保存默认值 |
| 通过启动环境指定 | `ANTHROPIC_MODEL` | 环境影响本次启动，不由 CLI 保存为默认值 |
| 在配置文件中设默认值 | `"model": "sonnet"` 或可用的完整名称 | 按文件作用范围生效 |

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

## Bedrock、Vertex 和 Foundry 的配置入口

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

| 平台 | 选择开关和连接信息 | 凭据与模型条件 |
| --- | --- | --- |
| AWS Bedrock | `CLAUDE_CODE_USE_BEDROCK=1`；区域可由 AWS profile 或 `AWS_REGION` 提供 | 使用 AWS 凭据链并拥有模型访问权限；SSO 登录区域不一定是模型所在区域 |
| Google Cloud Agent Platform，原 Vertex AI | `CLAUDE_CODE_USE_VERTEX=1`、`CLOUD_ML_REGION`、`ANTHROPIC_VERTEX_PROJECT_ID` | 需要适用 Google 凭据、API、配额和模型权限；请求项目以这里指定的项目为准 |
| Microsoft Foundry | `CLAUDE_CODE_USE_FOUNDRY=1`；`ANTHROPIC_FOUNDRY_RESOURCE` 填资源名称，或用 `ANTHROPIC_FOUNDRY_BASE_URL` 填完整地址 | 使用该资源的凭据与真实 Claude 部署名称；资源名称字段不能填 URL |

来源：[Bedrock 配置](https://code.claude.com/docs/en/amazon-bedrock)、[Google Cloud 配置](https://code.claude.com/docs/en/google-vertex-ai)、[Foundry 配置](https://code.claude.com/docs/en/microsoft-foundry)。这些配置不能授予账号本来没有的模型访问权，也不保证所有模型在每个区域可用。

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

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

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

### VS Code 扩展的凭据预检

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

~~~json
{
  "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 网关配置](https://code.claude.com/docs/en/llm-gateway-connect#vs-code-extension)

### Desktop 的第三方推理设置

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

## 怎么确认 API 配置真的生效

![通过配置加载、真实请求和供应商用量记录，分别确认 Claude Code 的入口、响应与费用归属](https://blog.laozhang.ai/posts/zh/claude-code-api-configuration/img/configuration-verification.webp)

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

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

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

| 症状 | 先检查什么 |
| --- | --- |
| 导出 Key 后仍是原账号 | 交互批准选择、settings 同名变量、是否从同一终端启动 |
| `/status` 中地址仍是旧网关 | 高优先级文件 `env`、管理员配置、当前启动环境 |
| 地址正确但 `401` | 凭据有效期、所属网关、Bearer 与 `x-api-key` 是否匹配 |
| 报模型不可用 | provider 的真实模型 ID、部署名称和访问权限 |
| 终端正常，扩展登录预检失败 | VS Code 自己的 `claudeCode.environmentVariables` |
| 修改 settings 后模型没变 | 模型是启动设置；重新启动或在会话中使用 `/model` |

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

## 常见问题

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

不必把订阅登录作为 API Key 使用的前提。API Key 是独立的认证方式，需要 Console API 使用资格与额度；交互式 CLI 使用环境变量 Key 时需要批准。Console 无 Key 登录还提供另一条按 API 入口使用的方式。[认证入口](https://code.claude.com/docs/en/authentication)

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

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

### `ANTHROPIC_BASE_URL` 能直接接任意模型吗？

不能这样推断。它改变请求目标，模型名称仍需单独配置；目标网关必须支持所需协议和 Claude Code 工作流。仅有 OpenAI 格式地址或网关宣传“兼容”，不足以证明任意模型可用。[网关兼容要求](https://code.claude.com/docs/en/llm-gateway-protocol)

### `/model` 只影响当前会话吗？

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

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-07。

- [官方认证说明](https://code.claude.com/docs/en/authentication) (code.claude.com)
- [官方快速入门](https://code.claude.com/docs/en/quickstart) (code.claude.com)
- [设置优先级](https://code.claude.com/docs/en/settings) (code.claude.com)
- [环境变量加载规则](https://code.claude.com/docs/en/llm-gateway-connect) (code.claude.com)
- [网关认证与计费边界](https://code.claude.com/docs/en/llm-gateway) (code.claude.com)
- [网关协议要求](https://code.claude.com/docs/en/llm-gateway-protocol) (code.claude.com)
- [模型配置说明](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [Bedrock 配置](https://code.claude.com/docs/en/amazon-bedrock) (code.claude.com)
- [Google Cloud 配置](https://code.claude.com/docs/en/google-vertex-ai) (code.claude.com)
- [Foundry 配置](https://code.claude.com/docs/en/microsoft-foundry) (code.claude.com)