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

OmniRoute 是采用 MIT 许可的开源本地 AI 网关，给支持兼容接口的客户端提供统一模型入口，再按配置把请求转给上游服务。它适合同时维护多家模型连接、希望集中管理路由和回退的用户；客户端仍需满足对应协议和配置要求。

调用关系可以理解为“客户端 → OmniRoute → 模型提供商”。本机网关统一了配置位置，调用云端模型时，请求仍会发给上游。网关代码开源、服务运行在本地，都不代表模型调用免费或内容只留在本机。

两种密钥，分别负责哪一段连接

提供商的 API Key 或 OAuth 凭据，让 OmniRoute 有权调用上游；在 OmniRoute 控制台创建的本地 API Key，让客户端有权访问网关。把两者混用，可能导致认证失败，也会扩大原始提供商密钥的暴露范围。

默认管理地址是 http://localhost:20128，兼容接口的 Base URL 为 http://localhost:20128/v1。先连接自己已有权限使用的提供商，再创建网关密钥；目录里能看见某个服务，不等于账号已有资格或该服务现在可用。

先打通一个模型，再启用自动选择

1. 选择 npm、Docker 或源码运行方式。npm 安装前核对包的 Node.js 要求；当前主分支允许 >=22.22.2 <23 或 >=24.0.0 <27。
2. 按所用版本配置启动密钥。安全文档要求 JWT_SECRET 与 API_KEY_SECRET 使用足够强的值，STORAGE_ENCRYPTION_KEY 用于静态凭据加密；配置文件不要公开。
3. 在控制台连接一个提供商并创建网关 API Key，保存创建时展示的密钥。
4. 请求模型列表，确认客户端能访问网关，再对一个明确模型发送最小请求。
5. 基础调用稳定后，再配置 auto 或组合路由，并检查实际选到的模型、工具调用与输出格式。

npm 路线的命令入口如下，运行前的密钥配置按对应版本文档完成：

npm install -g omniroute
omniroute

客户端填写网关 Base URL 与网关密钥后，可先用以下请求查看模型列表。YOUR_KEY 是占位值，替换时不要把真实密钥写进公开材料：

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

Docker 部署要保留数据目录，并按用途限制端口访问范围。latest 对应已发布的稳定版本，不等于 Git 默认分支；持续使用时固定镜像标签，记录配置和数据库变化。

回退解决可用性，也会改变输出条件

组合路由可以按优先级、轮询、权重或其他策略选择路径，失败、冷却或额度不足时尝试后备模型。用到多个服务以后，客户端不必逐个改地址；但回退模型可能拥有不同上下文、工具支持、视觉能力和价格。

• 结构化输出：先确认后备模型支持所需格式，返回了文字不等于返回了可解析的业务结果。
• 工具调用：核对调用参数和执行行为，不能只以 HTTP 成功判断 Agent 任务完成。
• 长上下文与图片：确认所有允许回退的路径都能接收输入，避免成功转发后丢掉任务需要的信息。
• 费用与速度：自动切换可能增加重试等待或改用计费服务，路由优先级要与预算一致。

请求压缩和过滤也是可选取舍。README 的令牌节省比例来自项目自己的介绍，不能直接换算成固定账单折扣。精确约束、代码和工具返回内容参与压缩时，应先检查关键任务是否仍能完成，再扩大使用范围。

本地控制面保存的东西，需要一起管理

提供商凭据、连接状态、配置与日志会进入网关的维护范围。安全文档说明，只有设置 STORAGE_ENCRYPTION_KEY 才启用对应静态凭据加密；未设置时保留明文透传方式。加密密钥与数据库备份要妥善保存，不能把“本地 SQLite”直接理解成无需保护。

日志可以帮助看清客户端发了什么，也可能含代码、提示词和业务数据。按用途设置保留周期和访问范围；提供商的数据处理条件另外确认。免费目录只是上游条款和额度的汇总，OmniRoute 不会为用户发放目录里列出的全部额度。

Guardrails 包含 PII 处理与提示词注入启发式检查，文档明确采用 fail-open：异常不阻断流量。它们不能替代账号权限、网络限制或业务校验。管理界面和 API 需要对外使用时，应按部署文档配置 HTTPS 与认证，不能直接沿用个人本机入口。

需要修改时，先区分界面、路由和提供商

控制台页面、路由策略和上游协议适配解决不同问题。连接失败时，先判断错误来自客户端认证、网关路由还是提供商；二次开发再按仓库结构进入对应代码。只用一家服务且不需要路由时，直接配置原生接口也更容易维护。

MIT 许可覆盖的是网关代码，供应商订阅、OAuth 资格、地区范围和模型内容条件仍独立存在。新增提供商或客户端桥接前，先核对该路径的当前文档，不把旧截图中的卡片数量或连接状态当成实时能力清单。

• 项目仓库：https://github.com/diegosouzapw/OmniRoute
• 快速开始：https://github.com/diegosouzapw/OmniRoute/blob/HEAD/docs/getting-started/QUICK-START.md
• 安全与凭据配置：https://github.com/diegosouzapw/OmniRoute/blob/HEAD/SECURITY.md