Claude Code 学习站

Claude Code 连接 LLM 网关参考

整理 Claude Code 连接企业 LLM 网关所需的环境变量、settings.json 配置项、各接入面(CLI/VS Code/GitHub Actions/Agent SDK)配置方式及常见错误排查表。

本页目录20
AI 摘要 · 已核查整理于 2026-06-13原文:Connect Claude Code to an LLM gateway(Anthropic)Claude CodeLLM网关环境变量参考文档
要点速览
  • 凭证变量二选一:「ANTHROPIC_AUTH_TOKEN」对应 Bearer Token,发送到 Authorization 头;「ANTHROPIC_API_KEY」对应 API Key,发送到 x-api-key 头;凭证轮换用「apiKeyHelper」
  • 必须同时设置「ANTHROPIC_BASE_URL」(网关地址)与凭证变量,可写入 shell 或 settings.json 的「env」块,settings.json 优先级高于 shell 导出
  • VS Code 插件需在 claudeCode.environmentVariables 中单独设置,桌面版走管理员分发配置而非这两个变量,Slack/Web/Remote Control 不支持网关
  • 可用 curl 直接验证网关连通性:返回以 {"id":"msg_ 开头的 JSON 即为成功,401 说明凭证放错了请求头
  • 路由到 Amazon Bedrock / Google Cloud Agent Platform / Microsoft Foundry / Claude Platform on AWS 网关需使用对应厂商专属的 BASE_URL 与 SKIP_AUTH 变量
  • 常见报错(401、ECONNREFUSED、400 context_management、模型未出现在选择器中等)对应的原因与修复方式已整理成表

本文是对 Claude Code 官方参考页「Connect Claude Code to an LLM gateway」的中文整理,完整与最新内容以原文为准:https://code.claude.com/docs/en/llm-gateway-connect

概述

LLM 网关(LLM gateway)是组织架设在 Claude Code 与模型提供方之间的代理。使用网关时,Claude Code 用组织签发的凭证认证,而非个人 claude.ai 登录。本页面覆盖两条路径:检查管理员是否已配置好网关,以及自行配置网关。

相关参考:

主题链接
组织侧部署网关「Roll out an LLM gateway」(/en/llm-gateway-rollout)
Claude Code 发给网关的协议内容「gateway protocol reference」(/en/llm-gateway-protocol)

检查是否已有现有配置

管理员可通过 managed settings、设备管理或「apiKeyHelper」分发网关地址与凭证,Claude Code 启动时自动读取。检查步骤:

  1. 运行 claude。若直接打开登录界面,说明未分发网关凭证,需自行配置。
  2. 若无需登录即进入会话,运行 /status 打开 Status 标签页,检查两行:
状态行含义
Anthropic base URL仅当设置了网关地址时才出现;若无此行,说明未指向网关
Auth token / API key出现「ANTHROPIC_AUTH_TOKEN」「ANTHROPIC_API_KEY」或「apiKeyHelper」字样,确认网关凭证生效;若显示「Login method」为 claude.ai 账户,说明凭证未分发
  1. 关闭 /status 菜单,发送一条测试消息,正常返回且无报错即确认网关连通。

自行配置 Claude Code

需要从网关团队获取:网关的 base URL;一个凭证(key/token 字符串,或获取凭证的命令)。

设置凭证变量

凭证写入位置使用场景
ANTHROPIC_AUTH_TOKEN网关团队说的是「bearer token」或「Authorization header」
ANTHROPIC_API_KEY网关团队说的是「API key」或「x-api-key」
apiKeyHelper凭证会轮换,或来自 vault

若未被告知类型,先用 ANTHROPIC_AUTH_TOKEN,通过验证请求判断是否需要切换。

设置 base URL 与凭证

可在 shell(仅当前终端会话有效)或 Claude Code 的 settings 文件(所有运行环境持久生效)中设置。首次连接建议先用 shell 导出并完成验证请求,再迁移到 settings 文件。

Bash / Zsh:

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

PowerShell:

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

shell 导出仅对该终端会话及其启动的程序生效,需持久化可写入 ~/.zshrc~/.bashrc 或 PowerShell 的 $PROFILE,或使用 settings 文件。

settings 文件作用域:

文件路径作用范围
~/.claude/settings.json(Windows:%USERPROFILE%\.claude\settings.json)应用于你所有项目
.claude/settings.local.json应用于单个项目;Claude Code 创建该文件时会自动加入 gitignore

⚠️ 不要把凭证放进项目的 .claude/settings.json,该文件会被提交并与所有克隆该仓库的人共享。

env 块写法(两种 settings 文件相同):

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

若 shell 导出与 settings 文件的 env 块同时设置同一变量,以 settings 文件的值为准。可用 /status 查看当前生效的 base URL 与凭证来源。

验证连接

直接向网关发送一次性 token 请求验证(需要 shell 导出的变量,即使已写入 settings 文件也要导出):

Bash / Zsh:

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": "."}]}'

PowerShell:

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 头,把 Authorization 替换为 x-api-key: $ANTHROPIC_API_KEY(PowerShell 中对应替换 hashtable 项)。

返回结果含义
JSON 以 {"id":"msg_ 开头且含 "content":[...]网关可达且凭证有效
报错「未知模型名」同样说明 URL 与凭证均正确(网关先认证后拒绝模型名),无需找到网关实际支持的模型
401凭证被拒绝;若是猜测的变量,切换到另一个变量重新导出

在 Claude Code 中确认: 从同一 shell 启动 claude(继承导出的变量),发送消息后运行 /status。「Anthropic base URL」应显示网关地址;「Auth token」/「API key」行应显示你设置的变量名(而非 claude.ai 登录)。

凭证变量与 HTTP 头的映射

变量对应 HTTP 头
ANTHROPIC_AUTH_TOKENAuthorization: Bearer
ANTHROPIC_API_KEYx-api-key
apiKeyHelper同时发送到以上两个头

凭证放错变量会导致请求到达网关不读取的头,报 401

与已有登录的冲突

网关凭证变量优先级高于已保存的 claude.ai 登录或 Console key。ANTHROPIC_AUTH_TOKEN 立即生效优先;ANTHROPIC_API_KEY 会在交互模式下提示批准一次后才生效。取消设置变量后自动回退到已保存登录。运行 /status 确认当前凭证来源;运行 /logout 清除已保存登录,只保留网关凭证。

各接入面(Surface)配置

接入面配置方式
CLI读取环境变量与 settings 文件(如上)
VS Code 扩展在 VS Code 用户设置(JSON)的 claudeCode.environmentVariables 中设置;插件在启动前独立检查此设置,~/.claude/settings.json 中的值能传给子进程但不会通过插件自身的登录检查
桌面 App读取管理员分发的配置(非 ANTHROPIC_BASE_URLsettings.json);若未分发,需改用终端 CLI 或 VS Code 扩展;报错 Gateway was unreachable 表示启动时无法连接 base URL
GitHub Actions读取工作流 env 块中的 ANTHROPIC_BASE_URLANTHROPIC_CUSTOM_HEADERS;凭证通过 action 的 anthropic_api_key 输入传入,该 action 会将其设为 ANTHROPIC_API_KEY(走 x-api-key 头)
Agent SDK无网关专属选项,传递环境变量给它启动的 Claude Code 进程;TypeScript 的 options.env 会整体替换环境(需自行展开 process.env),Python 的 ClaudeAgentOptions(env=...) 是在继承环境之上合并
Slack / Web / Remote ControlClaude Code in Slack 与 Claude Code on the web 是 Anthropic 托管产品,始终使用 Anthropic API,不支持网关;Remote Control 与语音听写依赖 claude.ai 身份,在 ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/apiKeyHelper 生效时不可用(v2.1.196 起 ANTHROPIC_BASE_URL 指向非 Anthropic 主机时 Remote Control 同样禁用)

VS Code 扩展配置示例

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

GitHub Actions 配置示例

x-api-key 类型网关:

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 类型网关(同一 secret 传两处):

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 启动前要求提供 anthropic_api_keyCLAUDE_CODE_OAUTH_TOKEN 或 workload identity federation 三者之一,且不读取 ANTHROPIC_AUTH_TOKEN;上例中的 input 仅用于满足启动检查,真正让凭证进入 Authorization 头的是 env 块里的 ANTHROPIC_AUTH_TOKEN

Agent SDK 示例

// TypeScript
const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})
# Python
options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

若要恢复 Remote Control / 语音听写,需登录 claude.ai 并取消相应网关变量:

功能需取消的变量
语音听写网关凭证
Remote Control网关凭证 + ANTHROPIC_BASE_URL

/doctor 会指出需要取消设置的具体凭证变量。

附加配置

以下配置仅在管理员指示或排查报错时才需要设置。

发送额外请求头

设置「ANTHROPIC_CUSTOM_HEADERS」,每行一个 Name: Value 键值对,用于网关的租户标识或路由键等场景。

Bash / Zsh:

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

settings 文件(多个键值对用 \n 分隔):

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

将网关模型加入模型选择器(Model Discovery)

说明
作用启动时查询网关的模型列表,加入 /model 选择器(内置模型之外)
启用条件网关提供的模型名不在 Claude Code 内置列表中,且希望从选择器中选用
环境变量CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1(写入 shell 或 ~/.claude/settings.jsonenv 块)
版本要求Claude Code v2.1.129 及以上
展示方式发现的模型标注为「From gateway」
调试方式claude --debug,查看 [gatewayDiscovery] 日志行(成功会记录缓存的模型数量,404/超时/重定向也会记录)

用 apiKeyHelper 轮换凭证

说明
定义Claude Code 运行的一条命令,用于获取网关凭证,而非从静态环境变量读取
适用场景凭证按计划过期、来自 vault/SSO 命令,或管理员要求配置
运行方式任意打印凭证到 stdout 的 shell 命令;Claude Code 通过系统 shell 运行,Windows 上可以是可执行文件或 PowerShell 调用
配置键settings 文件中的 apiKeyHelper
缓存时长默认 5 分钟,请求返回 HTTP 401 时会重新运行
缓存时长变量CLAUDE_CODE_API_KEY_HELPER_TTL_MS(单位毫秒,如 900000 表示 15 分钟)
发送位置同时发送到 Authorizationx-api-key 两个头

Bash 示例脚本:

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code
{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

PowerShell 示例:

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

通过网关路由到云厂商原生格式

仅当网关团队明确说明使用以下之一时才配置。Amazon Bedrock 与 Google Cloud Agent Platform 网关接受各自厂商原生请求格式;Microsoft Foundry 与 Claude Platform on AWS 网关接受 Anthropic Messages 格式,区别仅在于 base URL 变量。SKIP_AUTH 类变量表示不用提供方凭证签名请求(网关持有该凭证);如网关自身需要 token,追加 ANTHROPIC_AUTH_TOKEN(Microsoft Foundry 除外,用 ANTHROPIC_FOUNDRY_API_KEY)。

云厂商涉及的环境变量
Amazon BedrockANTHROPIC_BEDROCK_BASE_URLCLAUDE_CODE_SKIP_BEDROCK_AUTH=1CLAUDE_CODE_USE_BEDROCK=1
Google Cloud Agent PlatformANTHROPIC_VERTEX_BASE_URLANTHROPIC_VERTEX_PROJECT_IDCLAUDE_CODE_SKIP_VERTEX_AUTH=1CLAUDE_CODE_USE_VERTEX=1CLOUD_ML_REGION
Microsoft FoundryANTHROPIC_FOUNDRY_BASE_URLANTHROPIC_FOUNDRY_API_KEY(以 x-api-key 头发送)、CLAUDE_CODE_USE_FOUNDRY=1(注意:CLAUDE_CODE_SKIP_FOUNDRY_AUTH 在此不适用,缺少 API key 会导致所有请求在发出前失败)
Claude Platform on AWSANTHROPIC_AWS_BASE_URLANTHROPIC_AWS_WORKSPACE_IDCLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1CLAUDE_CODE_USE_ANTHROPIC_AWS=1

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

Google Cloud 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

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

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

排查网关报错

报错原因修复方式
启动警告提示两个凭证来源、以「auth may not work as expected」结尾(老版本显示「Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set」)网关凭证与已保存登录同时生效;请求使用变量,但旧登录可能导致异常认证行为取消变量以使用已保存登录,或运行 /logout 使用网关凭证
401 报无效或未识别的 token凭证不是网关签发的,或放在了网关不读取的请求头对照凭证表确认变量类型是否匹配,并在网关端重新生成 key(如已被吊销)
Unable to connect to API (ConnectionRefused)、或 npm 安装时的 (ECONNREFUSED),常伴随重试退避前的静默停顿base URL 无应答:地址错误,或 VPN/防火墙阻断到网关的路径运行 curl 验证测试(会立即以同样原因失败),与网关团队确认 URL 与网络路径
API returned an empty or malformed response (HTTP 200)网关或中间代理返回了非 API 响应,常见为 HTML 错误页或登录页用 curl 请求测试,修复返回非 JSON 的网关路由
400context_managementExtra inputs are not permitted 或其他未识别字段网关转发到不接受 Claude Code 发给 Anthropic 格式端点的某些字段的上游设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1(抑制多数预发布字段);部分 beta 不受此开关控制,需设置对应的 CLAUDE_CODE_USE_* 提供方变量
400thinkingadaptive,如 Input tag 'adaptive' found上游模型版本不接受 Claude 4.6 及更新模型请求的自适应推理(adaptive reasoning)升级网关上游;Opus 4.6 与 Sonnet 4.6 上可用 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 替代;「model configuration」的能力变量(如 CLAUDE_CODE_USE_BEDROCKCLAUDE_CODE_USE_VERTEX)仅对相应提供方配置生效,不适用于 ANTHROPIC_BASE_URL 网关
400 报网关自身措辞的上下文或 token 限制,如 ContextWindowExceededErrorprompt token count of N exceeds the limit of M网关强制了比模型原生窗口更小的上下文,并改写了上游报错,导致匹配 Anthropic「prompt is too long」措辞的自动 compact-and-retry 未触发运行 /compact 恢复会话;可设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW 为网关限制值(会被限制在至少 100,000 tokens、至多模型上下文窗口之间,故低于 100,000 的网关限制无法精确匹配,此时 /compact 仍是恢复手段);同时应把 CLAUDE_CODE_MAX_OUTPUT_TOKENS 设置得低于网关模型的输出上限
/model 选择器中缺少某些模型网关的模型名不在 Claude Code 内置列表中启用「gateway model discovery」,或用「model configuration」变量手动添加模型名
curl 测试成功但 Claude Code 仍要求登录CLI 本身没有凭证:可达的 base URL 不等于凭证;项目 .claude/settings.json.claude/settings.local.json 中的 env 块只在首次运行向导与信任提示之后才生效在 Claude Code 首次运行设置之前就能读到的地方设置 ANTHROPIC_AUTH_TOKEN:shell 导出、~/.claude/settings.jsonenv 块,或 managed settings
ANTHROPIC_API_KEY 已设置但被忽略,且无提示交互式会话中该 key 需要一次性批准,此前被拒绝过的 key 会被静默忽略、不再询问/config 中启用「Use custom API key」选项
This machine's managed settings require a first-party loginmanaged settings 中包含 forceLoginMethodforceLoginOrgUUID,在 Claude Code v2.1.146 及以上版本中不能与 ANTHROPIC_API_KEYANTHROPIC_AUTH_TOKENapiKeyHelper 共存管理员需从 managed settings 中移除 forceLoginMethodforceLoginOrgUUID 才能使用网关凭证,或移除网关凭证以使用第一方登录;两者不可同时使用
403 且响应体为 HTML(如 403 Forbidden),网关自身日志显示未收到请求网关前的 Web 应用防火墙(WAF)或反向代理在请求到达网关前就拦截了请求体;Claude Code 提示词中包含 XML 风格标签与源代码,匹配跨站脚本(XSS)请求体规则,因此简单 curl 测试能通过而真实会话不能将网关的 /v1/messages 路径从请求体检测中豁免;AWS WAF 对应 CrossSiteScripting_Body 托管规则,nginx + ModSecurity 对应等效的 OWASP CRS 请求体规则
证书或 TLS 报错,如 SSL certificate verification failedSelf-signed certificate detected,而 curl 测试成功Claude Code 运行时未信任 curl 所使用的同一证书颁发机构(CA);常见于企业 TLS 检查代理环境设置 NODE_EXTRA_CA_CERTS 指向 CA bundle 路径

若移除网关配置后 Claude Code 仍反复要求登录,通常是凭证存储问题而非网关本身导致,可参考「authentication errors」(/en/errors#authentication-errors)。

关键环境变量速查

变量名作用
ANTHROPIC_BASE_URL网关基础地址
ANTHROPIC_AUTH_TOKEN凭证,发送到 Authorization: Bearer
ANTHROPIC_API_KEY凭证,发送到 x-api-key
ANTHROPIC_CUSTOM_HEADERS附加自定义请求头,每行一个 Name: Value
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY设为 1 启用网关模型发现(需 v2.1.129+)
CLAUDE_CODE_API_KEY_HELPER_TTL_MSapiKeyHelper 输出的缓存时长(毫秒),默认 5 分钟
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS设为 1 抑制大多数预发布 beta 字段
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING设为 1 在 Opus 4.6 / Sonnet 4.6 上禁用自适应推理请求
CLAUDE_CODE_AUTO_COMPACT_WINDOW自动 compact 触发的上下文阈值(限制在 100,000 到模型上下文窗口之间)
CLAUDE_CODE_MAX_OUTPUT_TOKENS限制最大输出 token 数,需低于网关模型的输出上限
NODE_EXTRA_CA_CERTS指定额外信任的 CA 证书路径,解决 TLS 检查代理导致的证书错误
ANTHROPIC_BEDROCK_BASE_URL / CLAUDE_CODE_SKIP_BEDROCK_AUTH / CLAUDE_CODE_USE_BEDROCKAmazon Bedrock 网关路由
ANTHROPIC_VERTEX_BASE_URL / ANTHROPIC_VERTEX_PROJECT_ID / CLAUDE_CODE_SKIP_VERTEX_AUTH / CLAUDE_CODE_USE_VERTEX / CLOUD_ML_REGIONGoogle Cloud Agent Platform 网关路由
ANTHROPIC_FOUNDRY_BASE_URL / ANTHROPIC_FOUNDRY_API_KEY / CLAUDE_CODE_USE_FOUNDRYMicrosoft Foundry 网关路由
ANTHROPIC_AWS_BASE_URL / ANTHROPIC_AWS_WORKSPACE_ID / CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH / CLAUDE_CODE_USE_ANTHROPIC_AWSClaude Platform on AWS 网关路由

相关资源

主题说明
LLM gateways overview(/en/llm-gateway)网关是什么,及其与 claude.ai 订阅的关系
Roll out an LLM gateway(/en/llm-gateway-rollout)面向管理员的网关部署与分发配置清单
Gateway protocol reference(/en/llm-gateway-protocol)Claude Code 发送给网关的内容,包括网关必须转发的请求头与字段
Settings(/en/settings)settings 文件的位置与 env 块的读取方式
Authentication(/en/authentication)凭证变量、apiKeyHelper 与 OAuth 登录之间的交互关系