Weave Router

Weave Router 是一个面向智能体（Agent）系统的模型路由器。它的核心任务很简单：在 50 毫秒内，将每一个提示请求自动路由到最合适的模型。

对于开发者而言，这意味着你只需要更改一个端点，就能让应用自动选择最佳模型，从而将 API 成本降低 40-70%。它提供了一个统一的入口，背后连接着 Anthropic、OpenAI 和 Gemini 等主流提供商，甚至包括通过 OpenRouter 支持的 DeepSeek、Qwen、Llama 等开源模型。

核心工作原理：基于数据，而非“感觉”

许多路由工具依赖复杂的提示词工程来“猜测”哪个模型更好，而 Weave Router 采用了一种更硬核的技术路径。

它使用一个微小的本机嵌入器（Native Embedder）和一个源自 Avengers-Pro 的集群评分器。每次交互发生时，系统会根据请求内容的语义特征，从你启用的提供者中计算出最优模型。

这种机制带来了几个关键优势：

• 按请求实时路由：不是静态配置，而是动态决策。
• 全格式支持：兼容 Anthropic Messages、OpenAI Chat Completions 以及 Gemini 原生格式。
• 功能完整：支持流式传输、工具调用（Tools）、视觉理解等高级特性。
• 本地优先的安全设计：所有上游提供者的 API Key 都保留在你的机器上，并进行加密存储，不经过第三方服务器。

如何快速上手？

Weave Router 提供了两种主要的使用方式：托管版和自托管版。

1. 托管版：30 秒极速配置

这是最简单的入门方式，无需克隆代码、无需 Docker、也无需部署数据库。只需一条命令，即可将 Claude Code、Codex 或 opencode 指向托管版的 Weave Router。

确保你的环境已安装 Node ≥ 18，然后运行：

npx @workweave/router

安装程序会引导你完成以下操作：

• 选择要配置的工具（如 Claude Code）。
• 选择作用域（全局或特定项目）。
• 获取路由器密钥并写入配置文件。

如果你需要更精细的控制，可以使用以下标志：

• --claude：直接配置 Claude Code。
• --codex：配置 OpenAI Codex CLI。
• --scope project：为每个仓库单独配置，生成可提交的 settings.json。
• --local：切换到自托管模式，监听 localhost:8080。

2. 自托管版：完全掌控数据

如果你希望在自己的机器上运行路由器和监控仪表板，可以选择自托管。这种方式适合对数据隐私有极高要求或需要深度定制的场景。

首先，创建一个 .env.local 文件并填入你的上游提供者密钥（推荐使用 OpenRouter 作为基线）：

echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local

接着，启动整个堆栈（包含 Postgres 和路由器）：

make full-setup

启动后，路由器将在 http://localhost:8080 运行，仪表板位于 http://localhost:8080/ui/。日志中会打印出一个 rk_... 开头的路由器密钥，这是客户端访问路由器所需的凭证。

你可以像调用原生 API 一样测试它：

# 模拟 Anthropic 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"}]}'

接入主流开发工具

Weave Router 已经针对常见的 AI 编码助手进行了适配，接入过程非常平滑。

• Claude Code：运行 make install-cc 即可接入本地自托管路由器。如果是托管版，直接使用上述 npx 命令即可。
• Codex：运行 npx @workweave/router --codex，它会自动修补 ~/.codex/config.toml，添加受管理的 [model_providers.weave] 块。
• opencode：运行 npx @workweave/router --opencode，会将配置合并到 ~/.config/opencode/opencode.json 中。
• Cursor：在设置中将 OpenAI Base URL 覆盖为 http://localhost:8080/v1，并将 rk_... 密钥粘贴为 API Key。

为了方便管理，它还提供了开关命令：

• npx @workweave/router off --claude：临时关闭路由，直接回源到原始提供商。
• npx @workweave/router on：重新启用路由。
• npx @workweave/router status：查看当前状态。

可观测性与调试

对于生产环境或调试场景，透明度至关重要。Weave Router 开箱即用地支持 OTLP 跟踪。

你可以在 Weave 自带的仪表板中查看路由决策过程，也可以将其接入 Honeycomb、Datadog 或 Grafana 等专业监控平台。此外，通过 /v1/route 端点，你可以仅获取路由决策结果而不实际转发请求，这对于测试和优化路由策略非常有用。

注意事项：两种密钥的区别

在使用过程中，请务必区分两种不同的密钥，以免混淆：

1. 上游提供者密钥（如 sk-or-..., sk-ant-...）：这是你从 Anthropic、OpenAI 或 OpenRouter 获取的原始 Key。它们应存放在 .env.local 中，由路由器后端使用。
2. 路由器密钥（rk_...）：这是 Weave Router 生成的本地凭证。你的客户端（如 Claude Code）需要将此密钥作为 Bearer Token 发送给路由器，以证明访问权限。