Claude Code SDK #44：LLM Gateway 全解——ANTHROPIC_BASE_URL × apiKeyHelper × provider switching，把模型请求收口到团队网关

Claude Code SDK #44：LLM Gateway 全解——ANTHROPIC_BASE_URL × apiKeyHelper × provider switching，把模型请求收口到团队网关

LLM Gateway 不是企业代理的别名，而是 Claude Code 模型请求的控制平面。本篇拆解 ANTHROPIC_BASE_URL、gateway credential、apiKeyHelper、provider switching、Bedrock/Vertex 差异和团队 rollout，帮助开发者判断流量、凭据、计费和审计到底落在哪里。

Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解@wei
如果团队里每个人都把自己的 Claude Code 接到不同的 API key、不同的云账号、不同的代理出口，排障时会很痛苦：同样一个 claude 命令，有的人走 claude.ai 订阅，有的人走 Console API key，有的人走 Bedrock，还有人其实被公司网关转发了一层。LLM Gateway 要解决的不是「能不能连上网」，而是把模型请求的凭据、计费、审计、限额和 provider 路由收口到一个地方。官方文档对它的定位也很明确：gateway 管 provider credential、usage attribution、cost control、audit logging 和 provider switching。1

1. 先别把 gateway 和 proxy 混在一起

Corporate proxy 解决的是出站网络路径：请求能不能从公司电脑出去，TLS 证书能不能被信任，防火墙放不放行。LLM Gateway 解决的是模型请求进到哪一层服务：谁的上游凭据、记到哪个团队、怎么限流、怎么审计、是否能换 provider。官方企业部署页把 corporate proxy 和 LLM gateway 分成两个独立能力面，前者是网络出口，后者是模型请求集中管理层。2
换成一张表更好记：
层你在控制什么常见配置
Corporate proxy机器怎样出网HTTPS_PROXY、HTTP_PROXY、NO_PROXY 3
CA / mTLSTLS 和客户端证书怎样被信任CLAUDE_CODE_CERT_STORE、NODE_EXTRA_CA_CERTS、CLAUDE_CODE_CLIENT_CERT 3
LLM Gateway模型请求由谁鉴权、审计和计费ANTHROPIC_BASE_URL、provider-specific base URL、gateway credential、apiKeyHelper 1
所以排障顺序也应该分层：先确认网络能出，再确认 TLS 能过，最后看模型请求是不是被 gateway 正确接住。把 proxy 当 gateway，会缺少凭据归因和成本控制；把 gateway 当 proxy，又解决不了本机连不出去的问题。

2. Gateway 的核心入口是 base URL，但 base URL 不是凭据

Claude Code 的通用入口变量是 ANTHROPIC_BASE_URL。环境变量文档说，它会覆盖 API endpoint，用来把请求路由到 proxy 或 gateway；当它指向非一方主机时，MCP tool search 默认关闭，需要 gateway 能转发 tool_reference blocks 时再设 ENABLE_TOOL_SEARCH=true。同一行还记录了一个容易被忽略的行为：从 v2.1.196 起，如果 ANTHROPIC_BASE_URL 指向的不是 api.anthropic.com，Remote Control 会被禁用。4
最小配置长这样：
export ANTHROPIC_BASE_URL="https://llm-gateway.example.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="gateway-user-token"
claude
这里要拆成两个动作看：
  1. ANTHROPIC_BASE_URL 决定请求打到哪里。
  2. ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或 apiKeyHelper 决定这一轮请求用什么凭据。
官方 LLM Gateway 文档特别提醒：只设置 ANTHROPIC_BASE_URL，但没有 gateway credential，并不会替代开发者的 claude.ai 订阅。请求仍然会经过 gateway，但保存下来的 claude.ai login 仍是 active credential，usage limit 和 billing 也还是订阅那一套。只有 gateway credential variable 或 apiKeyHelper 生效时，开发者的 claude.ai subscription 才不会用于这个 session。1
这也是很多团队灰度 gateway 时最容易误判的地方：看到流量经过 gateway，就以为账单也已经切到组织账号。实际上如果凭据没切，gateway 只是转发路径，计费归属没有变。

3. apiKeyHelper 适合临时凭据，不适合手写死 token

如果公司不想把长期 token 直接写进环境变量，Claude Code settings 里有 apiKeyHelper。它是一个自定义命令，Claude Code 会通过系统 shell 执行它，并把返回值作为模型请求的 X-Api-Key 和 Authorization: Bearer header 发送；刷新间隔由 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 控制。5
一个更像企业真实部署的配置会是这样：
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com/anthropic",
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "900000"
  },
  "apiKeyHelper": "/usr/local/bin/get-claude-gateway-token"
}
这段配置的好处不是「更优雅」，而是把 token 生命周期交给公司已有的身份系统：helper 可以去拿 SSO、OIDC、Vault、内部 STS 或设备证书换出来的短期凭据。开发者机器上只需要有 helper，不需要知道上游 provider key。
Settings 文档还说，credential helpers 这类配置在 settings 文件变化时会 reload，属于多数可在运行中生效的 key；model 和 outputStyle 这类少数配置才需要用命令切换或重启。5

4. Provider switching 只有在「协议形状」统一时才真省事

Gateway 文档说 provider switching 的价值是：组织可以在 gateway 配置里换上游 provider，而不用改开发者机器。这个前提很关键：gateway 必须对外暴露统一的 Anthropic-format endpoint；如果 gateway 暴露的是某个云厂商自己的格式，Claude Code 侧仍然要按那个 provider 配置。1
看几个变量就能明白：
上游形态Claude Code 侧开关Gateway 相关 base URL
Anthropic API 格式ANTHROPIC_BASE_URL指向 gateway 的 Anthropic-format endpoint 4
Amazon BedrockCLAUDE_CODE_USE_BEDROCK=1ANTHROPIC_BEDROCK_BASE_URL 可覆盖 Bedrock endpoint，用于 custom endpoint 或 gateway 6
Google Cloud’s Agent PlatformCLAUDE_CODE_USE_VERTEX=1ANTHROPIC_VERTEX_BASE_URL 可覆盖 Agent Platform endpoint，用于 custom endpoint 或 gateway 7
Claude Platform on AWSCLAUDE_CODE_USE_ANTHROPIC_AWS=1ANTHROPIC_AWS_BASE_URL 可覆盖 Claude Platform on AWS endpoint 4
如果你的 gateway 对外统一成 Anthropic API 格式，开发者主要关心 ANTHROPIC_BASE_URL 和 gateway credential。若 gateway 对外保留 Bedrock 或 Vertex 的 provider format，开发者还要打开对应 provider 开关，配置区域、项目、模型 pin 和云厂商凭据。
这不是谁更高级的问题。统一 Anthropic-format endpoint 更适合做跨 provider 切换；provider-native endpoint 更适合保留云厂商自己的 IAM、区域、服务等级和治理能力。

5. Bedrock / Vertex 不是「换个 URL」那么简单

Amazon Bedrock 文档要求先有 AWS account、Bedrock access、目标 Claude model access、AWS credentials 和 IAM permissions。手动配置时要设 CLAUDE_CODE_USE_BEDROCK=1，区域通常走 AWS_REGION 或 AWS profile；文档还提醒，Bedrock 下 /logout 不可用，因为认证由 AWS credentials 处理。6
Google Cloud’s Agent Platform 也类似。文档要求 GCP account、billing、启用 Agent Platform API、模型访问权限、gcloud 和区域 quota；手动配置时要设 CLAUDE_CODE_USE_VERTEX=1、CLOUD_ML_REGION 和项目 ID。它同样说明 /logout 不可用，因为认证交给 Google Cloud credentials。7
这说明一件事：如果你只是想把 Anthropic API key 放到服务端统一管理，走 Anthropic-format gateway 通常更直接。如果你已经把 AI 调用治理放在 AWS 或 GCP 里，Claude Code 侧就要接受 provider-native 的认证、区域、模型可用性和配额模型。

6. Gateway 需要跟着 Claude Code 能力一起升级

官方文档对 gateway 有一句很实际的提醒：Claude Code 会随着版本增加能力，如果 gateway 没有转发对应能力，就会破坏相关功能；gateway 产品需要随着 Claude Code 演进保持更新。1
这句话落到工程上，就是别只测「能不能返回一段文本」。至少要测这些面：
  1. 流式响应是否稳定。环境变量页提到，gateway 连接默认会受 5 分钟 idle timeout 影响；慢 gateway 可以用 API_FORCE_IDLE_TIMEOUT 调整 stalled stream 行为。4
  2. Tool search 是否被正确转发。ANTHROPIC_BASE_URL 指向非一方主机时，MCP tool search 默认关闭，只有 gateway 能转发 tool_reference blocks 时才应显式打开。4
  3. OAuth 能力是否保留。如果只设置 base URL 而仍使用 claude.ai login，gateway 继续转发到 Anthropic 时需要转发 anthropic-beta 里的 OAuth capability。1
  4. 自定义 header 是否被保留。环境变量页提供 ANTHROPIC_CUSTOM_HEADERS，可把自定义 header 加到请求里；这类 header 经 gateway 时也要明确是否允许和转发。4
很多 gateway 迁移失败，不是第一天完全跑不起来，而是基本问答能跑，工具搜索、长流式、OAuth session、provider beta header 或成本归因在第二周开始出问题。

7. 团队 rollout 不要从「发一串 export」开始

LLM Gateway 文档给的 rollout 顺序很清楚：先部署 gateway 并放入 provider credential；再给每个开发者发 gateway credential；然后通过 managed settings 和 secrets tooling 分发 base URL 与凭据；最后让开发者在 Claude Code 里检查配置是否生效。1
Managed settings 是这里的关键。Settings 文档说 Managed scope 适合组织级安全策略和合规要求，优先级最高，用户和项目配置不能覆盖；它可以通过 server-managed settings、MDM/OS policy、系统级 managed-settings.json 等方式下发。5
一个 rollout 片段可以这样组织：
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com/anthropic",
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "900000",
    "API_TIMEOUT_MS": "1200000"
  },
  "apiKeyHelper": "/usr/local/bin/get-claude-gateway-token"
}
如果公司同时要控制 MCP、权限、插件市场和 telemetry，再把这些策略放进同一套 managed delivery，而不是让每个仓库复制一份 .claude/settings.json。项目配置适合团队协作规则，组织级 credential 和网关入口更适合放在 managed scope。

8. 最小自检清单

上线 LLM Gateway 前，可以让平台团队按下面这组问题验收：
  1. ANTHROPIC_BASE_URL 或 provider-specific base URL 是不是已经生效？/status 或请求日志里能不能看到实际路由？
  2. gateway credential 是否真的替代了 claude.ai subscription？只设 base URL 不算。1
  3. apiKeyHelper 返回的是短期凭据还是长期 token？TTL 是否符合公司身份系统的刷新周期？5
  4. Tool search、长流式响应、OAuth session、自定义 header 和 provider beta header 有没有逐项测试？
  5. Bedrock / Vertex / Foundry 这类 provider-native 路线是否已经单独处理区域、模型 pin、IAM、quota 和 /logout 行为？67
  6. Managed settings 是否已经覆盖团队机器，而不是靠 wiki 里的一串 export？5
我会把 LLM Gateway 当成 Claude Code 企业化的「模型请求控制平面」。它不替你解决所有网络问题，也不自动替换每个人的订阅；它真正有价值的地方，是把 provider key 从开发者机器上拿走，把 usage、成本、审计和切换权交回给团队平台层。做对了，开发者还是敲同一个 claude，但组织终于知道这些请求从哪来、花了多少钱、该由谁负责。

参考ソース

  1. 1Other LLM gateways - Claude Code Docs
  2. 2Enterprise deployment overview - Claude Code Docs
  3. 3Enterprise network configuration - Claude Code Docs
  4. 4Environment variables - Claude Code Docs
  5. 5Claude Code settings - Claude Code Docs
  6. 6Claude Code on Amazon Bedrock - Claude Code Docs
  7. 7Claude Code on Google Cloud's Agent Platform - Claude Code Docs

関連コンテンツ

  • ログインするとコメントできます。
More from this channel
View the full content archive of "Claude Code SDK 每日技术拆解"Explore more channels on Discover