项目快照：cheaper-inference/OmniRoute，约 79,330 个 Star，11,545 个 Fork；最新推送时间 2026-10-21T17:51:48Z。本文基于仓库公开资料撰写。
项目地址：https://github.com/cheaper-inference/OmniRoute · https://omniroute.online
项目速览（TL;DR）
OmniRoute 是用 TypeScript 编写的开源人工智能（AI）网关，目标是将多个模型服务商和开发工具接入统一入口，并提供路由、回退与请求压缩能力。根据 GitHub 仓库资料，项目采用 MIT 许可证，默认分支为 release/v3.8.53；仓库资料列出 375 个服务商、150 多个免费层级服务商和 1400 多个模型。
README 提到的免费额度是多个第三方服务商免费层级的汇总估算，不是 OmniRoute 发放的令牌额度。实际可用服务、额度和条款由各服务商分别决定；使用者需要自行注册并提供相应凭据。
| 项目项 | 仓库资料 |
|---|---|
| 语言 | TypeScript |
| 许可证 | MIT |
| 默认分支 | release/v3.8.53 |
| 服务商与模型规模 | 375 个服务商、1400 多个模型；README 标注 150 多个免费层级服务商 |
| 集成方向 | Claude Code、Codex、Cursor、OpenCode、Cline、Copilot 等工具 |
| 项目版本 | package.json 标注为 3.8.53 |
定位与目标用户
OmniRoute 面向需要在多个模型服务之间切换或集中管理调用入口的开发者与团队。它将兼容接口、服务商接入、路由和运维控制放在同一个项目中，减少应用分别对接多个模型服务时需要维护的连接逻辑。
这一定位不意味着所有服务商都能免配置使用。README 明确采用“自备服务商账号”的方式，服务商凭据、免费额度、可用模型和服务条款仍需逐一确认；OmniRoute 不能代替服务商授权，也不构成模型服务可用性的保证。
核心功能
核心能力围绕统一入口、请求路由、额度感知回退和压缩展开。下面分别说明资料能够确认的机制边界；具体接口字段、策略参数和内部实现细节未包含在给定资料中。
统一模型网关
项目描述称其提供一个入口连接多个服务商，并包含 OpenAI 兼容 API。其作用是让支持相应接口的客户端把请求发往网关，再由网关将请求路由到已配置的模型服务；完整的接口路径、请求格式、鉴权方式及响应映射规则，官方仓库未提供该信息，建议以最新 README 为准。
路由与自动回退
项目描述列出额度感知的自动回退，并在 README 图示说明中提到路由策略。按这一描述，路由会结合服务商或模型的可用额度选择后备目标；回退触发条件、优先级配置、重试次数和错误分类规则没有出现在给定资料中，不能据此推断具体行为。
请求压缩
README 和 package.json 提及 RTK 与 Caveman 组合压缩，并给出 15% 至 95% 的节省范围及约 89% 的平均值描述。资料未提供这组数据对应的输入集、计算方式、模型、误差范围或复现命令，因此应将其视为项目文档中的宣传性测量描述，而非对任意请求的性能保证。
从功能描述看，压缩组件处理的是发往模型的请求内容；其确切触发条件、是否可按客户端或模型关闭、压缩后语义质量如何评估，官方仓库未提供该信息，建议以最新 README 为准。
MCP 与 A2A
项目资料列出模型上下文协议（Model Context Protocol，MCP）和智能体间通信（Agent-to-Agent，A2A）支持。给定内容没有具体传输方式、工具发现流程、授权模型或配置字段，因此不能将其扩展解释为某种特定协议版本或兼容性承诺。
桌面端与渐进式 Web 应用
项目描述包含桌面端和渐进式 Web 应用（Progressive Web App，PWA）。README 展示了仪表板，并指向免费层级状态页面；各平台的打包格式、系统要求和安装方式未包含在给定资料中，官方仓库未提供该信息，建议以最新 README 为准。
系统架构与关键模块
现有资料显示，OmniRoute 由 Node.js 运行环境承载，代码以 TypeScript 为主，并包含服务端、共享代码、模型与领域逻辑等目录。由于没有完整目录清单和架构文档正文，以下只记录可核实的模块，不推断进程边界或内部调用链。
| 模块或组成 | 资料中的证据 | 可确认的作用边界 |
|---|---|---|
src/server/ | package.json 的发布文件清单 | 包含服务端相关源文件；具体路由职责未提供 |
src/domain/ | package.json 的发布文件清单 | 包含领域层相关源文件；内部领域模型未提供 |
src/models/ | package.json 的发布文件清单 | 包含模型相关源文件；模型注册结构未提供 |
src/lib/ | package.json 的发布文件清单 | 包含库代码；模块职责需查阅仓库文件 |
open-sse/ | package.json 工作区配置 | 独立工作区；更具体功能未提供 |
packages/browser-pool | package.json 工作区配置 | 独立工作区；具体用途未提供 |
仓库还提供 Docker Compose 配置，列出 base、web、cli、host、cliproxyapi、memory 和 bifrost 等配置档案。Compose 注释说明，memory 可添加 Qdrant sidecar，bifrost 可添加 Bifrost Go sidecar；更详细的组件决策文档在资料中被引用，但其正文未提供。
依赖与运行环境
根据 package.json，项目要求 Node.js 版本符合 >=22.22.2 <23 || >=24.0.0 <27。这表示 Node.js 23 不在声明范围内；运行前应核对本机版本与该范围，不能仅凭“安装了 Node.js”判断兼容。
Dockerfile 的基础镜像标注为 node:26-trixie-slim。项目还包含原生依赖构建相关脚本和安装后脚本，但给定资料没有列出完整依赖清单、操作系统矩阵或原生模块的逐项要求。
- 语言：TypeScript。
- 运行时：Node.js，版本范围以
package.json的engines字段为准。 - 容器部署：仓库提供 Dockerfile 与 Docker Compose 配置。
- 数据库、缓存和外部服务：Compose 配置中出现 Redis、Qdrant 和 Bifrost 等组件；是否启用取决于档案配置。
快速开始（含最小可运行示例）
给定资料包含 Docker Compose 的实际启动命令，但没有提供完整的首次安装、服务就绪检查或 API 验证示例。为避免编造接口路径和安装步骤，以下只展示资料中明确出现的基础档案启动方式；这不是完整的端到端 API 验证流程。
docker compose --profile base up -d该命令来自仓库 docker-compose.yml 的用法注释。Compose 注释还要求首次运行前将 .env.example 复制为 .env 并编辑密钥；但具体必填项与复制命令未包含在给定内容中，官方仓库未提供该信息，建议以最新 README 和环境变量示例为准。
docker compose --profile cli up -d --build第二条是仓库针对 cli 档案提供的命令，注释特别标明 Windows Docker Desktop 用户需要随容器构建 CLI 镜像。执行前需要从仓库根目录使用实际 Compose 文件，并准备其要求的环境配置；示例中没有放入服务商密钥，避免将凭据写入命令历史。
关于“验证”步骤，现有资料没有提供健康检查地址、验证命令或具体 API 请求样例。端口配置虽在 Compose 中出现，但资料不足以确定应请求哪个路径及其鉴权格式，因此不在此处给出虚构的 curl 示例。
配置说明
下表只列出给定 docker-compose.yml 中明确出现的配置项。默认值以 Compose 表达式中的字面值为依据；使用者还应检查自己的 .env，因为实际运行时值可能受环境变量覆盖。
| 字段名 | 类型 | 默认值 | 作用 |
|---|---|---|---|
DATA_DIR | 路径字符串 | /app/data | Compose 注释说明该值必须与数据卷挂载保持一致。 |
PORT | 端口字符串 | 20128 | 容器环境配置中的应用端口变量。 |
DASHBOARD_PORT | 端口字符串 | 20128 | 仪表板端口变量。 |
API_PORT | 端口字符串 | 20129 | API 端口变量。 |
API_HOST | 主机字符串 | 127.0.0.1 | API 主机绑定配置。 |
LIVE_WS_PORT | 端口字符串 | 20132 | 实时 WebSocket 服务端口变量。 |
LIVE_WS_HOST | 主机字符串 | 127.0.0.1 | 实时 WebSocket 主机绑定配置。 |
REDIS_URL | URL 字符串 | redis://redis:6379 | Redis 服务连接地址。 |
NODE_OPTIONS | 运行时选项字符串 | --max-old-space-size=2048 | Compose 公共环境配置中的 Node.js 选项。 |
Compose 还配置了 OMNIROUTE_BASE_PATH、LIVE_WS_ALLOWED_ORIGINS 和 OMNIROUTE_CODEX_APPSERVER_WS。其中可确认的默认值分别是空字符串、http://localhost:20128,http://127.0.0.1:20128 和 ws://codex-app-server:1456；Codex App-Server WebSocket 配置的注释说明，只有对应 Compose 档案启用时才会使用。完整字段类型、其他环境变量与敏感配置要求，官方仓库未提供该信息，建议以最新 README 为准。
进阶用法
Compose 文件按档案拆分部署选择，适合依据需要启用额外组件，而不是默认将所有 sidecar 一起运行。仓库注释给出了以下实际用法；它们是配置入口，不等同于各组件的完整安装或安全配置说明。
docker compose --profile base --profile memory up -d
docker compose --profile base --profile bifrost up -d
docker compose --profile cliproxyapi up -d第一条启用基础服务并添加 Qdrant sidecar；第二条启用 Bifrost sidecar；第三条单独启用 CLIProxyAPI sidecar。仓库注释为 CLIProxyAPI 标注了端口 8317，为 Qdrant 标注了端口 6333，为 Bifrost 标注了端口 8080；如何鉴权、限制网络可见性及配置持久化，需要查阅对应配置与文档。
对模型路由和压缩的调优，应先确认当前版本提供的实际配置字段、压缩开关和策略参数。资料没有列出这些字段，因此不应直接套用未经核实的环境变量或配置片段。
可观测性与运维
README 指出，免费层级目录的使用量与剩余额度可在仪表板的 /dashboard/free-tiers 页面查看。该页面展示的是目录所记录的免费额度信息；第三方额度会受服务商限制、可用性和条款影响，页面数据不构成服务商承诺。
Compose 公共配置声明容器重启策略为 unless-stopped，停止宽限时间为 40 秒，并通过 env_file: .env 载入环境配置。这些设置可用于理解容器生命周期和配置来源，但日志格式、指标端点、告警规则、备份恢复步骤与升级回滚流程，官方仓库未提供该信息，建议以最新 README 为准。
README 说明免费层级数据每两周重新审计一次，数值会因服务商变化而增减。其方法文档路径为 docs/reference/FREE_TIERS.md，但本资料只给出该文件名和摘要，具体核算细节应以仓库该文件为准。
安全与合规边界
OmniRoute 连接第三方模型服务并处理调用凭据与请求内容，因此部署者需要把服务商授权、凭据管理、网络暴露和数据处理纳入自己的安全边界。这里只讨论获授权账号与合规环境中的使用，不涉及绕过服务商限制或访问未授权系统。
- 仅接入自己拥有使用权或已获组织授权的服务商账号，并遵守各服务商的额度和使用条款。
- 不要将真实密钥写入公开仓库、镜像或命令历史；资料要求从
.env.example准备.env，但没有提供完整密钥管理指南。 - 请求可能包含个人信息、源代码或业务数据；保留、转发、日志记录和第三方处理方式未在给定资料中说明，应在接入生产数据前核实。
- Compose 中可见部分主机绑定默认为
127.0.0.1，但这不足以证明所有服务都只对本机开放；部署前应检查完整端口映射、反向代理与网络配置。 - 免费层级的资格、区域限制和服务条款由提供方控制。README 特别将需要区域身份验证的 ModelScope 额度单独列示，不计入其主要额度标题。
许可证与商用条款
仓库提供的 LICENSE 文件为 MIT License。该许可证允许使用、复制、修改、合并、发布、分发、再许可和销售软件副本，因此可以用于商业用途，但分发时必须包含版权声明和许可声明。
许可证同时按“现状”提供软件，不附带明示或默示担保，并限制作者及版权持有人承担相应责任。实际分发应遵守仓库许可证全文；第三方依赖的许可义务还需结合仓库的第三方声明文件核查，不应把 MIT 许可解释为第三方服务商也采用相同条款。
局限性与已知限制
现有资料能描述项目范围，但不足以确认全部部署和运行细节。以下限制来自资料边界或 README 对外部服务的明确说明，而不是对未展示代码行为的判断。
- 免费额度来自第三方免费层级的聚合估算，不是项目发放的令牌；额度会变化，且服务商保留各自限制与条款。
- 给定材料没有提供首次启动后的健康检查命令、API 路径、鉴权示例或端到端验证请求。
- 自动回退的触发条件、路由策略配置格式、模型兼容差异和失败重试语义未在资料中详述。
- 压缩节省比例缺少可复现基准测试条件，不能直接作为个别工作负载的结果预测。
- Node.js 版本范围有限，部署环境需符合
package.json的声明；其他平台兼容细节未提供。
适合谁
是否采用该项目，可从服务商数量、客户端接入方式和团队承担的运维责任判断。以下信号依据仓库功能描述整理；经验性建议均标注为作者判断。
- 同时使用多个模型服务，并希望通过单一网关入口集中接入的个人或团队。
- 已拥有第三方服务商账号，且能自行管理各服务商凭据、额度与条款的开发者。
- 使用 README 明确列出的 Claude Code、Codex、Cursor、OpenCode、Cline 或 Copilot，并愿意验证其实际接入配置的团队。
- 需要 Compose 部署，并能维护 Node.js 或容器运行环境、环境文件和相关 sidecar 的运维人员。
根据本文作者的经验判断，如果团队无法持续核对第三方免费层级的额度和服务条款，就不应把 README 的聚合数字当作稳定供应计划；应先以实际服务商合同或正式额度安排为准。
不适合谁
项目提供的是网关与路由能力，不会消除上游服务商的授权、可用性与合规约束。以下情形需要先补齐能力或选择符合要求的其他方案；资料没有明确推荐替代项目，因此此处不做产品对比。
- 要求统一且由单一供应方保证额度、可用性或服务等级协议（SLA）的团队；README 明确说明额度来自第三方服务商。
- 无法安全保管多个服务商密钥，或没有权限批准将请求转发到这些服务商的组织。
- 要求在不联网的隔离环境中完成模型推理，但尚未确认所需模型、部署方式和本地推理能力；给定资料没有证明项目提供离线模型运行。
- 必须使用固定版本运行时，却无法满足仓库声明的 Node.js 版本范围，也不准备评估容器部署的团队。
- 需要已验证的性能基准、压缩质量报告或生产 SLA 作为上线门槛，但当前提供资料不包含这些证据的团队。
常见问题与排查（FAQ / Troubleshooting）
排查时应先区分网关自身配置问题和第三方服务商状态问题。给定资料能够确认运行时范围、Compose 档案与部分环境字段，但没有提供通用诊断命令和错误码索引。
Node.js 版本不匹配怎么办？
核对 package.json 的 engines 字段，版本范围为 >=22.22.2 <23 || >=24.0.0 <27。如果使用 Docker，则 Dockerfile 基础镜像为 node:26-trixie-slim；不要把 23.x 视为声明支持的版本。
Compose 启动后，免费额度为何不可用？
README 说明这些额度来自第三方免费层级，用户需要自行注册、取得凭据并连接对应服务商。还应检查服务商自己的地域资格、账户状态、限流与条款；目录中的汇总数不代表当前账号已经获得相同额度。
Windows Docker Desktop 如何启用 CLI 档案？
Compose 注释建议 Windows Docker Desktop 用户使用打包 CLI 的镜像，并给出命令 docker compose --profile cli up -d --build。宿主机挂载的 host 档案被标注为 Linux 优先且仅 Linux，不能据此推断 Windows 主机挂载方案可用。
服务启动了，如何验证 API？
现有资料没有给出 API 健康检查地址、鉴权方式或调用示例。配置中出现 API_PORT=20129，但仅凭端口不能确定可访问路径和请求格式；应以项目当前 README 或对应接口文档为准。
自动回退为何没有切换到其他模型？
项目描述确认存在额度感知自动回退，但给定资料未列出启用条件、可回退目标、错误分类或日志字段。先检查已配置的服务商凭据和上游额度，再根据当前版本文档核实路由规则；不要假设所有错误都会触发回退。
引用说明
README 的核心定位是为不同 AI 工具提供统一服务商入口。以下引文保留其英文原文，中文释义不改变其承诺边界。
“Every AI tool → 375 providers — 150+ free — through one endpoint.”
来源：README。该描述是项目能力概述；免费层级额度由第三方服务商提供，需由使用者自行获取并遵守各自条款。
项目地址与资源
仓库与官网是核对版本、配置和额度方法的首要来源。README 中引用的免费层级说明文档可用于进一步核实其统计口径。
- GitHub 仓库：OmniRoute 项目仓库
- 官网与文档入口：OmniRoute 官网与文档
- README 中的免费额度方法文档：免费层级统计方法
