LLM路由

一个智能代理，根据传入请求的复杂度进行分类，并将其路由到相应的大语言模型。简单任务使用更便宜/更快速的模型，复杂任务则保留给昂贵的模型。

与OpenClaw配合使用，通过将简单请求路由到较小的模型来减少令牌使用量和API成本。

状态：已通过Anthropic、OpenAI、Google Gemini、Kimi/Moonshot和Ollama测试。

快速开始

先决条件

1. Python 3.10+以及pip
2. Ollama（可选 - 仅在使用本地分类时需要）
3. Anthropic API密钥或Claude Code OAuth令牌（或其他提供商的密钥）

设置

# Clone if not already present
git clone https://github.com/alexrudloff/llmrouter.git
cd llmrouter

# Create virtual environment (required on modern Python)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Pull classifier model (if using local classification)
ollama pull qwen2.5:3b

# Copy and customize config
cp config.yaml.example config.yaml
# Edit config.yaml with your API key and model preferences

验证安装

# Start the server
source venv/bin/activate
python server.py

# In another terminal, test health endpoint
curl http://localhost:4001/health
# Should return: {"status": "ok", ...}

启动服务器

python server.py

选项：

• --port PORT- 监听的端口（默认：4001）
• --host HOST- 要绑定的主机地址（默认：127.0.0.1）
• --config PATH- 配置文件路径（默认：config.yaml）
• --log- 启用详细日志记录
• --openclaw- 启用 OpenClaw 兼容性（在系统提示中重写模型名称）

配置

编辑config.yaml以进行自定义：

模型路由

# Anthropic routing
models:
  super_easy: "anthropic:claude-haiku-4-5-20251001"
  easy: "anthropic:claude-haiku-4-5-20251001"
  medium: "anthropic:claude-sonnet-4-20250514"
  hard: "anthropic:claude-opus-4-20250514"
  super_hard: "anthropic:claude-opus-4-20250514"

# OpenAI routing
models:
  super_easy: "openai:gpt-4o-mini"
  easy: "openai:gpt-4o-mini"
  medium: "openai:gpt-4o"
  hard: "openai:o3-mini"
  super_hard: "openai:o3"

# Google Gemini routing
models:
  super_easy: "google:gemini-2.0-flash"
  easy: "google:gemini-2.0-flash"
  medium: "google:gemini-2.0-flash"
  hard: "google:gemini-2.0-flash"
  super_hard: "google:gemini-2.0-flash"

注意：推理模型会自动检测并使用正确的 API 参数。

分类器

用于分类请求复杂性的三个选项：

本地（默认）- 免费，需要 Ollama：

classifier:
  provider: "local"
  model: "qwen2.5:3b"

Anthropic- 使用 Haiku 模型，快速且廉价：

classifier:
  provider: "anthropic"
  model: "claude-haiku-4-5-20251001"

OpenAI- 使用 GPT-4o-mini：

classifier:
  provider: "openai"
  model: "gpt-4o-mini"

谷歌- 使用 Gemini：

classifier:
  provider: "google"
  model: "gemini-2.0-flash"

Kimi- 使用 Moonshot：

classifier:
  provider: "kimi"
  model: "moonshot-v1-8k"

如果你的设备无法运行本地模型，请使用远程模型（anthropic/openai/google/kimi）。

支持的提供商

• anthropic:claude-*- Anthropic Claude 模型（已测试）
• openai:gpt-*,openai:o1-*,openai:o3-*- OpenAI 模型（已测试）
• google:gemini-*- 谷歌 Gemini 模型（已测试）
• kimi:kimi-k2.5,kimi:moonshot-*- Kimi/Moonshot 模型（已测试）
• local:model-name- 本地 Ollama 模型（已测试）

复杂度级别

自定义分类

编辑ROUTES.md以调整消息的分类方式。分类器读取此文件中的表格来确定复杂度级别。

API 使用

路由器暴露了一个与 OpenAI 兼容的 API：

curl http://localhost:4001/v1/chat/completions \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llm-router",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

测试分类

python classifier.py "Write a Python sort function"
# Output: medium

python classifier.py --test
# Runs test suite

作为 macOS 服务运行

创建~/Library/LaunchAgents/com.llmrouter.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.llmrouter</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/llmrouter/venv/bin/python</string>
        <string>/path/to/llmrouter/server.py</string>
        <string>--openclaw</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/path/to/llmrouter</string>
    <key>StandardOutPath</key>
    <string>/path/to/llmrouter/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/path/to/llmrouter/logs/stderr.log</string>
</dict>
</plist>

重要提示：替换/path/to/llmrouter为你的实际安装路径。必须使用 venv 中的 python，而非系统 python。

# Create logs directory
mkdir -p ~/path/to/llmrouter/logs

# Load the service
launchctl load ~/Library/LaunchAgents/com.llmrouter.plist

# Verify it's running
curl http://localhost:4001/health

# To stop/restart
launchctl unload ~/Library/LaunchAgents/com.llmrouter.plist
launchctl load ~/Library/LaunchAgents/com.llmrouter.plist

OpenClaw 配置

在~/.openclaw/openclaw.json中将路由器添加为一个提供者：

{
  "models": {
    "providers": {
      "localrouter": {
        "baseUrl": "http://localhost:4001/v1",
        "apiKey": "via-router",
        "api": "openai-completions",
        "models": [
          {
            "id": "llm-router",
            "name": "LLM Router (Auto-routes by complexity)",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

注意：成本设置为 0，因为实际成本取决于路由器选择哪个模型。路由器会记录每个请求由哪个模型处理。

设为默认模型（可选）

要默认对所有代理使用路由器，请添加：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "localrouter/llm-router"
      }
    }
  }
}

配合 OAuth 令牌使用

如果你的config.yaml使用了来自 OpenClaw~/.openclaw/auth-profiles.json路由器会自动处理Claude Code身份标头。

OpenClaw兼容模式（必需）

若与OpenClaw配合使用，您必须通过以下命令启动服务器：--openclaw：

python server.py --openclaw

此标志启用OpenClaw所需的兼容性功能：

• 重写响应中的模型名称，使OpenClaw显示实际使用的模型
• 处理工具名称和ID重映射，以确保工具调用的正确路由

若不使用此标志，在OpenClaw中使用路由器时可能会遇到错误。

常见任务

• 检查服务器状态：curl http://localhost:4001/health
• 查看当前配置：cat config.yaml
• 测试分类：python classifier.py "您的消息"
• 运行分类测试：python classifier.py --test
• 重启服务器: 停止并运行python server.py再次
• 查看日志（如果作为服务运行）：tail -f logs/stdout.log

故障排除

"externally-managed-environment" 错误

Python 3.11+ 要求使用虚拟环境。创建一个：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

端口 4001 上出现 "Connection refused"

服务器未运行。启动它：

source venv/bin/activate && python server.py

分类返回错误的复杂度

编辑ROUTES.md以调整分类规则。分类器读取此文件以确定复杂度级别。

Ollama 错误 / "model not found"

确保 Ollama 正在运行且模型已拉取：

ollama serve  # Start Ollama if not running
ollama pull qwen2.5:3b

OAuth 令牌无效

确保您在config.yaml 中的令牌以sk-ant-oat。路由器会自动检测OAuth令牌并添加所需的身份验证标头。

LaunchAgent未启动

检查日志并确保路径是绝对路径：

cat ~/Library/LaunchAgents/com.llmrouter.plist  # Verify paths
cat /path/to/llmrouter/logs/stderr.log  # Check for errors