将 Claude Code 连接到 LLM 网关

将 Claude Code 指向组织的 LLM 网关。先检查管理员是否已完成配置；如果尚未配置，可自行设置 CLI、VS Code、GitHub Actions 和 Agent SDK 使用的基础 URL 与凭证，然后验证连接并排查网关错误。

LLM 网关是由组织运行的代理，位于 Claude Code 与模型提供商之间。当组织使用 LLM 网关时，Claude Code 会使用组织签发的凭证向网关进行身份验证，而不是使用你的个人 claude.ai 登录信息。

本页面面向通过组织自建网关运行 Claude Code 的开发者，介绍两种配置路径：检查管理员是否已为你完成配置，以及管理员尚未配置时自行配置。

检查现有配置

管理员可以通过托管设置、设备管理或 apiKeyHelper 分发网关地址和凭证。这样 Claude Code 启动时便会自动读取，无需你进行任何设置。可以按以下步骤检查组织是否已经完成配置：

如果 /status 菜单中的两行信息均正确，但向 Claude 发送消息仍然失败，请参阅故障排除表。

自行配置 Claude Code

若要自行配置 Claude Code 以使用网关，需要向网关团队获取：

• 网关的基础 URL
• 凭证：密钥或 Token 字符串，或者用于获取凭证的命令
  • 如果网关团队没有说明凭证类型，请参阅下文的凭证变量部分，了解可尝试的方式

以下各节按配置顺序编排：

• 设置凭证变量并设置基础 URL：每个网关连接都需要设置这两个变量
• 验证连接：在持久保存任何设置之前确认连接正常
• 配置各运行界面：如果除了 Claude Code CLI 之外还使用 VS Code 等运行界面，请了解如何为其配置网关凭证
• 其他配置：部分网关除了基础 URL 和凭证外，还需要设置其他变量，例如自定义标头、凭证辅助程序、模型发现或提供商格式的基础 URL。仅当管理员明确要求时才设置这些变量

设置凭证变量

若要让 Claude Code 向网关进行身份验证，请在环境变量中设置凭证。具体使用哪个变量，取决于网关团队提供的信息：

如果对方没有说明凭证类型，请使用 ANTHROPIC_AUTH_TOKEN；下文的验证请求会帮助你判断是否需要改用另一个变量。

设置基础 URL 和凭证

将网关的基础 URL 以及上文选定的凭证变量设置为环境变量。示例使用 ANTHROPIC_AUTH_TOKEN；如果你选择的是另一个变量，请将其替换为 ANTHROPIC_API_KEY。可以在 shell 中设置，有效期为一个终端会话；也可以在 Claude Code 设置文件中设置，使其在 Claude Code 的所有运行位置持久生效。

首次连接时，请先使用 shell export，并在将值移入设置文件之前运行验证请求。

设置为 shell 环境变量

将以下值替换为网关团队提供的值：

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

shell export 仅适用于当前终端会话以及从该会话启动的程序；从 Dock 或“开始”菜单启动的编辑器无法读取这些变量。若要让变量在新终端中持续生效，请将相同的行添加到 shell 配置文件，例如 ~/.zshrc、~/.bashrc 或 PowerShell $PROFILE；也可以改用设置文件。

在设置文件中设置

若要让配置在 Claude Code 的所有运行位置生效，而不依赖 shell，请在设置文件的 env 块中设置变量。设置文件具有不同的作用域：

• ~/.claude/settings.json 适用于你的所有项目。在 Windows 上，路径为 %USERPROFILE%\.claude\settings.json
• .claude/settings.local.json 仅适用于一个项目。Claude Code 创建该文件时会将其添加到 gitignore；如果自行创建，请先手动将其添加到 gitignore，避免意外提交凭证

无论使用哪一种文件，env 块的写法都相同：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

如果 shell export 和设置文件的 env 块设置了同一变量，以设置文件中的值为准。运行 /status 可查看 Claude Code 当前使用的基础 URL 和凭证来源。

验证连接

在 shell 中导出变量后，直接向网关发送一个只请求一个 Token 的请求。这样可以在打开 Claude Code 之前确认 URL 和凭证有效；如果失败，问题出在网关，而不是 Claude Code 配置。以下命令会读取 shell 变量，因此即使已经将值放入设置文件，也必须先完成 shell export。

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

如果网关要求在 x-api-key 标头中传递密钥，请在 Bash 命令中将 Authorization 标头替换为 x-api-key: $ANTHROPIC_API_KEY；在 PowerShell 命令中，则将 "Authorization" 哈希表条目替换为 "x-api-key" = "$env:ANTHROPIC_API_KEY"。

如果 JSON 响应以 {"id":"msg_ 开头并包含 "content":[...] 字段，说明网关可访问且凭证有效。即使错误提示模型未知，也能证明 URL 和凭证有效，因为网关先对请求进行了身份验证，然后才拒绝模型名称；此项测试不必特意寻找网关支持的模型。401 表示凭证被拒绝：如果此前只是猜测应使用哪个变量，请改用另一个变量并重新导出。

在 Claude Code 中确认

从同一 shell 启动 claude，使其继承导出的变量；发送一条消息，然后运行 /status。

在 Status 标签页中，Anthropic base URL 行应当显示网关地址，这说明请求正在路由到该网关；如果没有此行，说明变量未传入会话。如果 Auth token 或 API key 行显示的是你设置的变量，说明当前生效的是网关凭证，而不是已保存的 claude.ai 登录信息。

如果消息发送失败，或者 /status 没有显示网关 URL，请参阅下文的故障排除表。

凭证变量与标头的对应关系

不同变量会将凭证放入不同的 HTTP 标头：ANTHROPIC_AUTH_TOKEN 对应 Authorization: Bearer，ANTHROPIC_API_KEY 对应 x-api-key，apiKeyHelper 则同时使用两者。如果将凭证放在错误的变量中，凭证会通过网关不读取的标头发送，请求将以 401 失败。如果验证请求返回 401，请改用另一个变量后重试。

与现有登录信息冲突

网关凭证变量的优先级高于已保存的 claude.ai 登录信息或 Console 密钥。设置该变量后，claude.ai 登录信息会继续保存在本地，但不会使用；取消设置变量后，Claude Code 会重新使用该登录信息。使用 ANTHROPIC_AUTH_TOKEN 时，变量会立即取得优先权。使用 ANTHROPIC_API_KEY 时，交互模式会提示一次，要求你批准该密钥，然后密钥才会生效。

运行 /status 可确认当前生效的凭证来源。如果启动时显示身份验证冲突警告并列出两个来源，请参阅故障排除表的第一行，了解应当移除哪一个来源。若要清除已保存的登录信息，只保留网关凭证，请运行 /logout。

配置各运行界面

CLI 会读取上述环境变量和设置文件。其他运行界面包括 VS Code 扩展、桌面应用、GitHub Actions、Agent SDK，以及 Slack 和 Web 等云端运行界面。以下各节说明上述设置是否会传递到这些运行界面。

VS Code 扩展

请在 claudeCode.environmentVariables 中为 VS Code 扩展设置网关变量。该项位于 VS Code 自身的用户设置中，可通过 Preferences: Open User Settings (JSON) 命令打开。扩展会先从此设置检查凭证，再启动进程，因此应当在这里可靠地配置网关凭证；~/.claude/settings.json 中的值可以传入所启动的进程，但扩展自身的登录检查无法读取。

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

桌面应用

桌面应用通过管理员分发的配置读取网关路由，而不是读取 ANTHROPIC_BASE_URL 或 settings.json。如果组织已经分发该配置，桌面应用无需你进行任何设置便会通过网关路由流量；如果尚未分发，请使用终端 CLI 或 VS Code 扩展建立网关会话。管理员可以按照组织推广部署中的说明分发配置。

如果桌面应用显示 Gateway was unreachable，说明应用启动时无法访问配置的基础 URL；请使用上文的 curl 测试检查 URL 和网络路径。

GitHub Actions

Claude Code GitHub Actions 从工作流的 env 块读取 ANTHROPIC_BASE_URL 和 ANTHROPIC_CUSTOM_HEADERS。将凭证作为 Action 的 anthropic_api_key 输入传递；Action 会将它设置为 ANTHROPIC_API_KEY，因此凭证会通过 x-api-key 标头到达网关。

对于使用 x-api-key 的网关，请在 env 中设置基础 URL，并将网关密钥作为输入传递：

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

对于使用 Bearer Token 的网关，请将同一密钥传递两次：一次作为 anthropic_api_key 输入，另一次作为工作流 env 块中的 ANTHROPIC_AUTH_TOKEN。Action 要求在启动 Claude Code 之前提供 anthropic_api_key、CLAUDE_CODE_OAUTH_TOKEN 或工作负载身份联合，而且它不会读取 ANTHROPIC_AUTH_TOKEN，因此这里的输入只是为了通过启动检查。环境变量才会将密钥放入网关所读取的 Authorization 标头；x-api-key 中的副本会被忽略：

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

有关该 Action 的其他身份验证选项（包括 CLAUDE_CODE_OAUTH_TOKEN 和工作负载身份联合），请参阅 Claude Code GitHub Actions 和 Action 的 README。

Agent SDK

Agent SDK 没有网关专用选项；它会将环境变量传递给自己启动的 Claude Code 进程。每种 SDK 都接受 env 选项，用于设置所启动进程的环境；TypeScript 和 Python SDK 的处理方式不同：

• TypeScript：默认情况下，所启动的进程继承父进程环境；但设置 options.env 会完整替换环境。请将 process.env 展开到其中，以保留网关变量。
• Python：ClaudeAgentOptions(env=...) 会与继承的环境合并，因此父进程中设置的网关变量无需展开即可传入。

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

Slack、Web 和 Remote Control

Claude Code in Slack 和 Claude Code on the web 是由 Anthropic 托管的产品，始终使用 Anthropic API，不属于网关部署的一部分。在云端会话的环境配置中设置网关变量不会生效。如果流量必须始终经过网关，请不要为这些用户启用上述运行界面。

Remote Control 和语音听写均依赖 claude.ai 身份：Remote Control 使用该身份将实时会话与你的账号配对，语音听写则使用该身份访问 claude.ai 转录端点。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 生效时，这两项功能均不可用。自 v2.1.196 起，如果 ANTHROPIC_BASE_URL 指向非 Anthropic 主机，Remote Control 也会被禁用，因此仅登录 claude.ai 还不够。

若要恢复任一功能，请使用 claude.ai 登录，并取消设置该功能检查的网关变量。claude doctor 的 Remote Control 部分会列出需要取消设置的凭证变量。

• 语音听写：取消设置网关凭证
• Remote Control：取消设置网关凭证和 ANTHROPIC_BASE_URL

其他配置

以下设置适用于基础 URL 和凭证之外的情况。仅当管理员的说明或故障排除表要求使用其中某项设置时，才进行配置。

发送其他标头

除凭证外，部分网关还使用自定义标头来路由请求或为请求添加标签，例如租户标识符或路由键。若要发送自定义标头，请设置 ANTHROPIC_CUSTOM_HEADERS，每行填写一个 Name: Value 对。以下示例添加名为 X-Org-Route 的路由标头：

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

也可以在设置文件的 env 块中设置 ANTHROPIC_CUSTOM_HEADERS。由于 JSON 字符串不能跨越多行，请在多个键值对之间使用 \n：

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"
  }
}

将网关模型添加到模型选择器

模型发现会在启动时向网关查询模型列表，并将这些名称与内置条目一同添加到 /model 选择器。

如果网关提供的模型名称不在 Claude Code 的内置列表中，并且你希望从选择器中选择它们，请启用模型发现。如果使用的都是内置模型，则无需启用；管理员也可能已经通过托管设置将其启用。

若要启用，请在 shell 中或 ~/.claude/settings.json 的 env 块中设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。模型发现需要 Claude Code v2.1.129 或更高版本。

发现的模型会显示为额外的 /model 条目，并带有 From gateway 标签。若要确认发现流程已经运行，请启动 claude --debug 并查找 [gatewayDiscovery] 行：成功时会记录缓存的模型数量，404、超时或重定向也会记录在其中。有关发现流程的运行时机、过滤规则以及网关应提供的响应格式，请参阅模型发现参考。

使用 apiKeyHelper 轮换凭证

apiKeyHelper 是 Claude Code 用来获取网关凭证的命令，可替代从静态环境变量读取凭证的方式。

如果凭证按计划过期、来自保险库或 SSO 命令，或者管理员明确要求配置辅助程序，请使用辅助程序。如果凭证是只需设置一次的固定字符串，只需设置凭证变量，可以跳过本节。

辅助程序可以是任何将当前凭证输出到 stdout 的 shell 命令。Claude Code 会通过系统 shell 运行它，因此在 Windows 上，它可以是可执行文件或 PowerShell 调用。编写脚本、赋予其执行权限，然后在设置文件中通过 apiKeyHelper 引用：

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

vault kv get -field=api_key secret/llm-gateway/claude-code

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude Code 默认将辅助程序的输出缓存五分钟，并在请求返回 HTTP 401 时重新运行辅助程序。若要更改缓存时长，请以毫秒为单位设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS，例如设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 表示 15 分钟。

辅助程序返回的值会同时通过 Authorization 和 x-api-key 标头发送，因此无论网关读取哪一个标头都可以正常使用。

通过网关路由到云提供商

这些配置不使用 ANTHROPIC_BASE_URL，而是通过提供商专用的基础 URL 变量，将 Claude Code 指向网关。Amazon Bedrock 和 Google Cloud's Agent Platform 网关接受相应提供商的原生请求格式；Microsoft Foundry 和 Claude Platform on AWS 网关接受 Anthropic Messages 格式，差别仅在于使用哪个基础 URL 变量。

仅当网关团队明确指定 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 时，才使用相应配置。如果上文的验证请求返回 JSON，可以跳过本节。

设置网关团队所指定提供商的配置块。跳过身份验证变量会指示 Claude Code 不使用提供商凭证签署请求，因为这些凭证由网关持有。如果网关还需要自己的 Token，请在配置块之后添加 ANTHROPIC_AUTH_TOKEN；Microsoft Foundry 除外，它使用如下所示的 ANTHROPIC_FOUNDRY_API_KEY。如果 Microsoft Foundry 网关需要 Bearer Token，可以改用 ANTHROPIC_FOUNDRY_AUTH_TOKEN；同时设置两个变量时，该变量的优先级高于 ANTHROPIC_FOUNDRY_API_KEY。ANTHROPIC_FOUNDRY_AUTH_TOKEN 需要 Claude Code v2.1.203 或更高版本。

Amazon Bedrock

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

Google Cloud's Agent Platform

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

Microsoft Foundry

将网关凭证放入 ANTHROPIC_FOUNDRY_API_KEY；它会以 x-api-key 标头发送到网关。如果网关需要 Bearer Token，可以改用 ANTHROPIC_FOUNDRY_AUTH_TOKEN。Claude Code 会将该值作为 Authorization: Bearer 标头发送；同时设置两个变量时，该变量的优先级高于 ANTHROPIC_FOUNDRY_API_KEY。需要 Claude Code v2.1.203 或更高版本。

如果网关会自行注入 Authorization 标头，请设置 CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1，并且不要设置上述两个凭证变量。这样 Claude Code 会在不附带 Azure 凭证的情况下发送请求，并保留你提供的 Authorization 标头，例如通过 ANTHROPIC_CUSTOM_HEADERS 提供的标头。在 v2.1.203 之前，如果设置 CLAUDE_CODE_SKIP_FOUNDRY_AUTH 但未提供 API 密钥，Microsoft Foundry 客户端将无法发送请求。

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

Claude Platform on AWS

工作区 ID 请参阅 Claude Platform on AWS。

export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

排查网关错误

以下是通过网关运行 Claude Code 时最常见的错误，以及网关侧原因和解决方法：

如果移除网关配置后 Claude Code 仍反复提示登录，通常是凭证存储导致，而不是网关本身；请参阅身份验证错误。

相关资源

• LLM 网关概览：网关的作用及其与 claude.ai 订阅的交互方式
• 为组织推广部署 LLM 网关：面向管理员的网关配置部署与分发清单
• 网关协议参考：Claude Code 向网关发送的内容，包括网关必须转发的标头和字段
• 设置：设置文件的位置以及 env 块的读取方式
• 身份验证：凭证变量、apiKeyHelper 与 OAuth 登录的交互方式