LiteLLM 搭建大模型网关实战（2026）

你有 Claude Code、Codex CLI、DeepSeek API、GLM 免费额度——但它们各自的 Key 分散在四个地方，每个工具配置不一样，账单也看不清楚。LiteLLM Proxy 就是把这四个变成一个的工具：一个本地 HTTP 网关，统一 OpenAI 兼容接口，所有 AI 工具指向同一个地址，你在 config.yaml 里管理所有 Key 和路由规则。

本文是实战教程，不讲原理，直接带你搭。从零开始，最终实现：

• Claude Code 通过 LiteLLM Proxy 路由到 DeepSeek / GLM（国内直连节省费用）
• OpenAI Codex CLI 通过同一个 Proxy 使用 Claude Sonnet 5 / DeepSeek 混合编程
• 主线路挂了自动切备用（故障转移），多个 Key 自动轮换（防限速）
• 给团队成员发虚拟 Key，设置消费上限
• Docker 生产部署，加 PostgreSQL + Redis

一、架构图：你将搭建什么

┌─────────────────────────────────────────────────┐
│              你的本地 / 服务器                    │
│                                                 │
│  Claude Code ──┐                                │
│  Codex CLI   ──┼──► LiteLLM Proxy :4000 ──────► │──► Anthropic API
│  任意脚本    ──┘   (config.yaml 管理路由)        │──► OpenAI API
│                     │                           │──► DeepSeek API（国内直连）
│                     ├── 负载均衡                 │──► 智谱 GLM API（国内直连）
│                     ├── 故障转移                 │──► 硅基流动等中转站
│                     ├── 虚拟 Key 管理            │
│                     └── 成本追踪                 │
└─────────────────────────────────────────────────┘

所有 AI 工具的请求统一打到 http://localhost:4000，LiteLLM 负责：

• 把 Anthropic 格式的请求（Claude Code 发的）翻译成 OpenAI / DeepSeek / GLM 的格式
• 把 OpenAI 格式的请求（Codex 发的）路由到任意 Provider
• 主线路失败时自动 fallback 到备用
• 多个 API Key 轮换，防止单 Key 被限速

二、安装 LiteLLM

# 推荐用 uv（快 10 倍）
uv tool install 'litellm[proxy]'

# 或 pip
pip install 'litellm[proxy]'

# 验证
litellm --version
# 应输出 v1.91.0 或更高

三、核心 config.yaml 结构

LiteLLM Proxy 的所有配置都在一个 config.yaml 文件里。先看骨架：

model_list:              # 你对外暴露的"模型菜单"
  - model_name: xxx      # 客户端调用时用的名字
    litellm_params:
      model: provider/model-id   # 实际调用的 Provider 和模型
      api_key: os.environ/XXX    # Key 从环境变量读取，不硬编码

litellm_settings:        # 全局行为设置
  drop_params: true      # 自动丢弃目标模型不支持的参数
  num_retries: 3

general_settings:        # Proxy 服务器设置
  master_key: sk-1234    # 调用 Proxy 需要带的 Key

router_settings:         # 路由策略
  routing_strategy: simple-shuffle

model_name 是你给外部工具看到的名字，可以随便起。litellm_params.model 才是 LiteLLM 实际转发到的 Provider。

四、接入 Claude Code

Claude Code 使用 Anthropic Messages API 格式。LiteLLM 会自动把这个格式翻译成目标 Provider 的格式，再把响应翻译回来。

4.1 原理

Claude Code 读取两个环境变量：

• ANTHROPIC_BASE_URL：把 API 请求打到这里（改成你的 LiteLLM 地址）
• ANTHROPIC_AUTH_TOKEN：Authorization Bearer Token（填 LiteLLM 的 master_key）

4.2 配置步骤

Step 1：在 config.yaml 里配置你希望 Claude Code 使用的模型：

model_list:
  # Claude Code 主力：Claude Sonnet 5（Anthropic 官方）
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # 便宜备用：DeepSeek V4 Flash（国内直连，成本 ↓90%）
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_API_KEY

  # 免费备用：GLM-4.7-Flash（永久免费）
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY

general_settings:
  master_key: sk-my-proxy-key

Step 2：启动 LiteLLM Proxy：

litellm --config config.yaml
# 输出：LiteLLM Proxy running on http://0.0.0.0:4000

Step 3：设置环境变量，然后启动 Claude Code：

# 设置环境变量（加到 ~/.zshrc 或 ~/.bashrc 永久生效）
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-my-proxy-key"

# 使用 Anthropic 原生 Claude（默认）
claude

# 切换到 DeepSeek（省钱）
claude --model deepseek-flash

# 切换到免费 GLM
claude --model glm-flash

# 启用面板内 /model 切换功能（需要 Claude Code v2.1.129+）
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude  # 进入后用 /model 命令列出并切换

4.3 验证是否成功

# 直接 curl 验证 Proxy 是否在转发 Claude Code 格式的请求
curl http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-my-proxy-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-flash",
    "max_tokens": 50,
    "messages": [{"role": "user", "content": "回复 ok"}]
  }'
# 应返回 DeepSeek 的响应，但格式是 Anthropic Messages 格式

五、接入 OpenAI Codex CLI

Codex CLI（@openai/codex）使用 OpenAI Chat Completions 格式。它读取 OPENAI_BASE_URL 和 OPENAI_API_KEY 两个变量。

5.1 安装 Codex CLI

npm install -g @openai/codex
# 或
yarn global add @openai/codex

5.2 配置

Codex 用的是 OpenAI 格式，直接用 /v1/chat/completions 端点，不需要额外翻译层：

# 把 Codex 指向 LiteLLM Proxy（OpenAI 兼容端点）
export OPENAI_BASE_URL="http://localhost:4000"
export OPENAI_API_KEY="sk-my-proxy-key"   # LiteLLM master_key

# 用 Claude Sonnet 5 跑 Codex（通过 Proxy 转发）
codex --model claude-sonnet-5

# 用 DeepSeek 跑 Codex（更便宜）
codex --model deepseek-flash --full-auto

# 用 GLM 免费版
codex --model glm-flash

5.3 Codex config.toml 永久配置

# ~/.codex/config.toml
model = "deepseek-flash"          # 默认用 DeepSeek
provider = "openai"
base-url = "http://localhost:4000"

[model-options]
temperature = 0.2

配置后直接 codex 就能用，不需要每次带 --model 参数。

六、接入 DeepSeek（多 Key 负载均衡）

DeepSeek 官方 API 在国内无法直连（api.deepseek.com），推荐通过硅基流动等国内中转站调用 DeepSeek 模型。多账号 Key 可以分散限速压力。

6.1 通过硅基流动（国内直连）

model_list:
  # 硅基流动 Key 1（主力）
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      rpm: 50   # 该 Key 每分钟最多 50 次请求

  # 硅基流动 Key 2（分摊流量）
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_2
      rpm: 50

  # DeepSeek 旗舰版（高质量，贵一些）
  - model_name: deepseek-pro
    litellm_params:
      model: openai/deepseek-v4-pro
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1

两个 model_name: deepseek-flash 条目，LiteLLM 自动在它们之间做负载均衡——当 Key 1 被限速时自动切 Key 2，完全透明。

6.2 通过 DeepSeek 官方（需代理）

  - model_name: deepseek-official
    litellm_params:
      model: deepseek/deepseek-chat   # litellm 内置 deepseek/ 前缀
      api_key: os.environ/DEEPSEEK_API_KEY

6.3 设置环境变量

# .env 文件或直接 export
export SILICONFLOW_KEY_1="sk-sf-xxxxxxxx"
export SILICONFLOW_KEY_2="sk-sf-yyyyyyyy"
export DEEPSEEK_API_KEY="sk-deepseek-zzzzzzzz"

七、接入智谱 GLM（含免费模型）

智谱 AI（bigmodel.cn）有国内直连 API，GLM-4.7-Flash 永久免费，31B MoE 参数，SWE-bench 59.2%，200K 上下文，适合用作低成本备用。

7.1 注册与获取 Key

1. 访问 bigmodel.cn 注册
2. 实名认证后获得 2000 万 tokens 免费额度
3. 在控制台生成 API Key

7.2 config.yaml 配置

model_list:
  # GLM 免费旗舰（永久免费，编程能力强）
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash    # LiteLLM 内置 zai/ 前缀支持智谱
      api_key: os.environ/ZAI_API_KEY

  # GLM 旗舰版（付费，更强）
  - model_name: glm-pro
    litellm_params:
      model: zai/glm-5.2
      api_key: os.environ/ZAI_API_KEY

  # GLM 视觉版（免费）
  - model_name: glm-vision
    litellm_params:
      model: zai/glm-4.6v-flash
      api_key: os.environ/ZAI_API_KEY

export ZAI_API_KEY="your-glm-api-key"

7.3 验证 GLM 连通

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-my-proxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-flash",
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

八、故障转移：主挂自动切备用

这是 LiteLLM 最实用的功能之一：主模型挂了（限速、宕机、报错），自动切换到备用模型，调用方感知不到。

8.1 用 order 参数设置优先级

model_list:
  # 主力：Claude Sonnet 5（最强，优先用）
  - model_name: best-model
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
      order: 1   # 最高优先级

  # 备用 1：DeepSeek（便宜，国内直连）
  - model_name: best-model
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      order: 2   # Claude 挂了用这个

  # 备用 2：GLM 免费版（兜底）
  - model_name: best-model
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY
      order: 3   # 最后兜底

所有条目的 model_name 相同，调用时统一用 best-model。LiteLLM 先试 order=1，失败后自动升级到 order=2，再失败到 order=3。

8.2 用 fallbacks 参数设置跨模型组兜底

litellm_settings:
  # 主模型失败时的跨组 fallback
  fallbacks:
    - claude-sonnet-5: ["deepseek-flash", "glm-flash"]
    - deepseek-flash: ["glm-flash"]

  # 限速时的专项 fallback（429 错误）
  content_policy_fallbacks:
    - claude-sonnet-5: ["deepseek-flash"]

  # 超出上下文窗口时的 fallback
  context_window_fallbacks:
    - claude-sonnet-5: ["glm-flash"]   # GLM 有 200K 上下文

  num_retries: 3        # 每个部署重试3次再切
  allowed_fails: 3      # 1分钟内失败超3次触发冷却
  cooldown_time: 30     # 冷却30秒

九、完整 config.yaml（四合一）

把前面所有配置合并成一个完整的 config.yaml，可以直接使用：

# config.yaml — LiteLLM 四合一网关配置
# Claude Code + Codex CLI + DeepSeek + GLM

model_list:
  # ── Claude Sonnet 5（Anthropic 官方）──────────────────────
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # ── DeepSeek Flash（硅基流动，国内直连，双Key轮换）───────
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      rpm: 50

  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_2
      rpm: 50

  # ── DeepSeek 旗舰版（高质量）─────────────────────────────
  - model_name: deepseek-pro
    litellm_params:
      model: openai/deepseek-v4-pro
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1

  # ── GLM 免费版（永久免费兜底）────────────────────────────
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY

  # ── GLM 旗舰付费版────────────────────────────────────────
  - model_name: glm-pro
    litellm_params:
      model: zai/glm-5.2
      api_key: os.environ/ZAI_API_KEY

  # ── best-model：有优先级的自动故障转移组 ─────────────────
  - model_name: best-model
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
      order: 1

  - model_name: best-model
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      order: 2

  - model_name: best-model
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY
      order: 3

litellm_settings:
  drop_params: true
  num_retries: 3
  request_timeout: 60
  allowed_fails: 3
  cooldown_time: 30
  fallbacks:
    - claude-sonnet-5: ["deepseek-flash", "glm-flash"]
    - deepseek-flash: ["glm-flash"]
  context_window_fallbacks:
    - claude-sonnet-5: ["glm-flash"]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  alerting: ["slack"]    # 可选，慢请求/错误 Slack 告警

router_settings:
  routing_strategy: simple-shuffle

# .env 文件（同目录下）
ANTHROPIC_API_KEY=sk-ant-xxx
SILICONFLOW_KEY_1=sk-sf-xxx
SILICONFLOW_KEY_2=sk-sf-yyy
ZAI_API_KEY=your-glm-key
LITELLM_MASTER_KEY=sk-my-proxy-2026

# 启动（自动读取当前目录的 .env）
litellm --config config.yaml

# 验证所有模型可用
curl http://localhost:4000/models \
  -H "Authorization: Bearer sk-my-proxy-2026" | python3 -m json.tool

十、虚拟 Key 与团队预算

如果是团队使用，不要把 master_key 发给所有人——通过虚拟 Key 给每人独立的限额：

10.1 创建虚拟 Key

# 给开发者 Alice 创建虚拟 Key（每月限额 $5，只能用 deepseek-flash 和 glm-flash）
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-my-proxy-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "dev-team",
    "max_budget": 5.0,
    "budget_duration": "30d",
    "models": ["deepseek-flash", "glm-flash"],
    "metadata": {"user": "alice@company.com"}
  }'

# 返回：{"key": "sk-virtual-abc123", "expires": "2026-08-08", ...}

# Alice 用她的虚拟 Key 调 Codex，只能用允许的模型，超预算自动拒绝
export OPENAI_API_KEY="sk-virtual-abc123"
export OPENAI_BASE_URL="http://localhost:4000"
codex --model deepseek-flash

10.2 查看消费情况

# 查看某个 Key 的消费详情
curl http://localhost:4000/key/info?key=sk-virtual-abc123 \
  -H "Authorization: Bearer sk-my-proxy-2026"

# 查看所有 Key 的消费汇总
curl http://localhost:4000/global/spend \
  -H "Authorization: Bearer sk-my-proxy-2026"

十一、Docker 生产部署

11.1 单容器快速部署

# docker-compose.yml（最简版）
version: '3.8'
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    command: --config /app/config.yaml --port 4000 --num_workers 8
    restart: unless-stopped

docker compose up -d
docker compose logs -f litellm   # 查看日志

11.2 完整生产部署（PostgreSQL + Redis）

1000+ RPM 的生产场景，需要 PostgreSQL 持久化虚拟 Key 和消费数据，Redis 做分布式限速状态共享：

# docker-compose.prod.yml
version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${'{POSTGRES_PASSWORD}'}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 10s

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgresql://litellm:${'{POSTGRES_PASSWORD}'}@postgres:5432/litellm
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    command: --config /app/config.yaml --port 4000 --num_workers 8
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:

在 config.yaml 的 router_settings 里启用 Redis：

router_settings:
  routing_strategy: usage-based-routing  # 需要 Redis 的策略
  redis_host: redis
  redis_port: 6379
  cache_responses: true   # 完全相同的请求直接返回缓存，降低成本

十二、调试与排障

12.1 开启详细日志

# 启动时开启 debug 模式
litellm --config config.yaml --detailed_debug

# 可以看到：每次请求的路由决策、重试日志、实际使用的 Provider

12.2 健康检查

# 检查 Proxy 自身状态
curl http://localhost:4000/health

# 检查所有配置的模型是否可达
curl http://localhost:4000/health/liveliness \
  -H "Authorization: Bearer sk-my-proxy-2026"

12.3 常见错误速查

错误	原因	解决
401 Unauthorized	Authorization header 缺失或 Key 错误	确认 -H "Authorization: Bearer <master_key>"
404 Not Found（模型）	请求的 model_name 不在 config.yaml 里	curl /models 查看可用模型列表
429 Too Many Requests	该模型所有 Key 都被限速且在冷却	增加 Key、减小 cooldown_time、加 fallback
连接拒绝（Claude Code）	ANTHROPIC_BASE_URL 指向的端口没有运行 Proxy	确认 litellm --config 在运行；检查防火墙
GLM 返回 400	model 字段没用 zai/ 前缀	改为 model: zai/glm-4.7-flash
Codex 模型不识别	model_name 和 config.yaml 里的不一致	严格匹配大小写，glm-flash ≠ GLM-flash

十三、常见问题

Q：我的 Claude Code 一直用的 Anthropic 官方，改到 Proxy 后会不会影响工具调用（Tool Use）？

A：LiteLLM 对 Claude Code 的 Anthropic Messages API 有完整支持，包括 tool_use、system prompt、vision、streaming。如果目标模型是 Anthropic 原生（anthropic/ 前缀），透传无损失。如果目标是 DeepSeek / GLM，LiteLLM 会把 Anthropic tool_use 格式转换成 OpenAI function_calling 格式——大部分 tool 场景正常工作，但极少数 Anthropic 特有的 tool 特性可能需要调整。

Q：Codex CLI 的 --full-auto 模式通过 Proxy 运行安全吗？

A：安全性取决于模型和你的系统，与 Proxy 无关。--full-auto 让 Codex 自动执行文件操作，建议在单独的 Docker 容器或 VM 里运行，无论用不用 Proxy 都是如此。

Q：GLM-4.7-Flash 免费的，用来跑 Claude Code 编程效果够吗？

A：GLM-4.7-Flash 在 SWE-bench 上得分 59.2%，和早期 Claude 3.5 Sonnet 相当，处理中型任务完全没问题。复杂多文件重构建议切回 Claude Sonnet 5；日常简单代码生成、解释、修 bug 用 GLM-Flash 够用且零成本。

Q：Proxy 会把我的请求内容存下来吗？

A：默认不存。开启 Langfuse / MLflow 等 callback 才会记录内容。虚拟 Key 的消费记录（token 数、费用）存在 PostgreSQL 里，但不包含请求内容本身。

Q：可以把 Proxy 部署在云端，让团队所有人用吗？

A：可以，这是 Proxy 模式最典型的用法。部署到云服务器后，改 ANTHROPIC_BASE_URL=https://你的域名，加 HTTPS（Nginx/Caddy）和防火墙。给每人发虚拟 Key，不需要分发真实 API Key。