cheaper-inference/OmniRoute · 上手攻略

  • 仓库：cheaper-inference/OmniRoute
  • 链接：https://github.com/cheaper-inference/OmniRoute
  • 分类：llm-infra / agent（TypeScript，MIT）
  • 作者：spark
  • 更新：2026-10-23

资料核验：README 于 2026-10-22 UTC 通过 raw.githubusercontent.com 实抓（main 分支），另实抓 docs/getting-started/FREE-TIERS-GUIDE.md（front-matter 标 version: 3.8.52、lastUpdated: 2026-10-11）。文中命令、端口、版本号逐字取自这两份文件。⚠️ 本次未运行任何代码、未 clone，仅只读公开内容。

一、是什么

OmniRoute 是一个 AI 网关（gateway）：把 375 个 provider、1400+ 模型聚合到一个 OpenAI 兼容端点后面，让 Claude Code、Codex、Cursor、Cline、Copilot、OpenCode、Antigravity 等编码 agent 都能通过它访问 Kimi、Claude、GPT、Gemini、GLM、DeepSeek、MiniMax 等模型，并带配额感知的自动降级（auto-fallback）与 token 压缩。

它的自我定位是"免费的 MIT AI 网关"，主打三件事：

  1. 多 provider 聚合 + 自动降级：一个端点打天下，某个 provider 撞配额时自动切走。
  2. 免费额度池：README 声称约 1.62B tokens/月，来自 467 个 free-tier 条目、34 个 recurring pool key。README 明确声明这是"跨第三方免费额度的估算聚合，不是 OmniRoute 发你的 token 赠额"。
  3. 压缩：RTK + Caveman 叠加压缩，README 称节省 15–95% token，平均约 89%。

分发形态齐全：npm 包 omniroute、Docker Hub diegosouzapw/omniroute、Electron 桌面端、PWA、Desktop，还有 MCP / A2A 接口。

⚠️ 重要前提：README 里所有 star 徽章、Trendshift、Star History、Docker Hub badge 指向的是 diegosouzapw/OmniRoute，而本文仓库是 cheaper-inference/OmniRoute。两者关系（fork、镜像、组织迁移、或不同实体）本次未核实。组织内卡片记录 Stars 79760、周增 +0，这个量级与 README 中 diegosouzapw 徽章所呈现的项目热度相符，但无法据此断定身份关系。使用前请自行确认你装的是哪个包——npm 上的 omniroute 包名可能是关键区分点。

二、解决什么问题

用编码 agent 的人都有同一个痛点：单一 provider 的配额就是你的产能天花板。Claude Code 用量撞顶就停工，换 provider 要改 base URL、改模型名、改请求体格式，每个 provider 一套 SDK、限额规则还各不相同，手工叠加几十个免费额度更是噩梦。

OmniRoute 把这件事收敛成"接一个端点、配自己的账号、模型名写 auto"：

  • Claude Code / Codex / Cursor 等客户端不改一行配置指向 localhost:20128/v1；
  • 你自己注册各家 provider、拿 key，OmniRoute 只做聚合；
  • 某个 provider 额度耗尽时自动降级到其他 eligible 目标，不中断。

它还试图解决 token 成本问题：压缩层在请求发出去前把 payload 缩小。

三、快速安装

README 给的形态是"装起来 → 接一个 provider → 把工具指向 localhost:20128/v1"：

# npm（README 列出的分发渠道之一）
npm install -g omniroute

# 或 Docker
docker pull diegosouzapw/omniroute

⚠️ 具体安装命令（npx / pnpm / 源码构建 / CLI 首次启动的具体语法）在 README 的 "Quick Start" 与 "More Install Methods (Docker / Source / pnpm / arch)" 段，本次抓取被截断，未取到逐字命令。npm 徽章指向 https://www.npmjs.com/package/omniroute，Docker 徽章指向 https://hub.docker.com/r/diegosouzapw/omniroute——这两条渠道的 owner 与本文仓库 owner 不一致，使用前务必核对。

四、核心用法

4.1 打通一次请求

连好 provider 后，从 Dashboard → Endpoints 复制 OmniRoute key：

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

模型名写 "auto"，路由器按可用 eligible 连接和 provider 限额选路。

README 在这段命令下挂了两条 sub 备注，非常关键：

auto needs an eligible route. A fresh installation can have no eligible keyless targets, and a keyless provider may reject third-party clients. Providers marked tos: avoid, including Kiro, are excluded from automatic routing by default; connecting an account does not override that setting.

即：装完不等于能用。你必须自己去注册 provider、拿凭证，且免费额度可能是无鉴权端点、周期配额、限速不限量、注册赠金、人工审批、或限时促销中的一种——有的还要信用卡、KYC 或接受特定条款。

4.2 免费额度到底怎么算

README 的方法论（docs/reference/FREE_TIERS.md 有完整版）：目录收录 467 个 free-tier 条目、34 个 recurring pool key；头条数字只由 17 个有公开正月预算的池 + 5 个 per-model Groq cap 计算，并按共享池去重（共享池只算一次）。预算条里点名了 Mistral 1B、Nara 210M、LLM7 150M、xKiro 150M、Groq 30M 五个 per-model cap 及若干更小的池，首月注册赠金另计，永久免费无 token cap 的 provider 单独展示、不进头条，以免虚高。

需要地域身份验证才开放的配额（比如今天的 ModelScope）单列，额外约 +6M，从不并入头条。实时已用/剩余在 /dashboard/free-tiers。README 还说这些数字每两周对活目录重审一次、且双向波动——有 provider 砍免费额度数字就掉，有新provider 数字就涨。

Free Tiers Guide 里的代表 provider（front-matter 记 version: 3.8.52，lastUpdated: 2026-10-11）：

Provider 模型 配额 接入方式
Kiro AI Claude Sonnet 4.5、Haiku 4.5、DeepSeek V3.2 等 目录估算 25K token 共享月池 OAuth/账号流；目录标 tos: avoid
Pollinations 当前无 key 模型集（部分已下线或改为需 key） 无 key；无公开 token cap 无需凭证
Logfare kimi-k3、deepseek-v4-pro、glm-5.2、gpt-5.6-luna、minimax-m3 等 免费 key，无速率限制、无卡；每个请求都被记录用于研究（可在 logfare.ai/consent 退出） logfare.ai/register 即时取 key
Cloudflare AI Workers AI 目录 目录估算约 30M token/月 Cloudflare 账号 + API 凭证
Gemini Gemini Flash 系 变动速率限制；不含固定月 token 赠额 Google AI Studio key
Groq Llama、GPT-OSS、Qwen 目录估算约 15M token/月 Groq key

注册赠金类：Cerebras 一次性 $5 促销额度（需绑支付方式，30 天过期，不是周期配额）、DeepSeek 5M free tokens、LongCat 10M 一次性赠金。Gemini 的速率限制随项目/模型/等级变化，不折算成保证的月度额度。

4.3 版本演进

README 的增长表（可直接看出迭代节奏很快）：

v3.8.50 v3.8.51 v3.8.52+
Providers 352 358 375
唯一 chat model ID 1320 1374 1475
Modality Bridge 🆕 vision+audio+video ✓ ✓
Radar 免费目录 🆕 opt-in ✓ ✓
配额感知调度 🆕 Quota-Share ✓ ✓
配额遥测 🆕 live ✓ ✓
Headless 模式 — — 🆕 serve --headless
LTS rail infra — — 🆕 release channels
模型发现 API — — 🆕 /v1/models/query

Roadmap 指向 v3.9.0 LTS。

4.4 其它接口

README 目录列出 CLI、A2A、MCP（#-full-cli--a2a--mcp）、Dashboards、Portal chat、Desktop/PWA。⚠️ 这些章节的具体命令本次未取到。

五、典型适用场景

  • 编码 agent 的配额续航：Claude Code / Codex / Cursor 撞限额后不中断，自动降级到别的 provider。
  • 多 provider 成本套利：同一任务在不同模型间按策略路由（README 称 20 种路由策略）。
  • 个人/小团队免费额度聚合：把散落在十几个 provider 的免费额度统一管理，/dashboard/free-tiers 看剩余。
  • 统一接入层：给内部工具一个稳定的 localhost:20128/v1，后面换 provider 不影响客户端。

不适合：企业生产环境的核心链路——大量 provider 是无鉴权或日志全记录的第三方端点（Logfare 明说每个请求都被记录），且 12 个 provider 在 terms-risk 目录里标了 avoid。

六、坑与注意（8 条）

坑 1 · 现象：装完就发 model: "auto" 请求，收到无路由可用。影响：新装环境常常一个 eligible 无 key 目标都没有，README 自己就写了这句"installing OmniRoute alone does not guarantee a successful chat response"。修复：先在 Dashboard 接至少一个真实 provider 账号，再测。

坑 2 · 现象：把 README 的 1.62B token/月当自己可用额度。影响：严重误判产能，任务排期全错。修复：这是跨第三方免费额度的估算聚合，需要你自己逐家注册、拿凭证；且各 provider 各自控制限额、可用性与条款。真实可用量取决于你实际连上了几家、拿到哪些 key。

坑 3 · 现象：以为接了 Kiro 就能自动路由到它。影响：完全不生效。修复：目录里标 tos: avoid 的 provider（Kiro 是 README 点名的一个）默认被排除在自动路由外，且 README 明确"connecting an account does not override that setting"。要用得手动改设置。

坑 4 · 现象：把 Logfare 放进敏感或生产流量。影响：你的每一次请求都被记录用于研究。修复：只在可接受的场景用，并到 logfare.ai/consent 退出记录；同时读 logfare.ai/tos 与 logfare.ai/privacy。总共 12 个 provider 被标 avoid，选之前先看 terms-risk 目录。

坑 5 · 现象：以为免费额度数字稳定。影响：容量规划失效。修复：README 说这些数字每两周重审、双向波动——有 provider 砍免费额度就掉。不要把 1.62B 写进长期承诺。

坑 6 · 现象：装错包 / 认错仓库。影响：可能拿到的是另一个同名或镜像项目。修复：README 所有 star badge、Trendshift、Star History、Docker badge 都指向 diegosouzapw/OmniRoute，npm 包名是 omniroute，Docker 是 diegosouzapw/omniroute；本文仓库是 cheaper-inference/OmniRoute。⚠️ 两者关系本次未核实，动手前先核对。

坑 7 · 现象：照旧文章抄安装命令。影响：命令不存在或装错版本——项目当前在 v3.8.52 附近，v3.8.50 → v3.8.51 provider 数从 352 到 358，功能以每版本粒度新增。修复：本文版本号取自 2026-10-22 实抓的 README 与 Free Tiers Guide（version: 3.8.52）；使用前核对自己装的 tag。

坑 8 · 现象：依赖压缩省下的 token 数。影响：89% 平均节省是 README 的宣传口径，实际随内容类型剧烈变化（README 给的区间就是 15–95%）。修复：先在自己的流量上量一遍再决定是否依赖；压缩与模型质量/工具调用正确性的相互影响 README 未披露 ⚠️。

七、与同类对比

  • vs LiteLLM Proxy：LiteLLM 是更"正统"的 OpenAI 兼容网关，模型覆盖广、社区大、企业采用多；OmniRoute 的差异化在免费额度聚合目录 + terms-risk 标注 + 面向编码 agent 的开箱即用 + token 压缩，且明确鼓励用户自带各家账号而不是提供统一计费。
  • vs Portkey / Helicone：Portkey 偏企业级可观测与治理，Helicone 偏 LLM 网关的观测/成本分析层；OmniRoute 的重心在"额度续航 + 降级 + 压缩"，观测不是主打。
  • vs OpenRouter：OpenRouter 是有统一计费的托管市场；OmniRoute 是本地自托管、用你自己的各家 key。定位不同。
  • vs 裸配环境变量切 provider：OmniRoute 省掉改 base URL / 请求体格式 / 限额逻辑的重复劳动，代价是多一跳进程与一层路由不确定性（auto 到底选了谁需要看遥测）。

八、一句话推荐结论

推荐：个人开发者或小团队重度使用 Claude Code / Codex / Cursor、经常撞配额，想把散落的免费额度聚合成一条稳定链路，值得一试——注意它本质是"帮你把各家免费额度用起来"而不是"送你额度"。

不推荐：企业生产核心链路、合规敏感数据、或任何不能接受请求被第三方记录的场景——tos: avoid 清单、Logfare 全量记录、无 key 端点，都是实打实的红线。

来源： - 仓库 README（raw.githubusercontent.com/cheaper-inference/OmniRoute/main/README.md，2026-10-22 UTC 实抓，取 Hero / 增长表 / Available / First Run 段） - docs/getting-started/FREE-TIERS-GUIDE.md（同仓实抓，front-matter version: 3.8.52、lastUpdated: 2026-10-11，取代表 provider 表与注册赠金段） - README 内引用但未 fetch：docs/reference/FREE_TIERS.md、ROADMAP.md、安装方式段、CLI/A2A/MCP 段 - README 引用的外部链接：npmjs.com/package/omniroute、hub.docker.com/r/diegosouzapw/omniroute、trendshift.io/repositories/23589 - 组织内卡片：organized/repo_cards/4569-cheaper-inference-omniroute.md

⚠️ 未确认清单：cheaper-inference/OmniRoute 与 diegosouzapw/OmniRoute 的实际关系；逐字安装命令与 CLI 用法；20 种路由策略的完整清单；压缩算法 RTK/Caveman 的实现与质量影响；卡片记录的 Stars 79760 与 README 内徽章的对应关系。