LiteLLM Config 🔀

通过 LiteLLM Proxy 将国内外主流大模型统一成一个 OpenAI 兼容接口，支持自动 Fallback。

快速开始

# 第一步：交互式引导配置 API Key + 启动
bash setup.sh

# 或手动启动（免费模型链 4000 端口）
bash bin/start.sh

# 第二步：验证
curl http://localhost:4000/health

接入 Claude Code（让所有请求经由 Proxy，自动 Fallback）：

export ANTHROPIC_BASE_URL=http://localhost:4000
claude

选择配置文件

选择逻辑

追求最强编程能力，不在意费用       → config/config-global.yml
在国内，日常编码 / 自动化          → config/config.yml
预算有限 / 只想试用                → config/config-free.yml
Claude Code 用户，断线不中断       → config/config-claude-fallback.yml

与 Claude Code 集成

方式一：Proxy 路由（推荐，支持 Fallback）

# 启动 Claude Fallback 服务（4001 端口）
bash bin/start-claude.sh

export ANTHROPIC_BASE_URL=http://localhost:4001
# 永久生效
echo 'export ANTHROPIC_BASE_URL=http://localhost:4001' >> ~/.zshrc

方式二：直接调用 Proxy

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"hello"}]}'

安全注意事项

• .env 含真实 API 密钥 — 确保 .gitignore 已包含 .env
• setup.sh 会创建系统服务（launchd / systemd），需要用户确认
• LITELLM_MASTER_KEY 是客户端连接 Proxy 的鉴权密钥，自定义设置即可

参考文档

• 平台参考 — API Key 获取入口、免费额度说明、平台选型速查
• 命令参考 — 启动命令、健康检查、测试调用、系统自启管理、常见问题排查

🧪 Claude Fallback 专用测试

Claude fallback 配置运行在 4001 端口，使用 config/config-claude-fallback.yml。

快速测试

cd ~/.openclaw/workspace/skills/litellm-config
bash tests/test-claude-fallback.sh

预期输出（无 ANTHROPIC_API_KEY 时）：

[1/3] claude-sonnet-4-6 → qwen3-coder-plus → OK
[2/3] claude-opus-4-6 → qwen3-coder-plus → OK
[3/3] claude-haiku-4-5 → qwen3-coder-plus → OK

如果配置了 ANTHROPIC_API_KEY，将直接使用 Claude 官方，不再 fallback。

手动 API 测试

# 查看已注册模型（包含 Claude 和 fallback 链）
curl -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  http://127.0.0.1:4001/v1/models

# 测试 Claude 调用（自动 fallback）
curl -X POST http://127.0.0.1:4001/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Say: CLAUDE"}],
    "max_tokens": 5
  }'

启动/停止服务

# 方式1：前台启动
bash bin/start-claude.sh

# 方式2：launchd 系统服务（后台）
launchctl start litellm-proxy-claude
launchctl stop litellm-proxy-claude

🔄 模型配置更新

全量获取各平台模型（fetch-models）

将各知名平台的及格线以上模型全量拉取，每平台保存为一份 JSON 文件（models/<platform>.json）。

cd ~/.openclaw/workspace/skills/litellm-config

# 获取所有平台（需对应 API Key 环境变量）
bash bin/fetch-models.sh

# 只获取指定平台
bash bin/fetch-models.sh deepseek qwen

# 查看帮助
bash bin/fetch-models.sh --help

支持平台：

输出：models/<platform>.json，包含平台信息、获取时间、模型列表（已过滤 embedding/TTS/图像等非 LLM 模型）。

检查并更新配置（update-models）

定期运行以下命令检查并更新模型配置，保持免费模型列表始终有效：

cd ~/.openclaw/workspace/skills/litellm-config

# 报告模式：检查当前配置状态（不修改文件）
bash bin/update-models.sh

# 应用模式：自动移除失效的 OpenRouter :free 模型
bash bin/update-models.sh --apply

脚本功能

更新流程

1. bash bin/fetch-models.sh            # 全量拉取各平台最新模型列表（可选）
2. bash bin/update-models.sh           # 查看配置更新报告
3. bash bin/update-models.sh --apply   # 自动移除失效模型
4. 根据报告手动添加新模型（参考 CLAUDE.md §新增平台标准流程）
5. 检查豆包模型 ID 是否需要手动更新（参考 https://www.volcengine.com/docs/82379/1330310）
6. bash bin/check-models.sh            # 验证所有模型可正常响应

🧪 测试方法

健康检查

curl http://localhost:4000/health

测试所有模型组（需要 LITELLM_MASTER_KEY）

# 1. 测试 free-coding（编码助手）
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "free-coding",
    "messages": [{"role": "user", "content": "Write a Python hello world"}],
    "max_tokens": 50
  }'

# 2. 测试 free-chat（对话助手）
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "free-chat",
    "messages": [{"role": "user", "content": "Explain quantum computing in 2 sentences"}],
    "max_tokens": 50
  }'

# 3. 测试 free-auto（自动化任务）
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "free-auto",
    "messages": [{"role": "user", "content": "Plan: research AI trends, summarize, email report"}],
    "max_tokens": 50
  }'

测试脚本（推荐）

bash tests/test-litellm.sh

🧪 免费模型链测试（4000 端口）

适用于 config/config-free.yml（默认 4000 端口）。

# 使用测试脚本
bash tests/test-litellm.sh

# 或手动 curl
curl -X POST http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"free-coding","messages":[{"role":"user","content":"Say: OK"}],"max_tokens":3}'

测试脚本详解

test-litellm.sh 会测试三个模型组：

• free-coding：编码助手 → DashScope qwen3-coder-plus
• free-chat：对话助手 → DashScope qwen3-max
• free-auto：自动化任务 → LongCat Flash-Thinking-2601

🔌 与 OpenClaw 集成

将 LiteLLM Proxy 配置为 OpenClaw 的主模型提供商。

步骤 1：确保 LiteLLM 正在运行

# 前台启动（测试）
bash bin/start.sh

# 或作为系统服务（后台）
launchctl start litellm-proxy

步骤 2：更新 OpenClaw 配置

编辑 ~/.openclaw/openclaw.json，添加/修改：

{
  "models": {
    "providers": {
      "litellm": {
        "baseUrl": "http://127.0.0.1:4000",
        "apiKey": "your_liteLLm_master_key",
        "api": "openai-completions",
        "authHeader": true
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "litellm/free-coding",
        "fallbacks": [
          "litellm/free-chat",
          "litellm/free-auto"
        ]
      }
    }
  }
}

步骤 3：重启 OpenClaw

# 方法一：通过配置工具
openclaw config apply

# 方法二：重启网关
openclaw gateway restart

验证集成

# 发送测试消息到 OpenClaw（通过任意通道）
# 应看到 LiteLLM 日志显示请求路由到不同后端
tail -f /path/to/litellm-config/litellm.log

📝 常见问题排查

🚀 系统服务（macOS launchd）

plist 已配置好，API Key 从 .env 读取，无需在 plist 中重复填写。

# 重载（更新 .env 或 config 后执行）
launchctl unload ~/Library/LaunchAgents/litellm-proxy.plist
launchctl load   ~/Library/LaunchAgents/litellm-proxy.plist

# 日常管理
launchctl start litellm-proxy        # 免费链 4000 端口
launchctl stop  litellm-proxy
launchctl start litellm-proxy-claude # Claude fallback 4001 端口
launchctl stop  litellm-proxy-claude

# 查看状态
launchctl list | grep litellm

📚 更多

• LiteLLM 官方文档
• 测试指南 - 详细测试步骤和故障排查
• 安全策略 - 安全最佳实践