LLM Gateway 配置

用网关在 Claude Code 与模型提供方之间做统一鉴权、用量与路由。

是什么

LLM gateway 是一层位于 Claude Code 与模型提供方之间的集中式代理，常用于集中鉴权（单点管理 API key）、用量追踪、成本控制（预算与限流）、审计日志（合规追踪）以及模型路由（无需改代码即可切换提供方）。Claude Code 通过指向网关的 base URL 与之对接，并依据网关暴露的 API 格式决定启用哪些功能。

怎么工作

• 网关至少需暴露一种 API 格式：Anthropic Messages（/v1/messages、/v1/messages/count_tokens）、Bedrock InvokeModel（/invoke、/invoke-with-response-stream）或 Vertex rawPredict（:rawPredict、:streamRawPredict、/count-tokens:rawPredict）
• Anthropic Messages 与 Vertex 格式必须转发请求头 anthropic-beta、anthropic-version；Bedrock 格式必须保留请求体字段 anthropic_beta、anthropic_version，否则可能功能受限或无法使用
• 当用 Anthropic Messages 格式对接 Bedrock 或 Vertex 时，可能需设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
• Claude Code 会附带请求头 X-Claude-Code-Session-Id、X-Claude-Code-Agent-Id、X-Claude-Code-Parent-Agent-Id，供代理在不解析请求体的情况下归因用量；这些 agent ID 是每次 spawn 的临时标识，非持久用户/设备 ID
• Claude Code 还会在 system prompt 前置一小段归因块（含客户端版本与会话指纹）；Anthropic API 在处理前会剥离该块，故不影响一方 prompt 缓存。若网关基于完整请求体做自有 prompt 缓存，设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 以省略它
• 默认情况下 Claude Code 对所选 API 格式使用标准模型名；可选启用网关模型发现（见下）

怎么配置 / 用法

基础环境变量（统一端点，推荐）：

export ANTHROPIC_BASE_URL=https://litellm-server:4000

统一端点相较 pass-through 的优势：负载均衡、回退（fallbacks）、对成本追踪与终端用户追踪的一致支持。

鉴权方式一 · 静态 API key：

export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

或在 Claude Code settings 中：

{ "env": { "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key" } }

该值作为 Authorization 头发送。

鉴权方式二 · 动态 key（helper，用于轮换/按用户鉴权）：

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

export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000   # 每小时刷新

apiKeyHelper 的输出同时作为 Authorization 与 X-Api-Key 头发送，优先级低于 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY。

Pass-through 端点（替代方案）：

# Claude API
export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
# Amazon Bedrock
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
# Google Vertex AI
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
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

网关模型发现（可选）：当 ANTHROPIC_BASE_URL 指向暴露 Anthropic Messages 格式的网关时，设 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，启动时查询网关 /v1/models 并把返回模型加入 /model 选择器（需 v2.1.129+）。

什么时候用

• 需要集中管理 API key 与单点鉴权
• 需要跨团队/项目追踪用量、做成本控制（预算与限流）
• 需要审计日志以满足合规
• 需要在不改代码的情况下做模型路由、切换提供方、负载均衡或回退

限制 / 坑

• LiteLLM 是第三方代理服务，Anthropic 不背书、不维护、不审计其安全性或功能；本指南仅供参考，可能过时，使用风险自负
• LiteLLM PyPI 1.82.7 与 1.82.8 版本被植入窃取凭据的恶意代码，切勿安装；若已安装需移除包、轮换受影响系统全部凭据
• 网关模型发现仅适用于 Anthropic Messages 格式，不对 Bedrock/Vertex pass-through 端点运行，且 ANTHROPIC_BASE_URL 未设或指向 api.anthropic.com 时不运行
• 若网关不转发头或不保留请求体字段，可能导致功能受限或无法使用 Claude Code 功能

硬事实速查（12 条）

• 统一端点（ANTHROPIC_BASE_URL=https://litellm-server:4000）为推荐方式，优于 pass-through
• ANTHROPIC_AUTH_TOKEN 作为 Authorization 头发送
• apiKeyHelper 的输出同时作为 Authorization 与 X-Api-Key 头发送，优先级低于 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY
• CLAUDE_CODE_API_KEY_HELPER_TTL_MS 控制 token 刷新间隔（示例 3600000 ms = 每小时）
• Bedrock pass-through 需 ANTHROPIC_BEDROCK_BASE_URL + CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 + CLAUDE_CODE_USE_BEDROCK=1
• Vertex pass-through 需 ANTHROPIC_VERTEX_BASE_URL + ANTHROPIC_VERTEX_PROJECT_ID + CLAUDE_CODE_SKIP_VERTEX_AUTH=1 + CLAUDE_CODE_USE_VERTEX=1 + CLOUD_ML_REGION
• 模型发现通过 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 开启，默认关闭，需 v2.1.129+，结果缓存到 ~/.claude/cache/gateway-models.json
• 模型发现只把 ID 以 claude 或 anthropic 开头的模型加入 /model 选择器，每个发现项标记为 From gateway
• 用 Anthropic Messages 格式对接 Bedrock/Vertex 时可能需 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
• 若网关自有 prompt 缓存基于完整请求体，可设 CLAUDE_CODE_ATTRIBUTION_HEADER=0 省略归因块
• X-Claude-Code-Session-Id / X-Claude-Code-Agent-Id / X-Claude-Code-Parent-Agent-Id 三个头可用于代理侧归因用量，且为每次 spawn 的临时标识
• Claude Platform on AWS 经网关需 ANTHROPIC_AWS_BASE_URL + ANTHROPIC_AWS_WORKSPACE_ID + CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1 + CLAUDE_CODE_USE_ANTHROPIC_AWS=1

---

官方出处：https://code.claude.com/docs/en/llm-gateway