Weave Router 是一个智能模型路由代理，它能根据请求内容动态选择最合适的 AI 模型，从而在保证性能的同时显著降低成本。它支持两种主要部署模式：托管模式（零基础设施，快速体验）和自托管模式（完全掌控，数据本地化）。本教程将分别介绍这两种方式。

开始之前

  • Node.js: 无论哪种模式，使用 npx 命令都需要 Node.js 18 或更高版本。
  • jq: 部分安装路径（如 Claude Code）需要 jq 命令行工具来处理 JSON 配置，请确保系统已安装。

路径一：托管模式（快速体验，无需维护）

这是官方推荐的快速开始方式，无需克隆代码、安装 Docker 或配置数据库，一条命令即可将你的 AI 编码工具接入托管服务。

1. 一键安装

在终端中直接运行以下命令，它将启动一个交互式安装向导：

1
npx @workweave/router

根据提示，你需要：

  1. 选择工具：选择你要接入的 AI 编码工具，如 Claude Code、Codex、opencode 或 pi。
  2. 选择作用域：选择 user（用户级配置）或 project（项目级配置，配置会提交到仓库中，方便团队共享，但密钥会保存在本地 .gitignore 中）。

你也可以通过添加参数跳过交互，直接配置特定工具：

1
2
3
4
npx @workweave/router --claude              # 直接配置 Claude Code
npx @workweave/router --codex               # 直接配置 Codex
npx @workweave/router --opencode            # 直接配置 opencode
npx @workweave/router --scope project       # 使用项目作用域

2. 工作原理

安装程序会自动修改对应工具的配置文件：

  • Claude Code: 修改 ~/.claude/settings.json，设置 ANTHROPIC_BASE_URL 等，使其请求指向 Weave 路由服务。
  • Codex: 修改 ~/.codex/config.toml，添加一个托管的路由器提供商配置块。
  • opencode: 修改 ~/.config/opencode/opencode.json，合并一个指向路由器的提供商条目。

安装后，你的工具请求会先发送给 Weave 托管的智能路由服务，该服务会根据你的请求内容动态选择最佳模型并代理调用，再将结果返回给你。你的上游提供商密钥（如OpenAI、Anthropic的密钥）会加密存储在你的本地。

3. 日常管理与开关

  • 开关路由：在不卸载配置的情况下，随时切换路由模式。

    1
    2
    3
    npx @workweave/router off --claude      # 关闭路由，直连原模型提供商
    npx @workweave/router on --claude       # 重新开启路由
    npx @workweave/router status --codex    # 查看当前路由状态

  • 卸载：移除配置，恢复工具原状。

    1
    npx @workweave/router --uninstall --claude

路径二：自托管模式（完全控制，数据本地化）

如果你对数据有严格的合规或安全要求，希望所有请求、密钥和路由逻辑都在自己的基础设施上运行，可以选择自托管。此模式会启动一个完整的技术栈，包括路由器服务、Postgres 数据库和一个可视化仪表板。

1. 环境准备与启动

  1. 克隆仓库：

    1
    2
    git clone https://github.com/workweave/router.git
    cd router

  2. 配置上游提供商密钥：
    你需要至少配置一个上游模型的API密钥。项目推荐使用OpenRouter作为基线，因为它可以接入多种模型。复制环境变量示例文件并填入你的密钥：

    1
    2
    3
    cp .env.example .env.local
    # 然后编辑 .env.local 文件，填入你的API密钥，例如：
    echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local

  3. 一键启动全栈服务：
    项目提供了一个 Makefile，可以使用一条命令启动所有服务（Postgres、路由器、迁移等）并生成一个路由器密钥（rk_...）。

    1
    make full-setup

    此命令会使用 Docker Compose 在后台启动整个技术栈。

2. 验证与使用

启动成功后，你会看到以下关键信息：

  • 路由器 API 端点: http://localhost:8080
  • 仪表板 (Dashboard): http://localhost:8080/ui/ (密码: admin)
  • 你的路由器密钥 (rk_...): 会打印在控制台日志中，这是后续客户端调用时需要使用的 Bearer Token。

调用示例：

你可以像调用 Anthropic 或 OpenAI 的 API 一样调用自托管的路由器，只需将请求指向 localhost:8080，并使用路由器密钥：

1
2
3
4
5
6
7
8
9
10
11
12
# 模拟 Anthropic Messages API 调用
curl -sS http://localhost:8080/v1/messages \
  -H "Authorization: Bearer rk_你的路由器密钥" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":256, "messages":[{"role":"user","content":"hi"}]}'

# 模拟 OpenAI Chat Completions API 调用
curl -sS http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer rk_你的路由器密钥" \
  -d '{"model":"gpt-4o-mini", "messages":[{"role":"user","content":"hi"}]}'

# 预览路由决策（不实际调用模型）
curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_你的路由器密钥" -d '...'

3. 连接你的工具到自托管路由器

当自托管服务运行后，你可以将你的 AI 编码工具指向它。

  • Claude Code / Codex / opencode：在安装命令后添加 --local 或 --base-url 参数即可。

    1
    2
    3
    4
    # 配置工具使用本地自托管路由器
    npx @workweave/router --claude --local
    # 或指定自定义的URL
    npx @workweave/router --codex --base-url http://localhost:8080

  • Cursor：Cursor 的集成目前是早期测试版。你需要手动在 Cursor 的设置 (Settings → Models) 中，将 Override OpenAI Base URL 覆盖为 http://localhost:8080/v1，并粘贴你的路由器密钥 rk_... 作为 API Key。

4. 可选：启用高级 HMM 策略

默认策略使用内置的集群评分器。你也可以启用一个更高级的 HMM (Hidden Markov Model) 策略[2, 4]。这需要添加一个 Google API Key 并启动一个额外的服务容器：

1
2
echo 'GOOGLE_API_KEY=你的Google_API_Key' >> .env.local
make up-hmm

启用后，你需要在路由器的配置中显式选择该策略。

重要注意事项

  • 许可证：请注意，该项目使用 Elastic License v2 (ELv2)，这不是一个宽松的 MIT/Apache 许可证。ELv2 允许你自由使用、修改和自托管，但禁止将其作为托管服务提供给第三方。
  • 数据与密钥：在托管模式下，虽然你的提供商密钥在本地加密，但请求内容会经过 Weave 的服务。对于数据敏感的用例，强烈建议使用自托管模式，确保所有数据不离开你的网络。
  • 路由效果：路由器的智能程度取决于你配置的模型池。为了达到最优的成本和性能平衡，建议配置多个来自不同提供商、性能和定价有梯度的模型（如 Claude Opus + DeepSeek + GLM）。