Llm Router

llm-router

别再把 Claude Pro/Max 配额浪费在免费模型就能回答的问题上。

llm-router 会接入你的编码工具自身的生命周期，在模型读取每条提示词之前读取它，并先使用免费或本地模型起草答案。Claude 订阅无需 API 密钥——路由通过 MCP 工具和本地模型运行。

_{有一点需要注意：默认情况下，路由生成的答案仅供参考——除非你选择启用零 Claude 模式，否则仍由 Claude 完成这一轮。默认情况下，某些工具调用会等待提示词完成路由；LLM_ROUTER_ENFORCE=off 可关闭此设置（所有用户设置请见：docs/configuration.md）。起草率和采纳率数据请见 docs/MEASUREMENT.md，其中包含样本量、时间窗口和条件。}

📑 目录

• 为什么要安装
• 快速开始
• 兼容工具
• 工作原理
• 功能
• 参考
• 节省情况
• 信任与安全
• 文档
• 企业版、贡献与许可证

---

为什么要安装

你使用 Claude Pro 或 Max 套餐，没有额外花一分钱，却仍然触及了五小时限额——并不是因为提问太多，而是因为每条提示词都发给了高级模型：“这个错误是什么意思”“重新格式化这段 JSON”“服务是否正常”消耗的配额，和真正需要高级模型回答的问题一样多。

为什么代理无法做到

这里的大多数路由器都是代理：你的 Agent 使用你的 API 密钥转发请求。这有个硬性限制——代理无法拦截通过订阅进行身份验证的会话，因为没有密钥可供转发。

	按 Token 付费	订阅付费
用尽的是什么	账单	五小时额度窗口
需要 API 密钥	是	否
代理能帮上忙吗	能	不能——没有可拦截的内容
llm-router 能帮上忙吗	能	能

诚实也是一项功能

llm-router status 会分别报告已验证和未验证的节省金额， 各自带有独立的 n 值，而不是混合后的百分比。本项目 不会公布通用的节省百分比；具体数值取决于你自己的工作负载。请参阅下文的 节省情况。

---

快速开始

pip install llm-routing        # installs the `llm-router` command
llm-router install             # wire up Claude Code (default host)
llm-router doctor               # check provider connectivity and setup
llm-router status               # verify it's routing — est. savings vs baseline

使用 Claude Pro/Max 订阅即可无需 API 密钥：路由通过 MCP 工具和本地模型完成。添加服务提供商密钥可扩大可用范围； 但并非必需。请参阅 guide/PROVIDERS.md。要安装到其他宿主，请参阅兼容宿主。每日 KPI 任务仅在获得同意后安装（运行 install --schedule-daily，或在询问时输入 Y；--no-schedule 可跳过）；uninstall 会将其移除。

Python Agent 可在进程内进行路由，无需服务端：from llm_router import Router; r = Router(budget_usd=0.50).run("...")（异步代码中使用 await .arun(...)；达到上限时会触发 BudgetExceeded）。

---

兼容宿主

宿主	安装
Claude Code（默认）	llm-router install
Codex CLI	llm-router install --host codex
OpenCode	llm-router install --host opencode
Gemini CLI	llm-router install --host gemini-cli
GitHub Copilot CLI	llm-router install --host copilot-cli
OpenClaw	llm-router install --host openclaw
Trae IDE	llm-router install --host trae
Pi (pi.dev)	计划支持（v16 P2.12）；--host pi 会说明原因并以状态码 2 退出
Factory Droid	llm-router install --host factory
Claude Desktop	llm-router install --host desktop
VS Code（原生 MCP）	llm-router install --host vscode
Cursor	llm-router install --host cursor
VS Code 中的 GitHub Copilot（功能扩展，不支持成本路由）	llm-router install --host copilot
Windsurf / Cascade	llm-router install --host windsurf
Kimi Code (Moonshot AI)	计划支持（v16 P2.12）；--host kimi 会说明原因并以状态码 2 退出

llm-router install --host all 会一次性安装或打印所有宿主的配置。各宿主的完整详情，包括每个宿主确实无法实现的功能： guide/HOST_SUPPORT_MATRIX.md。

---

工作原理

钩子会在提示词被你的编码工具自己的模型看到之前将其拦截。免费的 正则启发式方法可即时分类，并能以一定置信度为约一半的实际提示词评分——在 1,571 条已测量提示词中有 788 条（scripts/measure_low_signal_rate.py， 于 2026-09-23 运行）；其余提示词会回退到默认值。对于可路由的提示词，系统会先使用免费/本地模型生成 草稿，只有在必要时才逐步切换到付费 模型。

这份草稿仅供参考——它会作为未经验证的提示交给 Claude，而不是替换一次轮次， 除非你选择启用零 Claude 模式。强制执行发生在工具调用层面：smart（默认）会暂缓所选工具调用，直到提示词完成路由；off 则会关闭此功能。完整模式及各宿主的覆盖设置： guide/GETTING_STARTED.md。

---

功能

• 包含密钥的提示词只会发送给本地模型，否则就不会发送。 路由调用（llm_* 文本工具、网关、流式传输）中包含 API 密钥、令牌或私钥时，llm-router 只会将其发送给回环守护进程上的 Ollama 模型——直接发送，不经过 HTTP 代理，也不使用语义缓存、裁判队列或云端回退——否则会拒绝请求，并说明密钥类别及后续处理方式（使用 cloud: 前缀可覆盖单次请求）。AKIA...EXAMPLE 或 postgres:postgres@ 之类的占位符不会被拒绝。不涵盖：Claude Code 代理和钩子（仅记录日志）、Agent 委派，以及主机已发送给其自有模型的内容。详情和限制。
• 自动回退和断路器。 发生故障或触发速率限制的提供商会被跳过，不会反复重试。
• 运行状态一目了然。 状态行、终端标题和操作系统通知会显示最近路由的模型、节省金额和健康状况。
• 会话结束摘要。 包括相对于基准的节省金额、层级分布、各提供商成本、延迟 p50/p95/p99 和热门路由。
• 也支持媒体和流水线。 llm_image / llm_video / llm_audio，以及用于多步骤研究的 llm_orchestrate。

---

参考

默认的 MCP 接口显示 12 个前端工具；选择退出后会显示所有已注册工具 （用户设置请参阅 docs/configuration.md）。

主题	内容	指南
CLI	install、status、gain、doctor、okf index/status、sessions status 等	guide/GETTING_STARTED.md
提供商	免费优先——Ollama（本地）、OpenRouter、Gemini、Groq、你的 Claude 订阅	guide/PROVIDERS.md
路由策略	conservative → balanced（默认）→ cost_aggressive；阈值和 YAML 架构	guide/POLICIES.md
MCP 工具	每个工具及其签名	guide/TOOLS.md

llm-router gain today           # savings so far today
llm-router okf status           # knowledge base freshness
llm-router sessions status      # per-session summary

---

节省金额

节省金额是一个反事实指标——同样的令牌按 API 标价计算的成本，与实际支出之间的差额——并非固定订阅费用所节省的钱。llm-router status 和 llm-router savings-report 会分别列出已验证和未验证的节省金额，并各自标明样本数 n。方法、假设和局限：docs/MEASUREMENT.md。

---

信任与安全

llm-router 完全在你的机器上运行——没有托管代理，不会向 llm-router 服务发送任何内容，也无需账户。依据核验（src/llm_router/grounding.py）会丢弃引用了其上下文和索引仓库中不存在的文件或函数的草稿，并回退到 Claude。

LLM_ROUTER_DIRECT_EXECUTION 默认开启——本地模型可在受限的允许路径下使用 write_file、edit_file 和 run_command，但这无法阻止针对性删除、git push --force 或数据外泄。静态拦截机制会拒绝将内容写到项目根目录之外的 Shell 重定向和复制操作，但它不是沙箱；OS 沙箱将在 16.1 中推出。对于拦截机制无法判断的命令（解释器单行命令、sudo、$(...)），会返回 needs_approval，但目前尚未接入审批流程，因此两种命令路径都会将其视为拒绝并且不会执行。使用 LLM_ROUTER_DIRECT_EXECUTION=false 可将其关闭。完整分析： SECURITY.md。

自审结果发布在 audit/ 和 docs/repo_goals/AUDIT-2026-09-25.md （13 项达成、6 项部分达成、1 项未达成），包括负面结果。

Ground Truth 累积（可选择启用）会构建可重放路由决策的语料库，而不是彼此无关的遥测数据；默认关闭，因为这是唯一会将提示词文本写入磁盘的部分。详情： guide/GROUND_TRUTH.md。

文档

完整索引：guide/README.md

文档	用途
快速开始（2 分钟）	以最快方式实现可用的路由
入门指南	完整的设置指南
主机支持矩阵	各主机的功能对比
提供方	提供方设置和模型推荐
路由策略	routing.yaml 架构及如何编写自己的策略
工具参考	所有 MCP 工具及示例
架构	内部设计和模块结构
故障排除	常见问题及解决方法
测试路由器	用于验证路由健康状况的隔离套件
测量	“节省”的含义及计算方式
RouterArena	基准测试方法、结果和负面发现
真实数据	可重放的路由语料库，可选择启用
基准测试	模型成本／延迟／质量表，由 CI 重新生成
更新日志	发布说明（存档）

llm-router 在 RouterArena 基准测试中进行评分——完整数据集包含 8,400 个查询，使用本仓库的测试框架在本地评分， 尚未经过独立验证。当前 Arena 得分：72.35。完整方法及负面结果（包括一个 导致调优结果偏差 4.25 分的代理数据集）：docs/ROUTERARENA.md。

---

企业版、贡献与许可证

llm-router 面向个人开发者和小型团队打造：节省本地成本、无需运维开销、不托管任何服务。对于团队级策略 执行、审计导出、SSO 或组织级预算，请参阅 Chuzom——一款独立的姊妹产品。

欢迎贡献——请参阅 CONTRIBUTING.md。

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (10,000+)
uv run ruff check src/ tests/   # Lint

MIT 许可证。问题 · 讨论 · PyPI · 更新日志