OmniRoute 快速入门

OmniRoute 快速入门

OmniRoute（omniroute.online）是一个 MIT 协议的开源 AI 网关：把 359 家 provider（其中 150+ 提供免费额度）、1200+ 模型聚合到一个 OpenAI 兼容端点后面，带配额感知的自动降级（auto-fallback）与限流路由，RTK+Caveman 压缩宣称节省 15-95% token。它的口号是「Never stop coding」——主键场景是让 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 这类编码工具在单一 provider 掉线或限流时自动切到下一条路由。2026-10-08 核验：官网与 GitHub 仓库均可访问，GitHub ★73.9k，最近一次 push 在 2026-10-07。

这是什么？适合谁？

用 Claude Code 或 Cursor 写代码的人迟早撞上三件事：官方 API 限流、某个 provider 临时掉线、免费额度分散在十几家（Gemini 免费档、各家新用户赠金）用不起来。常见解法是 LiteLLM 这类代理，但 LiteLLM 的配置偏运维向，编码工具生态的适配要自己写。OmniRoute 的定位就是补这一层：一个自托管的开源网关，上游接 359 家 provider，下游只暴露一个 OpenAI 兼容端点；任意支持「自定义 OpenAI base URL」的工具（官方列表 25+，含 Claude Code、Codex CLI、Cursor、OpenCode、Cline、Copilot、Roo Code、Kilo、Aider 等）改一行配置就能接入。

它由 Cheaper Inference 团队维护（官网标注 OmniRoute has joined Cheaper Inference），云服务与自托管开源版并存；自托管完全免费且 MIT 协议，无功能锁。

适合人群：

• 同时用多家模型/免费额度的独立开发者：把分散的额度收进一个端点
• 被限流/掉线打断工作的编码工具用户：自动 fallback 让会话不断线
• 想压缩 token 成本的团队：RTK+Caveman 压缩宣称省 15-95%（效果因内容而异，未实测）

不适合谁：只需要单一官方 API 的轻用户（直接用官方端点更简单）；需要企业级 SLA、审计合规的团队（自托管版需自担运维，云服务另行评估）。

准备工作

• 账号：自托管不需要任何账号——克隆仓库即可跑；用配套云服务（Cheaper Inference）才需要注册（新用户 $10 赠金，官网自述）
• 预算：软件本身 $0（MIT 开源）；模型调用费取决于你接的上游 provider
• 时间预算：自托管首次部署约 30 分钟（Docker 或本地 Node 均可）；把编码工具切到网关端点约 5 分钟/工具
• 前置知识：会改环境变量（如 ANTHROPIC_BASE_URL / OPENAI_BASE_URL）；大致了解自己有哪些 provider 的 API key
• 替代方案：LiteLLM（更偏通用 LLM 网关、配置面更宽但编码工具生态适配弱）；OneAPI/new-api（国内生态的渠道聚合面板）；直连官方 API（单一 provider 够用时最简单）

快速上手

第一步：拿到并启动 OmniRoute

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
# 按 README 选择 Docker 或本地启动；启动后网关默认监听本机端口

预期产出：网关进程在本机跑起来，日志显示监听地址（形如 http://127.0.0.1:8787/v1 的 OpenAI 兼容端点）。以仓库 README 的实际启动命令为准（2026-10-08 仓库活跃，文档可能与版本同步变化）。

成功判定：curl http://127.0.0.1:8787/v1/models（换成你的实际端口）返回模型列表 JSON。

第二步：配置 provider 密钥

在 OmniRoute 的配置界面/文件里填入你手上的各家 API key（OpenAI、Anthropic、Gemini、DeepSeek、GLM、Kimi、MiniMax 等都支持）。免费额度来源（如 Gemini 免费档）按仓库文档的 provider 清单逐个添加。

预期产出：配置里出现多条 provider，每条带各自的 key 与免费额度信息；OmniRoute 的配额感知会自动记录各 provider 的剩余额度与限流状态。

第三步：把编码工具指到网关

以 Claude Code 为例（其它工具同理，改各自的 base URL 设置）：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8787/"
export ANTHROPIC_API_KEY="omniroute 分配的本地 key"
claude

第一个可完成任务：在 Claude Code 里让它写一个 50 行以内的脚本并运行。如果模型正常回复，说明端到端已通。此时把某一家 provider 的 key 故意改错再试——OmniRoute 应自动 fallback 到下一条可用路由，会话不中断（这是它最核心的卖点，值得当场验证一次）。

常见踩坑

坑 1：以为「359 家 provider」都是免费 现象：配置完发现还是要付费。原因：359 家是「支持的上游总数」，其中 150+ 有免费额度来源，其余照常计费。解决：只添加你确认有免费额度的 provider；成本以各上游账单为准。

坑 2：压缩比例当承诺 现象：期望一律省 95% token，实测只省了 20%。原因：RTK+Caveman 压缩对不同内容（代码 vs 自然语言 vs 重复上下文）效果差异大，15-95% 是区间不是承诺，本站未实测。解决：拿自己的真实会话做前后对比，再决定是否长期开启。

坑 3：本地网关端口与工具配置不一致 现象：编码工具报 connection refused。原因：base URL 写错端口或漏了 /v1 路径（不同工具期望的路径后缀不同）。解决：先用 curl 验证端点返回模型列表，再按工具文档逐字填写。

坑 4：fallback 生效但模型行为变了 现象：掉线后自动切到另一家模型，风格/能力突变。原因：fallback 按可用性与配额路由，默认不保证同一模型。解决：在路由策略里把「同模型优先」或指定 fallback 链配好，别裸用默认策略跑严肃任务。

坑 5：Claude Code 等工具的环境变量不生效 现象：工具仍在打官方 API。原因：环境变量没进到工具的启动 shell（Windows 下尤常见，或被 .env 覆盖）。解决：在工具内 /status 类命令里核对实际 endpoint；用绝对配置文件而非临时 export。

坑 6：忘记自托管版的运维成本 现象：网关进程挂了所有工具一起断。原因：自托管意味着你是单点。解决：用 systemd/Docker restart 策略做保活；接受不了就评估托管云服务。

权限 / 安全 / 成本 / 平台限制

• 安全：自托管版所有 API key 留在你本机；把它暴露到公网前务必加鉴权（网关自带本地 key 机制，以文档为准）
• 成本：软件免费；上游模型费照付。压缩与 fallback 不会凭空降费，只是把「哪个 provider 出钱」重新分配
• 平台：桌面端/PWA 与各平台 CLI 均支持；服务器端 Linux/macOS/Windows 均可自托管
• 协议：MIT——可商用、可修改、须保留版权声明

FAQ

Q1: OmniRoute 和 LiteLLM 怎么选？

A: LiteLLM 是更早、更通用的 LLM 代理（Python 生态、provider 覆盖广）；OmniRoute 主打编码工具场景的深度适配（Claude Code/Cursor/Cline 等开箱即用）与免费额度聚合。重度编码工具用户选 OmniRoute 更省事；做通用 API 中台选 LiteLLM。

Q2: 免费额度真的能白嫖 1200+ 模型吗？

A: 150+ provider 提供某种免费额度（官方自述），但额度大小、限速、有效期各不相同，且会随时调整。把它当「试用与兜底」，别当生产依赖。

Q3: 已被 Cheaper Inference 收购，开源版会阉割吗？

A: 截至采集日（2026-10-08）仓库仍是 MIT、活跃 push（10-07 仍有提交）、官网仍提供 self-host 入口。商业化后开源版走向无法保证，关注仓库动态即可。

Q4: 支持非编码场景吗（如自建聊天应用）？

A: 支持——端点是 OpenAI 兼容的，任何 OpenAI SDK 客户端都能接。只是它的路由策略与压缩特性是围绕编码工作流调优的。

Q5: 和 OneAPI/new-api 比？

A: Oneapi/new-api 是渠道聚合面板，强在渠道管理与国内生态；OmniRoute 强在编码工具适配、配额感知 fallback 与 token 压缩。按你的主要工具链选。

进阶玩法

• fallback 链定制：把「便宜但慢」的 provider 排在兜底位，「贵但稳」排在首位，按任务重要性切换两条链
• 配额看板：用网关的配额感知数据观察各家免费额度的真实消耗率，动态调整路由权重
• 配合 Claude Code 的模型切换：网关层换模型不换工具配置，比在工具里来回改设置快
• 团队共享网关：一台服务器自托管 + 团队成员统一指向，key 集中管理不外发

参考链接

• OmniRoute 官网
• GitHub 仓库 diegosouzapw/OmniRoute
• Cheaper Inference（配套云服务）