Workweave Router 实战教程：给 AI 编码 Agent 装上智能模型路由，每次调用都省 40-70%

用 Claude Code、Codex 或 Cursor 写代码时，你有没有注意过每个月花在 API 上的账单？

Claude Sonnet 4.5 能力强但贵（$15/M 输入 token），DeepSeek V3 便宜但什么时候该用它？GPT-4o-mini 快但遇到复杂推理就掉链子。大多数开发者要么全用最强模型（钱包流泪），要么手动切模型（精力浪费）。

Workweave Router 是一个开箱即用的智能模型路由代理——你把它插在 AI 编码 Agent 和模型提供商之间，每次请求自动选最合适的模型。根据官方数据，平均降低成本 40-70%，每次路由决策仅需 <50ms。

它由 Workweave（工程智能平台，客户含 Robinhood、PostHog）开发，发布在 GitHub（754⭐），使用 ELv2 源可用许可证。

30 秒快速接入

最简单的方式：一行命令将 Claude Code 或 Codex 指向 Workweave Router 的托管服务。

npx @workweave/router

安装脚本会询问你使用哪个工具（Claude Code / Codex / opencode）、设置作用域（用户级或项目级），然后自动生成配置文件。整个过程不到 30 秒。

如果你想指定工具类型，也可以：

npx @workweave/router --claude

npx @workweave/router --codex

npx @workweave/router --opencode

npx @workweave/router --scope project

自托管部署

如果你的代码有隐私要求，或者想完全掌控路由策略，可以通过 Docker 自托管：

echo "OPENROUTER_API_KEY=$(API_KEY)" >> .env.local

make full-setup

启动后，Router 监听 localhost:8080，Dashboard 也同端口可用（密码：admin）。

架构原理：为什么它真的有效

Workweave Router 的路由策略基于 Avengers-Pro（arXiv:2508.12631）的聚类评分算法，但做了一些实用化改造。

核心思路很简单：不是所有请求都需要最强模型。 一个 Git log 查询可能只需要 GPT-4o-mini，而一个复杂的架构重构才需要 Claude Sonnet。Router 在每个请求到达时，基于请求内容（prompt 的前几百个 token）和当前模型集群的实时状态，计算出一个「性价比分数」，自动选择最优模型。

它的评估向量不是靠 “vibe” 或简单关键词匹配，而是一个本机嵌入模型（on-box embedder） 在本地计算请求特征，不发送你的数据到第三方。密钥也留在本地（BYOK），AES 加密存储。

支持的模型提供商包括：

实际使用场景

场景 1：Claude Code 日常编程

配置完成后，Claude Code 的所有请求都会自动经过 Router：

claude

Router 还会为 Claude Code 添加三个 slash 命令：

• /router-off — 临时切回直连（调试 Router 问题时）
• /router-on — 重新启用路由
• /router-status — 查看当前路由状态

场景 2：多 Agent 共享路由器

如果你同时跑 Claude Code、Codex 和 opencode，可以让它们共用同一个 Router 实例：

npx @workweave/router --claude
npx @workweave/router --codex
npx @workweave/router --opencode

Router 会自动管理三个工具的模型选择策略，避免它们同时用最贵模型打爆预算。

场景 3：API 兼容与可观测性

Router 支持三种 API 格式：Anthropic Messages、OpenAI Chat Completions 和 Gemini native。三者在同一个端口上共存：

curl -sS http://localhost:8080/v1/messages \
  -H "Authorization: Bearer $(ROUTER_KEY)" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":256,
       "messages":[{"role":"user","content":"hi"}]}'

curl -sS http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $(ROUTER_KEY)" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini",
       "messages":[{"role":"user","content":"hi"}]}'

Router 原生支持 OTLP（OpenTelemetry Protocol） 追踪，所有路由决策和延迟数据可以通过本地 Dashboard（http://localhost:8080/ui/dashboard）实时查看，也可以导出到 Honeycomb、Datadog、Grafana 等平台。

效果评估

根据 Workweave Router 的测试数据（基于 10 万次调用）：

• 成本降低：40-70%，具体取决于你的模型组合
• 路由延迟：<50ms（远低于一次模型调用的时间）
• 质量保持：通过聚类评分确保复杂任务不降级到弱模型

小结

Workweave Router 解决的是一个非常实际的痛点：AI 编码 Agent 的模型选择困境。 它不是靠”智能猜测”工作，而是基于真实请求内容的聚类评分来做路由决策。30 秒的安装体验、支持主流 AI 编程工具、自带可观测性，这些特性使它成为团队使用 AI 编程 Agent 时的实用基础设施。

如果你想用，可以先从 npx @workweave/router --claude 开始体验——不满意随时可以 npx @workweave/router off --claude 切回去。

相关链接：

• GitHub 仓库
• Workweave 官网
• 配置文件参考
• Avengers-Pro 论文