古法编程

LLM 网关是在 Claude Code 和模型提供商之间的集中代理层，解决 API 密钥统一管理、用量追踪和成本控制问题。配置前需要确保网关支持 Anthropic Messages、Bedrock InvokeModel 或 Vertex rawPredict 三种 API 格式之一，并正确转发请求头；集成 LiteLLM 时，推荐使用统一端点，若用动态 API key 则需创建辅助脚本并设置刷新间隔。

Claude Code LLM 网关配置：LiteLLM 集成与认证方式

LLM 网关在 Claude Code 和模型提供商之间提供集中代理层，通常提供：

  • 集中认证：API Key 管理的单一入口
  • 使用量追踪：跨团队和项目监控使用情况
  • 成本控制：实施预算和速率限制
  • 审计日志：记录所有模型交互以满足合规需求
  • 模型路由：无需更改代码即可切换提供商

网关要求

LLM 网关必须满足以下要求才能与 Claude Code 配合使用。

API 格式

至少支持以下 API 格式之一：

  1. Anthropic Messages：/v1/messages、/v1/messages/count_tokens

    • 必须转发请求头：anthropic-beta、anthropic-version

  2. Bedrock InvokeModel：/invoke、/invoke-with-response-stream

    • 必须保留请求体字段：anthropic_beta、anthropic_version

  3. Vertex rawPredict：:rawPredict、:streamRawPredict、/count-tokens:rawPredict

    • 必须转发请求头：anthropic-beta、anthropic-version

未转发必要头或保留字段可能导致功能减少或无法使用 Claude Code 特性。

Claude Code 根据 API 格式决定启用哪些功能。当通过 Bedrock 或 Vertex 使用 Anthropic Messages 格式时，可能需要设置环境变量 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

请求头

Claude Code 在每个 API 请求上都会携带以下头：

头 说明
X-Claude-Code-Session-Id 当前会话的唯一标识符。代理可以用它聚合同一会话的所有 API 请求，无需解析请求体。
X-Claude-Code-Agent-Id 发起请求的子代理或队友的标识符。代理可以用它将 API 成本归因到会话内的并行子代理，无需解析请求体。仅由进程内的子代理或队友发起的请求携带此头。
X-Claude-Code-Parent-Agent-Id 创建该发起请求的 agent 的 agent 标识符。与 X-Claude-Code-Agent-Id 配合，可在代理中跨嵌套 agent 归因 API 成本。仅当发起请求的 agent 本身是由另一个 agent 创建时携带。

两个 agent ID 头是每次生成的临时标识符，不是持久的用户或设备 ID。

Claude Code 还会在系统提示前附加一个短的归属块，包含客户端版本和从对话派生的指纹。Anthropic API 在处理前会剥离此块，因此不影响第一方提示缓存。如果网关基于完整请求体实现自己的提示缓存键，可以设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 来忽略它。

模型选择

默认情况下，Claude Code 使用所选 API 格式的标准模型名称。

当 ANTHROPIC_BASE_URL 指向一个暴露了 Anthropic Messages 格式的网关时，Claude Code 可以在启动时查询网关的 /v1/models 端点，并将返回的模型添加到 /model 选择器中。设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 以启用此功能。

模型发现默认关闭，这样可以防止由共享 API Key 支持的网关将每个 Key 可访问的所有模型暴露给每个用户。每个发现的条目会标记为“From gateway”，并在响应中提供 display_name 字段时使用该字段。此功能需要 Claude Code v2.1.129 或更高版本。

发现请求的认证方式与推理请求相同：发送 ANTHROPIC_AUTH_TOKEN 作为 bearer token，或当未设置 auth token 时发送 ANTHROPIC_API_KEY 作为 x-api-key 头，同时携带 ANTHROPIC_CUSTOM_HEADERS 中的任何头。只有 ID 以 claude 或 anthropic 开头的模型才会添加到选择器中。结果缓存到 ~/.claude/cache/gateway-models.json，并在每次启动时刷新。如果请求失败或网关未实现 /v1/models，选择器会回退到上次启动的缓存列表或内置模型列表。

模型发现仅适用于 Anthropic Messages 格式。对于 Bedrock 或 Vertex 透传端点不会运行，当 ANTHROPIC_BASE_URL 未设置或指向 api.anthropic.com 时也不会运行。

如果网关使用的模型名称与发现过滤条件不匹配，使用 模型配置 中记录的环境变量手动添加它们。

LiteLLM 配置

LiteLLM PyPI 版本 1.82.7 和 1.82.8 已被凭证窃取恶意软件入侵。请勿安装这些版本。如果已安装：

  • 移除该包
  • 轮换所有受影响系统上的凭证
  • 按照 BerriAI/litellm#24518 中的补救步骤操作

LiteLLM 是第三方代理服务。Anthropic 不认可、不维护、也不审计 LiteLLM 的安全性或功能性。本指南仅供参考，可能会过时。请自行斟酌使用。

前提条件

  • Claude Code 已更新至最新版本
  • LiteLLM Proxy Server 已部署并可访问
  • 通过所选提供商可访问 Claude 模型

基础 LiteLLM 设置

配置 Claude Code：

认证方式

静态 API Key

最简单的方式，使用固定 API Key：

# 通过环境变量设置
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# 或在 Claude Code 设置中
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

此值作为 Authorization 头发送。

动态 API Key（辅助脚本）

适用于轮换密钥或每用户认证：

  1. 创建 API key 辅助脚本：
#!/bin/bash
# ~/bin/get-litellm-key.sh

# 示例：从 Vault 获取 key
vault kv get -field=api_key secret/litellm/claude-code

# 示例：生成 JWT token
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'
  1. 在 Claude Code 设置中配置辅助脚本：
{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}
  1. 设置令牌刷新间隔：
# 每小时刷新（3600000 毫秒）
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

此值作为 Authorization 和 X-Api-Key 头发送。apiKeyHelper 的优先级低于 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY。

统一端点（推荐）

使用 LiteLLM 的 Anthropic 格式端点：

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

统一端点优于透传端点：

  • 负载均衡
  • 故障转移
  • 一致的成本追踪和终端用户追踪

提供商特定的透传端点（替代方案）

通过 LiteLLM 使用 Claude API

使用 透传端点：

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
通过 LiteLLM 使用 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
通过 LiteLLM 使用 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
通过网关路由到 Claude Platform on AWS

路由到转发到 Claude Platform on AWS 端点的网关：

export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

更多信息请参考 LiteLLM 文档。

相关资源

常见问题

为什么统一端点比透传端点推荐？

统一端点支持 LiteLLM 的负载均衡和故障转移，并且能一致地追踪成本和终端用户。透传端点适合需要直接使用特定提供商（如 Bedrock、Vertex）格式的场景，但会丢失统一端点的上层能力。

LiteLLM 版本 1.82.7 或 1.82.8 有什么安全问题？

这两个版本被植入凭证窃取恶意软件。如果已安装，需要立即移除包、轮换所有受影响系统上的凭证，并按照 BerriAI/litellm#24518 中的步骤进行补救。

网关配置后模型不显示在 /model 选择器中怎么办？

检查是否设置了 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，且网关暴露了 /v1/models 端点。模型发现默认关闭，且仅适用于 Anthropic Messages 格式。如果网关使用自定义模型名称，需要手动通过环境变量添加。