连接 Claude Code 到 LLM 网关¶

将 Claude Code 指向组织的 LLM 网关。检查管理员是否已配置好，或自行为 CLI、VS Code、GitHub Actions 和 Agent SDK 设置 Base URL 和凭证，然后验证连接并修复错误。

LLM 网关是组织在 Claude Code 和模型提供商之间运行的代理。 使用网关时，Claude Code 通过组织签发的凭证认证，而非个人 claude.ai 登录。

本页面面向通过组织网关运行 Claude Code 的开发者，涵盖两条路径：检查管理员是否已为你配置好，以及未配置时自行设置。

• 部署组织网关：推广 LLM 网关
• Claude Code 向网关发送的内容：网关协议参考

检查已有配置¶

管理员可能已通过托管设置、设备管理或 apiKeyHelper 分发了网关地址和凭证。 Claude Code 启动时会自动识别，无需手动设置。检查方式：

1. 启动 Claude Code：运行 claude。如果出现登录界面而非直接进入会话，说明没有分发网关凭证；按下文自行配置。

2. 检查 Status 标签：如果 Claude Code 未显示登录界面直接进入会话，运行 /status，打开 Status 标签，检查两行内容：
   - Anthropic base URL：仅在设置了网关地址时出现。如果不存在，说明 Claude Code 未指向网关。
   - Auth token 或 API key：显示 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或 apiKeyHelper 表示网关凭证生效。如果是 Login method 行指向 claude.ai 账号，则凭证未分发。

3. 发送测试消息：关闭 /status 菜单，发送任意提示词。收到正常回复即确认网关连接正常。

如果 /status 显示正常但消息失败，参见故障排查表。

自行配置 Claude Code¶

自行配置网关需要从网关团队获取：

• 网关的 Base URL
• 凭证：密钥/令牌字符串，或获取凭证的命令

设置凭证变量¶

根据网关团队告知的凭证类型，设置对应的环境变量：

如果不确定用哪个，先用 ANTHROPIC_AUTH_TOKEN；验证请求时会知道是否需要切换。

设置 Base URL 和凭证¶

将网关 Base URL 和凭证设为环境变量。 下面示例使用 ANTHROPIC_AUTH_TOKEN；如果你选的是 ANTHROPIC_API_KEY，请替换。

Shell 环境变量方式¶

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 导出仅对当前终端会话及其启动的程序生效。从 Dock 或开始菜单启动的编辑器不会看到。要在新终端中持久化，将相同行添加到 Shell 配置文件（如 ~/.zshrc、~/.bashrc 或 PowerShell 的 $PROFILE）。

如果仅在 Shell 中导出网关变量，它无法可靠地到达由 supervisor 托管的后台 Agent；参见每个后台会话如何获取网关配置。后台 Agent 必须路由的网关请使用设置文件。

设置文件方式¶

在设置文件的 env 块中设置变量，让配置应用于 Claude Code 运行的所有地方，包括后台 Agent：

• ~/.claude/settings.json：适用于所有项目（Windows 路径为 %USERPROFILE%\.claude\settings.json）
• .claude/settings.local.json：适用于单个项目。Claude Code 在保存设置时会将其添加到全局 gitignore；如果你手动创建或让 Claude 写入该文件，请先自行加入 gitignore 以免意外提交凭证

不要将凭证放在项目的 .claude/settings.json 中——该文件会提交到仓库。

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

当 Shell 导出和设置文件 env 块同时设置同一变量时，设置文件的值优先。运行 /status 可查看 Claude Code 使用的 Base URL 和凭证来源。

验证连接¶

导出变量后，直接向网关发送一个单 token 请求来验证 URL 和凭证：

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

如果网关使用 x-api-key 头，将 Authorization 头替换为 x-api-key: $ANTHROPIC_API_KEY。

判断结果：
- JSON 响应以 {"id":"msg_ 开头且包含 "content":[...] 字段：网关可达、凭证有效
- 模型名不认识的错误：仍然证明 URL 和凭证有效（网关认证了请求后才拒绝模型名）
- 401：凭证被拒绝，切换到另一个变量重试

在 Claude Code 中确认¶

从同一 Shell 启动 claude（继承导出的变量），发送消息后运行 /status。在 Status 标签中，Anthropic base URL 行应显示你的网关地址。

凭证变量与请求头的映射¶

每个变量以不同的 HTTP 头发送凭证：

凭证放错变量时，会以网关不读取的头发送，请求返回 401。

与已有登录的冲突¶

网关凭证变量优先于已保存的 claude.ai 登录或 Console 密钥。 已保存登录在变量设置期间保留但未使用；取消变量后 Claude Code 会恢复使用。运行 /status 确认当前活跃凭证源。要清除已保存登录使网关凭证唯一，运行 /logout。

各平台配置¶

CLI 读取上面的环境变量和设置文件。 其他界面是 VS Code 扩展、桌面应用、GitHub Actions、Agent SDK 和云端界面（如 Slack 和 Web）；以下各节说明这些设置是否到达每个界面。

VS Code 扩展¶

在 VS Code 扩展的用户设置（JSON）中通过 claudeCode.environmentVariables 设置网关变量，使用 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 读取。该配置可来自组织分发或应用内表单：

• 管理员分发：如果组织已部署配置，桌面应用无需你设置即可通过网关路由
• 本地配置：对于没有管理员分发配置的设备，打开 Help -> Troubleshooting -> Enable Developer Mode（会重启应用），然后打开 Developer -> Configure Third-Party Inference 输入网关 Base URL。管理员分发的配置优先并使此表单只读

网关配置生效后，桌面应用仅在本地机器上运行会话：环境选择器不提供 SSH 会话或 Anthropic 托管的云环境，Remote Control 不可用。要通过网关在远程主机上使用 Claude Code，在该主机上运行 CLI 并设置 ANTHROPIC_BASE_URL 和网关凭证。

如果桌面应用显示 Gateway was unreachable，说明启动时无法到达配置的 Base 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:
  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 传递两次：作为 anthropic_api_key 输入和作为工作流 env 块中的 ANTHROPIC_AUTH_TOKEN。Action 要求 anthropic_api_key、CLAUDE_CODE_OAUTH_TOKEN 或 workload identity federation 之一才能启动 Claude Code（它不读取 ANTHROPIC_AUTH_TOKEN），因此 input 仅满足该启动检查。env 变量才是将密钥放入网关读取的 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 和 workload identity federation），参见 Claude Code GitHub Actions 和 action 的 README。

Agent SDK¶

Agent SDK 没有网关专用选项；它将环境变量传递给生成的 Claude Code 进程。

• 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,
    },
  },
})

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

Slack、Web 和 Remote Control¶

Slack 中的 Claude Code 和 Web 版 Claude Code 是 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

附加配置¶

发送自定义请求头¶

某些网关需要额外头（如租户标识或路由键）：

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

设置文件中用 \n 分隔多个头：

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

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

模型发现（Model Discovery）在启动时查询网关的模型列表，添加到 /model 选择器。

启用方式：设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。需要 Claude Code v2.1.129 或更高版本。

发现的模型标记为「From gateway」。启动 claude --debug 并查找 [gatewayDiscovery] 行可确认发现结果。

使用 apiKeyHelper 轮换凭证¶

apiKeyHelper 是 Claude Code 运行的命令，用于获取网关凭证而非从静态环境变量读取。

适用于凭证有过期时间、来自密钥库或 SSO 命令的情况。Helper 是任何将当前凭证打印到 stdout 的 Shell 命令。

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

在 ~/.claude/settings.json 中引用：

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

Claude Code 默认缓存 helper 输出 5 分钟，收到 HTTP 401 时重新运行。通过 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整缓存时长（毫秒）。

Helper 的值会同时发送到 Authorization 和 x-api-key 头。

关闭非网关路径流量¶

网关承载模型请求，但 Claude Code 还会在网关路径之外向 Anthropic 和第三方服务（如 GitHub）发送非必要的后台流量： 版本检查、遥测、错误报告、发行说明等。在仅允许出口到网关的网络中，这些请求会失败并出现在出口监控中。

设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1：

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

该变量的效果和限制：

• 禁用自动更新，需规划其他更新路径（如包管理器或托管分发）
• 抑制 fast mode 可用性检查。除非之前的检查已在机器上启用了 fast mode，否则 /fast 报告不可用
• 关闭网关模型发现，即使发现查询的是网关本身。之前发现的模型从本地缓存仍可用，但列表不会刷新
• WebFetch 工具的域名安全检查不受影响仍会调用 api.anthropic.com。如果你的网络阻止该主机，在设置中单独设置 skipWebFetchPreflight: true
• 每个遥测流及其控制变量，参见遥测服务

通过网关路由到云服务商¶

仅在网关团队明确指定 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 时才设置以下配置。 如果上面的验证请求返回了 JSON，你可以跳过本节。

skip-auth 变量告诉 Claude Code 不要用提供商凭证签名请求（因为网关持有那些凭证）。如果网关需要自己的 token，在配置块后添加 ANTHROPIC_AUTH_TOKEN（Microsoft Foundry 使用 ANTHROPIC_FOUNDRY_API_KEY）。自 v2.1.203 起，期望 bearer token 的 Microsoft Foundry 网关可以使用 ANTHROPIC_FOUNDRY_AUTH_TOKEN 代替，它在两者同时设置时优先于 ANTHROPIC_FOUNDRY_API_KEY。

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¶

将网关凭证放入 ANTHROPIC_FOUNDRY_API_KEY，它作为 x-api-key 头发送到网关。期望 bearer token 的网关可以使用 ANTHROPIC_FOUNDRY_AUTH_TOKEN 代替（以 Authorization: Bearer 头发送，两者同时设置时优先，需要 v2.1.203+）。

对于注入自己的 Authorization 头的网关，设置 CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 并留空两个凭证变量。

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¶

参见 Claude Platform on AWS 获取 workspace ID。

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

排查网关错误¶

如果移除网关配置后 Claude Code 反复提示登录，原因通常是凭证存储而非网关；参见认证错误。

相关资源¶

• LLM 网关概览：网关定义及与订阅的交互
• 为组织推广 LLM 网关：管理员部署和分发网关配置的检查清单
• 网关协议参考：Claude Code 向网关发送的内容
• 设置：设置文件位置及 env 块读取方式
• 认证：凭证变量、apiKeyHelper 和 OAuth 登录的交互