[Github] OmniRoute – 为 Codex 等工具统一 AI 模型入口

Github发现2026-08-30发布 WarpEdit

OmniRoute 是放在 Codex、Claude Code、Cursor 等工具与多家 AI 服务之间的本地网关。工具只连接一个 OpenAI 兼容地址，OmniRoute 再按模型可用性、额度、成本和回退规则选择下一跳。它解决的是多账号、多密钥和多模型切换，不是一个新的大模型，也不会自动赠送项目目录里列出的全部免费额度。

OmniRoute 将一个本地端点的请求按健康、额度、成本和回退策略路由到不同 AI 服务 — OmniRoute 用一个本地兼容端点集中处理模型选路与失败回退。

它接管哪一层

典型调用链是“编码工具 → OmniRoute → 模型提供商”。OmniRoute 默认在本机提供 http://localhost:20128/v1，上游工具继续使用熟悉的 OpenAI 兼容请求格式；提供商的认证、模型映射、额度状态、健康检查和失败回退则由网关集中处理。

这层抽象的实际收益是减少工具侧配置。团队不必在每个编辑器和 Agent 中重复保存十几组 Base URL、模型名和密钥，也可以在不改客户端配置的情况下调整后端顺序。但“支持某个提供商”只表示 OmniRoute 具备对应适配或目录项，不表示用户已经拥有该服务的账号、地区资格或可用配额。

项目 v3.8.50 的 README 表格列出 350 个提供商和 1,312 个唯一聊天模型 ID；默认分支的包版本已经是 3.8.51。此类目录会持续变化，模型 ID 也可能包括同一基础模型在不同提供商处的入口，因此不能把数量直接等同于 1,312 个彼此独立、开箱即用的模型。

一条地址接入

安装与启动

官方提供 npm、Docker 和源码安装。npm 全局安装命令是 npm install -g omniroute；当前 package.json 要求 Node.js >=22.22.2 <23 或 >=24 <27。Docker 可以把 20128 端口映射到本机，但准备长期部署时，官方建议固定具体版本，而不是一直跟随 latest。

docker run -d --name omniroute \
  -p 20128:20128 \
  diegosouzapw/omniroute:latest

启动管理界面后，先连接至少一个自己有权使用的提供商，再创建 OmniRoute 本地 API Key。README 提到新安装会预接无需密钥的 OpenCode Free 路径，而 Quick Start 仍按“连接提供商 → 创建本地 Key”组织步骤；为了让配置可追踪，实际接入时按 Quick Start 完成这两步更稳妥。

工具怎么连

在编码工具里，把 Base URL 指向 http://localhost:20128/v1，API Key 填刚创建的 OmniRoute Key，模型先使用 auto。项目也提供面向 Codex 的启动命令 omniroute launch-codex --model auto。如果网关运行在另一台机器，地址应替换为实际受保护的主机，但不要在没有鉴权和网络边界的情况下把管理端与 API 端口直接暴露到公网。

OmniRoute 官方 Endpoint 页面显示本地 API 地址、Registered Keys 和可用端点类型 — 官方 Endpoint 页面集中显示本地 API 地址、已注册密钥和兼容端点；截图中的局域网 IP 只是示例环境。

auto 如何选路

model=auto 不是随机抽取一个模型。OmniRoute 会结合请求能力、上下文、提供商健康状态、剩余额度和已配置策略选择候选路径；请求失败时，再根据回退链尝试下一项。对需要固定模型家族的任务，还可以创建 Combo，把多个提供商提供的同一模型或相近模型组成一个逻辑名称。

项目提供优先级、轮询、加权、成本优化、最少使用等多种组合方式，并在 README 中列出 19 种路由策略。策略名称本身不能替代业务判断：成本优先可能降低结果一致性，轮询会把请求分散到不同服务，跨模型回退则可能改变上下文长度、工具调用格式、图像支持和输出风格。

OmniRoute 官方 Combos 页面展示优先、轮询、加权和成本优化等组合路由 — 官方 Combos 页面展示多种组合策略；真正的候选模型、权重和回退顺序仍需按任务配置。

用于代码修改、结构化输出或 Agent 工具调用时，建议先建立一组小型验收请求：检查工具调用参数、JSON 格式、长上下文、流式响应和失败重试，再决定哪些模型可以互相回退。若任务必须保持同一模型行为，应使用明确模型或受限 Combo，而不是把所有可用入口都交给 auto。

免费额度怎么算

仓库首页给出的约 15.1 亿月度循环免费 token 是项目维护者依据公开政策整理的估算，不是 OmniRoute 发放给单个用户的额度。Free Tiers 文档说明，这个合计来自 39 个有明确正数月度预算的循环池，并做了去重；首月若计入一次性注册额度，估算约为 21.3 亿。无上限服务和理论可达 100 亿的额度没有计入总和。

这些数字仍受账号审批、地区、KYC、速率限制、模型范围和政策变更影响，最后一次集中调研日期与后续更新时间也分别记录在文档中。更重要的是，一些提供商被标为 caution、avoid 或 unknown。项目中的 ToS 风险标签主要用于提示和汇总，excludeTosAvoid 只影响汇总视图，不等于全局路由会自动阻止这些服务。

因此，免费路由的正确用法是逐个核对提供商条款和账户状态，再把确认允许自动化访问的入口加入策略。不要把聚合表的理论总额写进预算，也不要把个人订阅、开发者试用或禁止转售的额度当成可供团队共享的公共资源。

压缩与转换

OmniRoute 还集成 RTK 与 Caveman 等压缩路径，项目宣称在符合条件的内容上可节省约 15%–95% token。这个范围是项目说明，不是本文独立测得的结果；代码、日志、重复上下文和自然语言对压缩的适应程度不同，压得越激进，越可能丢失命令细节、文件位置或对话约束。

协议转换同样需要测试。不同提供商对 system message、tool call、图片输入、缓存、推理参数和错误码的实现并不完全相同。网关可以统一接口，但无法让所有后端能力天然一致。重要任务应记录实际落到哪个提供商和模型，并保留一条关闭压缩或固定路由的排查路径。

密钥与日志

安全文档说明，OmniRoute 支持 Dashboard JWT、本地 API Key 的 HMAC 校验，以及提供商支持时的 OAuth2/PKCE。凭据静态加密使用 AES-256-GCM 和 scrypt，但前提是设置 STORAGE_ENCRYPTION_KEY；如果没有设置，系统会进入明文直通存储模式。这是部署前必须处理的条件，不应只因为服务运行在本机就忽略。

服务端模式还要求设置足够长度的 JWT_SECRET 与 API_KEY_SECRET，并建议同时配置存储加密密钥。若需要远程访问，应限制管理路由、绑定地址、防火墙和反向代理权限，确认备份文件同样受保护，避免把真实提供商密钥写进仓库、镜像或公开环境变量示例。

项目支持请求日志、审计记录、保留期和按 Key 的 noLog 控制。涉及源代码、客户数据或私有提示词时，应先决定哪些字段可以留存、保留多久、谁能查看。Guardrails 出现异常时采用 fail-open 行为，而且请求可以选择退出，因此它不能代替客户端侧的数据分级和提供商侧的隐私策略。

版本与许可

截至 2026-08-30，GitHub 显示项目约有 58,225 Stars、8,045 Forks 和 207 个 Open issues，仓库未归档。最新 GitHub Release 是 2026-08-26 发布的 v3.8.50，而默认分支已经推进到 3.8.51。生产环境应固定经过验证的 Release 或镜像标签，并在升级前检查配置迁移、路由策略和密钥读取方式。

仓库代码采用 MIT License，可以在保留许可声明的条件下使用、修改和分发。但 MIT 只约束项目有权许可的代码，不会覆盖上游模型提供商的服务条款、订阅限制、数据政策和模型输出许可。通过 OmniRoute 发出请求，并不会改变用户与各提供商之间原有的责任关系。