OmniRoute四级自动降级原理：Subscription→API→Cheap→Free，AI请求永不掉线-编程实验室

OmniRoute四级自动降级原理：Subscription→API→Cheap→Free，AI请求永不掉线

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 是一款 MIT 协议的免费 AI 网关，用「四级自动降级」路由机制统一管理 350 多个提供商、1200+ 模型（Kimi、Claude、GPT、Gemini、GLM、DeepSeek、MiniMax 等），并原生适配 Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 等工具。当订阅额度用尽、API 限流或廉价通道失效时，它会自动沿Subscription → API → Cheap → Free四级阶梯逐级切换上游，保证 AI 请求永不掉线。

一图看懂：四级自动降级如何工作

传统用法是：每个 AI 工具各配一把 API Key，额度用完就手动换 Key，稍不留神 Coding 就中断。OmniRoute 的解法是在所有工具和上游之间加一个"智能路由器"，请求先走你最优质的订阅连接，额度见顶后无缝滑向API Key，再不够就切到廉价通道（Cheap），最后落到**免费额度（Free）**兜底——全程无需人工干预。

路由入口是一个本地 OpenAI 兼容端点（默认http://localhost:20128/v1），你的 IDE 或 CLI 只需要把 Base URL 指过来，降级、熔断、重试全部发生在网关内部。

四级阶梯详解：每一级"耗尽"的信号都不同

关键洞察：降级不是简单"按价格排序"，而是每一级都有自己独立的耗尽判定信号——这正是 OmniRoute 降级体系区别于普通负载均衡的核心。四级阶梯的完整设计详见 docs/routing/SUBSCRIPTION_LADDER.md。

级别	通道	何时判定"耗尽"
Tier 1	Subscription 订阅	配额窗口触及截止线（如 Claude Code / Copilot 套餐配额）
Tier 2	API Key 按量	触发限流 429 或熔断器打开
Tier 3	Cheap 廉价	该档位预算（budget）被消耗完
Tier 4	Free 免费	免费额度用尽（始终常驻兜底）

Subscription 级：网关维护一份人工策展的"连接计费目录"（open-sse/config/connectionBillingCatalog.ts），逐连接判断"这个模型在我这条连接上到底收不收费"——同一个模型，走订阅连接是套餐内含，走 API Key 连接则按 Token 计费。
Cheap / Free 级：订阅和 API 级有真实配额可观测，而付费档没有"额度"概念，因此用每档预算上限作为耗尽信号，没有信号就无法谈"升级"。
请求内兜底：即使预检没拦住额度，运行中的请求失败后也会沿阶梯继续向下穿透（投机式重试循环），失败先分类再决定重试策略，详见 docs/OMNIROUTE_PROVIDER_FAILOVER.md——超时、限流、5xx 可回退，鉴权错误则不会盲目重试。

三个工程细节，让"永不掉线"真正成立

1️⃣ 配额感知 + 健康度持续探测网关对每个连接持续做配额遥测（docs/OMNIROUTE_QUOTA_TELEMETRY.md），候选池构建时按实时健康度动态打分，配额耗尽、熔断打开的候选直接出局，未知配额保持中性分，路由决策完全可解释。

2️⃣ 防抖滞回带（Anti-flap）如果额度在截止线附近徘徊，请求会在两档之间反复横跳。OmniRoute 用"退出截止 2%、重新准入需剩余 5%"的滞回带解决震荡——正在使用的连接只要剩余额度高于 2% 就继续服务，而刚重置的档位必须回到 5% 以上才重新入池。

3️⃣ 额度重置后自动"升回去"很多网关一旦掉到免费档就再也不回来了。OmniRoute 做到三件事同时失效才算"可回切"：配额状态缓存（180 秒 TTL）的resetAt一旦过期立即强制刷新、阶梯本身不保存任何状态（每次建池都从实时配额重算，不存在"卡在第 3 档"）、连接冷却时间被钳制到上游真实重置时刻。订阅套餐午夜一重置，下一个请求立刻回到 Tier 1，一分钱不多花。

最快上手：两条命令体验四级降级

仓库 clone 下来即可本地运行：

git clone https://gitcode.com/GitHub_Trending/om/OmniRoute cd OmniRoute && npm install && npm start

启动后在任意 AI 工具的配置里把端点指向http://localhost:20128/v1，然后通过两个"虚拟模型 ID"选择降级风格（均为按需启用，不影响现有配置）：

模型 ID	行为	适合谁
`auto/thrifty`	全阶梯`subscription → keyless → free → cheap → premium`，耗尽一级升一级	想让订阅额度"一分都别浪费"的用户
`auto/subscription`	只走订阅连接，额度用尽即明确报错（fail-closed）	预算严格管控、绝不允许意外扣费的用户

两者都支持与类别组合，例如auto/coding:thrifty。路由决策完全透明——调用POST /api/omniroute/route/preview即可看到每个候选的得分、因子和落选原因，且零上游真实请求（见 docs/OMNIROUTE_ROUTING_POLICY.md）。

在仪表盘里观察降级过程

Health 面板：实时查看每个连接的配额窗口、熔断状态与重置倒计时，降级发生时一眼就能看清"谁顶上了"。
Analytics 面板：统计各档位的用量与节省金额，验证降级是否真的帮你省钱。
Compos 面板：调整组合内的通道顺序与预算参数。

常见问题 FAQ

Q1：降级是"掉线重连"吗？不是。降级发生在网关内部，对客户端是一个连续流式响应，即使某一级在请求中途失败，投机式重试也会在同一次请求内切换到下一级。

Q2：免费档会不会有质量落差？Free 级同样进入评分体系，由模型偏好、可靠性等因子共同决定最终选择；且搭配 RTK + Caveman 压缩（节省 15–95% Token）后，免费额度的可用性被进一步放大。

Q3：如何确保"绝不意外扣费"？使用auto/subscription时，所有未策展、配额不可验证、超额会转为计费的连接都会被排除；池子为空时返回明确错误，而不是悄悄切到付费通道。

总结

OmniRoute 的四级自动降级（Subscription→API→Cheap→Free）本质是一套"配额感知 + 逐档预算 + 防抖回切"的可靠性系统：它让订阅额度被最大化利用，API 限流被自动绕行，免费额度成为永不断线的最后防线。配合 19 种路由策略、MCP/A2A 与本地优先的加密存储，它是个人开发者和团队"一个端点跑通所有 AI 工具"的高性价比基础设施。