为组织推广 LLM 网关¶

部署网关产品用于 Claude Code：配置转发、签发开发者凭证、通过托管设置分发配置、验证推广效果。

本页引导管理员完成 LLM 网关的组织级推广。 假设你已部署了满足网关要求的网关产品。具体产品的部署和运维不在此覆盖范围。

• 开发者连接现有网关：连接 Claude Code 到 LLM 网关
• Claude Code 向网关发送的内容：网关协议参考

前提条件¶

完成推广需要：

• 已部署在基础设施上的网关，通过 HTTPS 监听你将分发给开发者的确切地址（非重定向地址），且已配置 Claude 模型名称路由
• 网关用于转发的提供商凭证：
• Anthropic API：Claude Console 的 API key
• 云服务商：具有模型访问权限的云凭证。参见 Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry 页的前提条件
• 将设置文件分发到开发者机器的方式（MDM 或配置管理）
• 如果尚未有分发方式，设置如何到达设备对比了各种选项

网关要求¶

网关产品必须满足以下条件：

可选：提供 GET /v1/models 以支持模型发现。

推广步骤¶

推广分五步，每步有检查点：

1. 确认网关路由模型
2. 签发开发者凭证
3. 针对网关测试 Claude Code
4. 分发配置
5. 从开发者机器验证

涉及三种凭证：

确认网关路由模型¶

用最小请求测试端到端路径：

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

检查点：200 + content 字段表示网关到达了提供商。404 表示模型名未路由；来自提供商的 401 表示网关的提供商凭证有误。

对网关路由配置中的每个 Claude 模型名重复测试。

避免在重定向后面提供网关。重定向可能丢弃请求体或剥离凭证头，且模型发现将任何重定向视为失败。

签发开发者凭证¶

每位开发者需要自己的网关密钥。 在网关创建每人一个凭证，并确认新签发的密钥有效：

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

检查点：200 + content 字段表示开发者密钥到达网关且网关成功转发。

每人一个密钥（而非共享密钥）才能实现按人归属用量和独立吊销。

针对网关测试 Claude Code¶

在分发前，自己先以开发者身份通过网关运行 Claude Code：

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

然后发送单次提示：

claude -p "Reply with one word: connected"

检查点：收到回复，且网关日志中显示 POST /v1/messages 状态 200。

排查提示：
- Not logged in：检查网关日志区分原因——日志为空说明凭证未到达会话；日志显示 x-api-key 被拒说明应切换到 ANTHROPIC_API_KEY
- Failed to authenticate. API Error: 401：凭证被发送但被拒绝，网关日志显示方向
- 命令卡住无输出：检查网关日志而非等待——无到达请求说明 Base URL 不对

分发配置¶

每台开发者机器需要网关地址和凭证。 通过托管设置集中分发，或交给开发者自行设置。

需分发的变量¶

通过托管设置分发¶

通过 MDM、注册表策略或配置管理推送托管设置文件的 env 块：

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

托管的 ANTHROPIC_BASE_URL 是强制的，开发者的 Shell 导出无法覆盖。

不要在托管设置中同时包含 forceLoginMethod/forceLoginOrgUUID 和网关凭证。 自 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 和凭证
- 托管 Windows 上的 WSL：仅在 wslInheritsWindowsSettings 为 true 时读取 Windows 托管设置

交给开发者自行设置¶

如果没有托管设置分发机制，发给每位开发者：

• 网关 URL
• 个人凭证
• 凭证应放入哪个变量
• 条件变量及其值

检查点：开发者机器上 claude 启动不显示登录界面；/status 的 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"}]}'

应看到 data: 行逐步到达。整个响应在停顿后一次性到达表示网关在缓冲（会卡住 Claude Code）；404 表示模型名未路由。

然后启动 claude 发送消息。各症状对应：
- 登录提示：凭证缺失——检查 /status 的 Setting sources
- Failed to authenticate：网关拒绝请求——查看网关日志
- 密钥一次性审批提示：使用 ANTHROPIC_API_KEY 时首次使用的正常行为

如果组织使用 fast mode，此处也运行 /fast：可用性检查直接调 api.anthropic.com 而非走网关 Base URL，因此网关路由的会话可能报告 fast mode 不可用或已禁用即使推理正常。在代理和网关后使用 fast mode 将每条消息映射到恢复它的变量，与其余配置一起分发。

最后检查网关日志：凭证标识开发者，x-claude-code-session-id 头按会话分组请求。如果功能因排障症状而失败，说明网关在剥离头或重写错误；参见上方网关要求。

维护网关¶

推广后需关注三类变化：

设置速率限制时，考虑客户端重试瞬态失败（含 429）最多 10 次带退避，遵循 Retry-After。

相关资源¶

• 连接 Claude Code 到 LLM 网关：开发者设置步骤和排障表
• 网关协议参考：网关运维的协议协定
• 设置文件和优先级：托管、项目和用户设置的组合方式
• 为组织设置 Claude Code：网关所属的更广泛组织设置