在组织中推广部署 LLM 网关

为 Claude Code 部署网关产品：配置网关转发 Claude Code 发送的内容、签发开发者凭据、通过托管设置分发配置，并验证推广部署结果。

本页指导管理员为 Claude Code 推广部署 LLM 网关。文中假定你已部署满足网关要求的网关产品。这里不介绍任何具体产品的部署或运维；请按照相应供应商的文档部署你的产品。

前提条件

要完成推广部署，你需要：

• 在自己的基础设施中部署一个网关。它必须通过 HTTPS 在准备分发给开发者的确切地址上提供服务，而不能使用会重定向到该地址的地址；同时，网关应已配置为将 Claude 模型名称路由到你的提供方
• 供网关转发给提供方的凭据：
  • 对于 Anthropic API：从 Claude Console 获取 API 密钥
  • 对于云提供商：拥有模型访问权限的云凭据。请参阅 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 页面中的前提条件
• 一种向开发者计算机分发设置文件的方法，例如 MDM 或配置管理系统
  • 如果尚未部署此类系统，设置如何下发到设备对各种方案进行了比较

网关要求

无论使用哪种网关产品，都必须满足以下要求：

• 接受受支持的 API 格式：支持 API 格式表中的一种格式。下文的推广部署步骤假定使用 POST /v1/messages 上的 Anthropic Messages API，大多数网关都支持该接口
• 流式传输响应：服务器发送事件到达后立即透传，而不是缓冲完整响应
• 路由 Claude 模型名称：将开发者使用的每个名称映射到上游模型。Claude Code 会在每个请求中发送类似 claude-sonnet-4-6 的模型名称；对于大多数网关产品，该映射配置为网关自身配置中的模型列表或路由表
• 原样转发请求头和正文：在两个方向上透传 anthropic-beta、anthropic-version 和请求正文；功能透传表列出了缺少各项内容时会失效的功能
• 不修改上游错误：Claude Code 的自动恢复机制会匹配错误措辞，因此用网关自己的封装格式包装错误会导致恢复失效
• 免除该路径的 WAF 请求正文检查：Claude Code Prompt 中包含源代码和 XML 风格标签，会命中针对跨站脚本的正文规则；网关前方的 WAF 可能使真实会话返回 403，即使简短的测试请求能够通过

还可以选择提供 GET /v1/models，让 Claude Code 通过模型发现从网关填充模型选择器。

推广部署步骤

推广部署分为五步，每一步都有一个检查点：

1. 确认网关能够路由模型
2. 为每位开发者签发凭据
3. 通过网关测试 Claude Code
4. 分发基准 URL 和凭据
5. 从开发者计算机验证推广部署

这些步骤涉及三种不同的凭据。检查点使用占位符指代它们，便于在发生故障时判断是哪一种凭据出了问题：

确认网关能够路由模型

此时，网关应已配置提供方凭据，正在其基准 URL 上监听，并能将请求转发到提供方 API。请使用一个最小请求测试整条路径，并替换其中来自你部署环境的两个值：

• <gateway-key> 是当前可用于调用网关的凭据：可以是管理密钥、测试密钥，也可以是已经签发的个人开发者密钥。并非所有网关产品都提供单独的管理凭据；如果你的产品没有，请先在签发开发者凭据步骤中为自己签发一个开发者密钥
• model 是网关已配置路由的 Claude 模型名称。示例使用 claude-sonnet-4-6；请替换为你已配置的名称

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -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 "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

检查点：收到包含 content 字段的 200 响应，说明网关已使用该模型名称连接到提供方。404 表示网关未路由该名称；来自提供方的 401 则表示网关的提供方凭据有误。

请针对网关路由配置中的每个 Claude 模型名称各重复一次该请求。开发者选择任何网关未路由的名称时都会收到 404，因此要在推广部署前测试每个名称。

签发开发者凭据

每位开发者都需要自己的网关密钥来完成身份验证。请按照所用产品的凭据管理文档，在网关上为每位开发者分别创建凭据。

使用与确认网关能够路由模型相同的请求，确认刚签发的密钥可以访问网关，并将 <gateway-key> 替换为新的 <developer-key>：

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -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 "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

检查点：收到包含 content 字段的 200 响应，说明开发者密钥可以访问网关，且网关已转发请求。如果上一步成功而此处返回 401，则开发者密钥有误，或者尚未在网关上生效。

只有为每位开发者分别签发密钥，而不是共用同一个密钥，才能按开发者归因用量，并单独撤销离职人员的访问权限。用于保存密钥的环境变量取决于网关读取哪个请求头。对于通过 Authorization: Bearer 请求头检查凭据的网关，开发者应将密钥设置到 ANTHROPIC_AUTH_TOKEN。对于从 x-api-key 请求头读取密钥的网关，则应设置 ANTHROPIC_API_KEY；凭据表说明了这种对应关系。

通过网关测试 Claude Code

分发任何内容之前，请先自行通过网关运行 Claude Code，并使用推广部署将向整个设备群下发的同一套配置。请直接在终端中输入以下命令，不要写入 .env 或设置文件；这些变量只在当前终端会话中有效，关闭终端后，计算机会恢复正常配置。如果网关读取 x-api-key 请求头，请使用 ANTHROPIC_API_KEY，而不是 ANTHROPIC_AUTH_TOKEN：

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

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

然后通过网关发送一次性 Prompt：

claude -p "Reply with one word: connected"

检查点：Prompt 返回响应，而且网关日志中出现一个发往 /v1/messages 路径、状态为 200 的 POST 请求。Claude Code 会附加类似 ?beta=true 的查询字符串，因此应匹配路径，而不是完整 URL。以下两种故障信息指向不同的问题：

• Not logged in：通过网关日志区分两种原因。如果日志为空，说明会话没有收到凭据，也没有请求离开本机；请在用于测试的 shell 中重新运行 export 命令。如果日志显示请求被拒绝，且 401 正文中出现 x-api-key，说明网关要求通过该请求头提供密钥；请改用 ANTHROPIC_API_KEY
• Failed to authenticate. API Error: 401 表示凭据已经发出，但遭到拒绝，具体位置可查看网关日志：如果 401 中提到 api.anthropic.com 或提供方端点，说明网关已连接上游，但提供方凭据遭到拒绝；也就是说，开发者密钥正常，而网关保存的提供方凭据有误或仍是占位值

基准 URL 错误或无法访问会产生另一种症状：Claude Code 会采用退避策略重试连接，可能持续数分钟不输出任何内容，之后才报告错误。如果命令看似卡住，请直接查看网关日志，不要继续等待；没有请求到达，说明 ANTHROPIC_BASE_URL 未指向网关。

分发配置

每台开发者计算机都需要网关地址和凭据。你可以通过托管设置集中分发，让开发者无需自行配置；也可以把相关值交给开发者，由他们自行设置。

需要分发的内容

无论选择哪种方式，需要分发的变量都相同。大多数推广部署只需 ANTHROPIC_BASE_URL 和一种凭据；如果网关配置符合条件列中的情形，再加入相应变量。

通过托管设置分发

通过托管设置文件的 env 块分发变量，并使用 MDM、注册表策略或配置管理系统推送该文件：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

将表格中的条件变量添加到同一个 env 块。托管的 ANTHROPIC_BASE_URL 会强制生效，开发者无法通过 shell export 覆盖，因为 Claude Code 会用它覆盖进程环境和优先级较低的设置。

请勿在托管设置中将 forceLoginMethod 或 forceLoginOrgUUID 与网关凭据同时使用。从 Claude Code v2.1.146 开始，只要存在这两个配置键中的任意一个，无论其值是什么，启动时都会阻止 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 apiKeyHelper，导致开发者看到 This machine's managed settings require a first-party login，且无法继续。

服务器托管设置的下发需要直接连接 api.anthropic.com，因此无法覆盖经网关路由的会话。网关部署应使用这种基于文件的托管设置方式；它会对相同的配置键强制执行设置。

对于凭据，可以像上例一样，在托管设置文件中分发一个 apiKeyHelper 命令。该命令以本地开发者身份向密钥存储系统进行身份验证，因此每台计算机都会收到自己的密钥。另一种方法是通过现有的密钥分发流程把密钥交给各开发者，让他们自行设置 ANTHROPIC_AUTH_TOKEN。

某些环境需要单独分发：

• 桌面应用只从 MDM 下发的第三方推理配置中读取网关路由；请将该文件与托管设置一同部署，使桌面会话也通过网关路由。请参阅桌面版第三方配置文档和桌面版网关文档
• CI runner 需要在 runner 环境中设置 ANTHROPIC_BASE_URL 和凭据
• 只有将 wslInheritsWindowsSettings 设为 true，托管 Windows 计算机上的 WSL 才会读取 Windows 托管设置

将设置值交给开发者自行配置

如果尚未部署托管设置分发系统，请向每位开发者提供以下信息，让他们按照连接页面操作：

• 网关 URL
• 个人凭据
• 凭据应存入哪个变量：使用 bearer token 的网关应存入 ANTHROPIC_AUTH_TOKEN，使用 x-api-key 的网关应存入 ANTHROPIC_API_KEY。明确告诉开发者应使用哪个变量，可以省去连接页面中提到的反复尝试
• 需要分发的内容表中适用的所有条件变量及其值

连接页面会指导开发者逐项完成设置。

检查点：在开发者计算机上启动 claude 时，由于分发的凭据已满足身份验证要求，会话应直接启动，不显示登录界面。然后运行 /status 并打开 Status 标签页：Anthropic base URL 一行应显示网关地址；如果通过托管方式分发，Setting sources 一行应包含托管设置。出现登录界面，或者缺少 Anthropic base URL 一行，都表示配置尚未到达该计算机。

验证推广部署

请从开发者计算机而不是网关主机进行验证，确保测试覆盖开发者实际使用的网络路径。发送一个流式请求，一次检查端点、流式透传和模型路由：

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
  -H "Authorization: Bearer <developer-key>" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  --data-binary '@-'

你应该会看到 data: 行逐步到达。如果暂停一段时间后整个响应一次性到达，说明网关正在缓冲，这会使 Claude Code 停滞；404 则表示模型名称未被路由。请针对每个模型名称重复测试。

然后启动 claude 并发送消息。此步骤中的每种症状都对应一个原因：

• 出现登录提示，说明凭据存在缺口。运行 /status 并打开 Status 标签页：如果 Setting sources 一行不包含托管设置，则分发未到达该计算机；如果包含，说明开发者凭据没有成功下发，请设置 ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper
• 出现 Failed to authenticate 错误，说明网关拒绝了请求；网关日志会指出哪种凭据失败。由网关自身记录的拒绝会指向开发者密钥，而来自 api.anthropic.com 或提供方端点的 401 则表示网关保存的提供方凭据遭到拒绝
• 如果网关要求通过 x-api-key 请求头提供密钥，并通过 ANTHROPIC_API_KEY 设置，那么首次使用时出现一次密钥批准提示属于正常现象。使用 ANTHROPIC_AUTH_TOKEN 时不会显示提示，该变量会直接接管身份验证；之前保存的 claude.ai 登录信息在该会话中不会生效

最后，在网关日志中找到刚才发送的消息：凭据用于标识开发者，x-claude-code-session-id 请求头用于按会话归组请求。如果功能出现故障排除症状，说明网关移除了请求头或改写了错误；请参阅上文的网关要求。

维护网关

推广部署后，网关会随时间遇到三类变化。每类变化都有需要关注的症状和应采取的措施。

为每个密钥设置速率限制时，要考虑客户端会重试暂时性故障：包括 429 响应在内，客户端会采用退避策略最多重试 10 次，并遵循 Retry-After。请将协议参考作为判断各 Claude Code 版本发送内容的约定。

相关资源

• 将 Claude Code 连接到 LLM 网关：面向开发者的设置步骤，包括各使用界面的配置方法，以及可以直接交给开发者的故障排除表
• 网关协议参考：面向网关运营方的通信协议约定，涵盖端点、需要转发的请求头和功能透传表
• 设置文件和优先级：托管、项目和用户设置的组合方式，以及各平台上托管文件的存放位置
• 为组织设置 Claude Code：此网关所属的整体推广部署，包括策略执行、用量可见性和数据处理