自定义模型：LLM 网关与兼容接口

LLM 网关是你的组织在 Claude Code 和模型提供商之间运行的代理。使用网关时，Claude Code 用你的组织签发的凭据向网关认证，而不是用你个人的 claude.ai 登录。这也是让 Claude Code 使用「自己的」模型入口的方式：把请求指向一个你控制的端点。

重要：Anthropic 不认可、维护或审计第三方网关产品，也不支持通过任何网关把 Claude Code 路由到非 Claude 的模型。出了问题只能找对应的网关或模型厂商。

网关能给你的组织什么

一个网关给组织提供一个统一管理这些的地方：

• 凭据：提供商的密钥保存在服务端，开发者持有的是网关凭据
• 用量追踪：不管由哪个提供商处理请求，都能按开发者或团队归属用量
• 成本控制：在一处强制执行预算和速率限制
• 审计日志：为合规记录每个模型请求
• 切换提供商：在网关配置里更改提供商，无需触碰开发者的机器

代价是网关成为你组织要运营的基础设施。Claude Code 每个版本都会增加新功能，网关如果不转发它们，对应的功能就会出问题，所以网关产品需要随 Claude Code 的演进而保持更新。任何暴露了受支持 API 格式的网关都能用。

检查是否已有配置

管理员可以通过托管设置、设备管理或 apiKeyHelper 分发网关地址和凭据，让 Claude Code 在启动时直接拿到，你什么都不用设置。检查方法：

1. 运行 claude。如果它打开的是登录界面而不是会话，说明没有分发网关凭据，需要自己配置
2. 如果 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 菜单，发送任意提示。Claude 正常响应、没有报错，就确认网关连接可用

自己配置

你需要从网关团队拿到：网关的基础 URL，以及一个凭据（密钥或令牌字符串，或获取它的命令）。

设置凭据变量

要向网关认证，把凭据设置在环境变量里。用哪个变量取决于网关团队告诉你的：

如果你不知道是哪一种，用 ANTHROPIC_AUTH_TOKEN。每个变量把凭据放在不同的 HTTP 头里：ANTHROPIC_AUTH_TOKEN 放在 Authorization: Bearer，ANTHROPIC_API_KEY 放在 x-api-key，apiKeyHelper 两者都放。凭据放错了变量，会以网关不读取的头到达网关，请求就以 401 失败。

设置基础 URL 和凭据

第一次连接，先用 shell 导出，并在把值移到设置文件之前先运行验证请求。把下面的值换成网关团队给你的：

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

Windows PowerShell：

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

shell 里的 export 只对那个终端会话和从它启动的程序有效。想让值在新终端里保持，把同样的几行加到 shell 配置文件里（如 ~/.zshrc、~/.bashrc 或 PowerShell 的 $PROFILE）。

想让配置在 Claude Code 运行的所有地方都生效（包括后台智能体），把变量设置在设置文件的 env 块里，而不是依赖你的 shell：

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

可以放在 ~/.claude/settings.json（对你所有项目生效）或 .claude/settings.local.json（对一个项目生效，Claude Code 在那里保存设置时会把它加入你的全局 gitignore；手工创建时要先自己加进 gitignore，以免意外提交凭据）。不要把凭据放进项目的 .claude/settings.json，那个文件会被提交并与每个克隆仓库的人共享。当 shell 导出和设置文件的 env 块设置了同一个变量时，设置文件的值生效。

验证连接

shell 里导出变量后，先直接向网关发一个一 token 的请求，这样可以在打开 Claude Code 之前确认 URL 和凭据可用，失败就能指向网关而不是你的配置：

curl -sS -w '\n%{http_code}\n' -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。以 {"id":"msg_ 开头、并带有 "content":[...] 字段的 JSON 响应，意味着网关可达且凭据有效。一个指出未知模型的错误同样证明 URL 和凭据可用（网关在拒绝模型名之前已经认证了请求）。然后在同一个 shell 里启动 claude，发一条消息，运行 /status：Anthropic base URL 一行应该显示你的网关地址；Auth token 或 API key 一行点名你设置的变量，确认使用的是网关凭据而不是已保存的 claude.ai 登录。

与已有登录的冲突

网关凭据变量优先于已保存的 claude.ai 登录或 Console 密钥。变量设置期间，你的 claude.ai 登录保持保存但不被使用；取消设置变量，Claude Code 就回到它。运行 /status 确认哪个凭据来源处于活动状态。如果启动时出现点名两个来源的认证冲突警告，运行 /logout 清除已保存的登录，让只剩网关凭据。

设置了网关凭据后，请求走网关，计入网关侧的用量，不再消耗你的 Claude 订阅额度。只设置 ANTHROPIC_BASE_URL 而不设置网关凭据，不会替换订阅：请求仍经过网关，但已保存的 claude.ai 登录仍在使用。

其他入口怎么配置

这些配置对其他入口同样适用：VS Code 扩展、桌面应用、GitHub Actions 和 Agent SDK 各有各的配置位置（见官方「Configure each surface」一节）。

额外配置

只有当管理员需要，才设置这些：

发送额外的请求头：一些网关除了凭据，还用自定义头路由或标记请求，比如租户标识符。用 ANTHROPIC_CUSTOM_HEADERS，每行一个 Name: Value 对：

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

在设置文件的 env 块里时，pair 之间用 \n（JSON 字符串不能跨行）：

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

把网关模型加入模型选择器：启用模型发现后，Claude Code 在启动时向网关查询它的模型列表，并把这些名字和内置条目一起加到 /model 选择器里。如果你的网关提供 Claude Code 内置列表里没有的模型名，并且想从选择器里选，就启用它：

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

也可以放在 ~/.claude/settings.json 的 env 块里。发现到的模型作为额外的 /model 条目出现，每个条目显示网关提供的描述，或没有提供时显示 From gateway。想确认发现确实运行了，用 claude --debug 启动并在位于 ~/.claude/debug/<session-id>.txt 的调试日志里找 [gatewayDiscovery] 行。想加单个条目而不是依赖发现，用模型配置里的 ANTHROPIC_CUSTOM_MODEL_OPTION。

用 apiKeyHelper 轮换凭据：apiKeyHelper 是 Claude Code 运行来获取你的网关凭据的命令，而不是从静态环境变量里读取。凭据按计划过期、来自密钥库或 SSO 命令，或管理员让你配置时使用。

关闭网关路径之外的流量：网关承载模型请求，但 Claude Code 也会向 Anthropic 和第三方服务（如 GitHub）发送非必要的后台流量：版本检查、遥测、发布说明等。在只允许出口到网关的网络上，这些请求会失败，需要关闭。

接入第三方 Anthropic 兼容接口

一些模型厂商提供了兼容 Anthropic Messages API 的接口，可以用同样的变量把 Claude Code 接到它们的模型上。以 DeepSeek 官方给出的配置为例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<你的 DeepSeek API Key>",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

每家厂商的地址和模型名都不一样，接入前请对照该厂商的最新官方文档核实。需要注意：

• Anthropic 官方不支持通过网关把 Claude Code 路由到非 Claude 模型，出了问题只能找对应厂商
• 第三方接口不一定支持 Claude Code 的全部特性。如果遇到 400 报错，提示不认识某些字段（如 context_management、Extra inputs are not permitted），尝试设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1，它会抑制大部分预发布字段
• 如果报错提到 thinking 或 adaptive（上游模型版本不接受 Claude Code 对 Claude 4.6 及之后模型请求的自适应推理），升级网关的上游；在 Opus 4.6 和 Sonnet 4.6 上，也可以用 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
• 模型名、地址以各厂商最新文档为准

排查网关错误