OmniRoute | 开源本地 AI 网关，统一模型接入与自动回退

如果你需要在 Claude Code、Codex、Cursor 等客户端之间切换多家模型服务，OmniRoute 把这件事收敛为一个运行在本机的 AI 网关：客户端只配置一个 OpenAI 兼容地址，网关再根据模型、额度、健康状态和路由策略选择上游。它是一个采用 MIT 许可证的 TypeScript 开源项目，适合研究多供应商接入、自动回退与本地控制面的实现。本文依据官方仓库、package.json、Quick Start 和 SECURITY.md 核对；没有在本地实际安装或压测。

截至 2026 年 9 月 2 日核对，GitHub 最新稳定 Release 是 v3.8.50，发布时间为 2026 年 8 月 26 日；仓库默认分支为 release/v3.8.51，该分支的 package.json 版本为 3.8.51。GitHub 页面当时约有 6.00 万 stars 和 8.3k forks。Release、分支版本和页面统计会继续变化，安装前应以仓库当前内容为准。

它把多家模型服务接在哪一层

OmniRoute 的边界可以用一条调用链理解：编码工具或 Agent → 本地 OmniRoute → 已配置的模型提供商。网关默认监听 http://localhost:20128，客户端使用的 Base URL 是 http://localhost:20128/v1；本地控制台负责提供商连接、组合路由、配额查看和 API 密钥管理。这样做的好处是切换上游时不必逐个修改客户端配置，但它并不会替你创建供应商账号、绕过地区限制或保证任何免费额度。

层次	OmniRoute 提供的能力	使用时要留意
统一入口	本机一个 OpenAI 兼容 `/v1` 地址	本地 API 密钥仍需妥善保管，不能当作上游授权
路由层	`auto` 与可组合的优先级、权重、轮询等策略	不同模型的上下文、工具和输出能力并不完全相同
提供商层	API Key、OAuth、免费目录和兼容协议接入	可见条目不等于当前可用，资格、区域和 ToS 由上游决定
压缩层	RTK + Caveman 请求压缩与输出过滤	15–95% 是项目口径，实际节省取决于提示词和客户端
控制与审计	配额、日志、密钥范围、限流和本地 SQLite 审计记录	仍需自行设置密钥、保留周期、备份和网络边界

组合路由与自动回退：为什么不是简单代理

在最简单的用法中，把模型写成 auto 即可让 OmniRoute 从可用提供商中选择路径。README 将项目描述为支持 19 种路由策略，包含优先级、先填充、加权、轮询、最少使用、成本优化以及按上下文能力选择等思路；组合路由还可以把多个提供商编排成一个可复用的组。当某一路径失败、熔断或触及额度时，网关可以继续尝试后备路径，减少临时更改客户端配置的次数。

自动回退并不等于结果完全一致。上游模型可能在上下文长度、函数调用、视觉输入、结构化输出和内容政策上存在差异；同一个请求切换到另一模型后，速度、价格和输出风格也可能变化。因此，重要工作流应对关键模型设置明确优先级和能力约束，并在真实请求中检查工具调用、JSON 结构和长上下文，而不是只看“请求成功”。

压缩、协议桥接与工具接入

OmniRoute 还把请求压缩和客户端兼容放在同一控制面里。项目介绍的 RTK（冗余令牌压缩）与 Caveman（提示词压缩）组合，宣称可节省约 15%–95% 的令牌；这是项目自己的估算，不是本文独立测试，也不应直接换算成固定成本折扣。网关同时提供 OpenAI 兼容接口，并在仓库说明中列出 Claude Code、Codex、Cursor、Cline、Copilot 等客户端，以及 MCP/A2A 等扩展方向。

官方仓库附带的 Providers 页面截图能看出它的控制面思路：API Key 兼容、免费层和 OAuth 提供商被分组管理，连接状态和测试入口集中在同一页。截图中的 OmniRoute 版本、卡片数量和连接状态属于截图生成时点（界面左侧显示 v3.8.1），不代表当前 v3.8.51 分支或最新目录的实时数据。

OmniRoute Providers 提供商管理界面 — OmniRoute 官方仓库附带的 Providers 管理界面截图；图中版本与提供商数量为截图时点的示例信息，不代表当前实时目录。来源：https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/docs/screenshots/MainOmniRoute.png

安装与第一次接入

npm 路线

package.json 要求 Node.js >=22.22.2 <23 或 >=24.0.0 <27。满足条件后，可以按 Quick Start 安装全局 CLI：

npm install -g omniroute
omniroute

启动后访问 http://localhost:20128，按控制台提示连接提供商并创建一个 OmniRoute 本地 API 密钥。官方 Quick Start 也给出源码路线：克隆仓库、执行 npm install，再用 npm run dev 启动开发环境。本文没有在本地执行这些命令，版本兼容性请以当前分支的 engines 字段和文档为准。

Docker 路线

容器用户可以先用官方示例快速启动，并把端口限制在本机回环地址：

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

README 说明 :latest 指向已发布的最高稳定语义版本，并不等于 Git 默认分支；需要可复现构建时应把它替换为明确的 :X.Y.Z 标签并记录数据迁移。并发长上下文会提高内存需求，Docker 的内存限制应按实际 Agent 数量和请求长度调整。

把客户端指向本地网关

在控制台创建 API 密钥后，客户端填写 Base URL http://localhost:20128/v1、刚生成的密钥和模型 auto。官方 Quick Start 给出的 Codex 启动方式是：

omniroute launch-codex --model auto

也可以先用 curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY" 检查本地网关是否返回模型列表，再发送一个最小的聊天请求。密钥只在控制台创建时展示一次，建议立即保存到本地密码管理器，不要提交到项目仓库或截图中。

密钥、日志与本地优先边界

OmniRoute 的 SECURITY.md 描述了较完整的本地控制面：请求经过 CORS、授权、guardrails、限流、熔断和模型锁定等层后才到达提供商；仪表盘使用密码和 JWT，API 密钥采用 HMAC/CRC，提供商 OAuth 使用 OAuth2 + PKCE。项目还建议设置 JWT_SECRET（至少 32 个字符）、API_KEY_SECRET（至少 16 个字符）和 STORAGE_ENCRYPTION_KEY。

安全文档明确说明，只有配置 STORAGE_ENCRYPTION_KEY 时，静态凭据才会以 AES-256-GCM + scrypt 方式加密；缺少该变量时会保留明文透传行为。README 将 telemetry 描述为默认关闭，并提到密钥范围、IP 过滤、限流、上游请求头清理和本地审计记录，但这些是项目设计声明，不是对任何部署环境的绝对保证。

部署边界：guardrails 中的 prompt-injection 和 PII 处理属于启发式防护，文档标注为 fail-open，不能当作完整防火墙。将管理界面或 API 端口暴露到公网前，至少应配置强密钥、HTTPS、反向代理认证和防火墙规则；Provider 的原始密钥不应写入前端代码、公开日志或镜像层。

免费目录、维护状态与使用取舍

README 当前展示约 355 个提供商、150+ 个免费入口，并以目录口径估算每月可用令牌池；这些数字会随上游政策和去重口径变化，不能理解为 OmniRoute 向用户发放的额度。免费入口可能要求 OAuth、注册、特定地区或额外资格，也可能受到速率、并发、模型范围、KYC 和服务条款限制；真正启用前应逐项阅读上游规则。

如果你只使用一家稳定供应商，直接使用该供应商的原生客户端配置往往更简单；OmniRoute 更适合需要统一入口、跨提供商切换、额度感知和故障回退的人。维护方面，SECURITY.md 将 3.8.x 标为 Active、3.7.x 标为 Security、低于 3.7.0 标为 Unsupported；这也是为什么应区分最新稳定 Release 与默认分支上的开发版本。

MIT 许可证与二次开发边界

OmniRoute 使用 MIT License，通常可以在保留版权和许可证声明的前提下使用、修改和再分发源码。MIT 许可不替你取得任何上游模型的使用权，也不覆盖供应商的订阅、积分、区域限制、数据政策或输出内容许可。自托管可以把网关和控制面放在自己的机器上，但备份、访问控制、日志保留、隐私告知和合规审查仍由部署方负责。