首页 / AI Trending / diegosouzapw/OmniRoute

OmniRoute 是什么？

OmniRoute 是 TypeScript/Next.js 写的本地 OpenAI 兼容网关，把 Claude Code、Codex CLI、Cursor、Cline 等编程工具发出的请求按订阅→API Key→低价→免费四级 Combo 自动路由到 160+ Provider，附带 Dashboard、MCP Server、A2A 协议端、Electron 桌面端。

⭐ 5,006 Stars 🍴 841 Forks TypeScript MIT 作者: diegosouzapw
来源：README + package.json + docs/ARCHITECTURE.md 查看 GitHub 仓库 →

为什么值得关注

OmniRoute 之所以受关注，是因为它把过去散落在 ClawRouter、9router、各种 OAuth 代理脚本里的能力做成了一个可上手的本地服务。开发者只要 npm install -g omniroute 就能拿到 Dashboard、MCP Server 和一份 4 级回退 Combo，把 Kiro、Qoder、Qwen、Gemini CLI 等免费额度连成「$0/月」工作流，对国内用户和预算紧的开发者来说替代付费订阅的吸引力很大。最近一年节奏明显提速：v3.6 引入 WebSocket Bridge、Sync Token、Hybrid Token Counting，v3.7 直接把 Codex GPT-5.5、CrofAI 加进默认 Provider 库，issue 和 PR 都活跃。仓库 ★2.7K、Fork 408、29 个 MCP 工具、41 种界面语言，叠加 Docker 多架构与 Electron 桌面端，把「LLM 网关」这个赛道从命令行工具卷成了带运维面板的产品。

来源：README + GitHub Releases + package.json

核心功能

OpenAI 兼容 /v1/* 网关与多协议格式翻译

本地 Next.js 服务把 OpenAI Chat、Anthropic Messages、Gemini、OpenAI Responses 四种请求格式以 OpenAI 为中转 hub 互转，统一暴露 /v1/chat/completions、/v1/messages、/v1/responses、/v1/embeddings、/v1/images/generations、/v1/audio/* 等端点。覆盖响应清洗（去除 x_groq、usage_breakdown 等 SDK 不识别字段）、developer→system 角色归一、 标签抽取到 reasoning_content、json_schema→Gemini responseSchema 自动转写。

来源：README + docs/ARCHITECTURE.md (open-sse/translator, open-sse/handlers/responseSanitizer.ts, roleNormalizer.ts)
4 级 Combo 回退与 13 种路由策略

Combo 由「subscription→api key→cheap→free」四档组成，运行时按 priority、weighted、fill-first、round-robin、P2C、cost-optimized、context-relay 等 13 种策略选择具体 Provider+Model+Account 三元组。Quota-aware P2C 会综合配额余量、回退冷却、最近错误、连续命中次数挑账号；context-relay 在跨账号切换时通过 contextHandoff 服务注入摘要保留对话上下文。

来源：README + docs/ARCHITECTURE.md (open-sse/services/combo.ts, accountSelector.ts, contextHandoff.ts)
OAuth 代理与多账号轮转

内建 13 个 OAuth Provider 模块（claude、codex、gemini、qwen、qoder、kiro、cursor、antigravity、kilocode、cline、kimi-coding、github、gemini-cli），实现后台自动 Token Refresh、PKCE 流程、设备码、JWT 提取多账号。配套支持局域网/远程的 redirect_uri 私网检测、Nginx 反向代理下用 window.location.origin 修正、Round-robin 多账号 + JWT/ID Token 抽取，解决 unsupported_country_region_territory 与 redirect_uri_mismatch。

来源：README + docs/ARCHITECTURE.md (src/lib/oauth/providers/, open-sse/services/tokenRefresh.ts)
Provider 弹性：连接冷却、断路器、Wait-For-Cooldown

请求会先经过 Per-connection request bucket 限流，遇到可重试错误进入 Connection Cooldown，遵守上游 Retry-After。多账号同时冷却时支持服务端 Wait-For-Cooldown（可配置 maxRetries / maxRetryWaitSec）等下一个可用窗口；只有在回退链耗尽且整体仍失败时才升级到 Provider 级断路器。配 Anti-thundering-herd mutex+semaphore 防止重试风暴，所有状态写到 domain_circuit_breakers 表实现冷启动恢复。

来源：docs/ARCHITECTURE.md (open-sse/services/rateLimitManager.ts, circuitBreaker.ts, src/sse/services/cooldownAwareRetry.ts)
MCP Server（29 工具）+ A2A JSON-RPC 端

omniroute --mcp 用 stdio/SSE/Streamable HTTP 三种 transport 暴露 29 个工具（健康检查、Combo CRUD、配额查询、缓存管理、Memory/Skills 等），写 SQLite audit 表，10 档 Scope 控制最小权限。同时跑 A2A Server：POST /a2a 走 JSON-RPC 2.0 的 message/send、message/stream、tasks/get、tasks/cancel，配 /.well-known/agent.json Agent Card；MCP 与 A2A 状态卡片直接挂在 /dashboard/endpoint 页。

来源：README + docs/ARCHITECTURE.md (open-sse/mcp-server/*, schemas/a2a.ts)
Dashboard：Combos / Health / Logs / Playground / Analytics

基于 Next.js App Router + React 19 + Recharts 实现 Provider 列表、Combo 步骤化构建器、Translator Playground（含 Chat Tester、Test Bench、Live Monitor 四种调试模式）、Health 页（断路器、冷却、p50/p95/p99 延迟）、Logs 页（Request/Proxy/Audit/Console 四 Tab），并内建 LLM Eval 框架（金集 + exact/contains/regex/custom 4 种判分）。

来源：README + docs/ARCHITECTURE.md (src/app/(dashboard)/dashboard/*)
Embeddings、Images、Audio、Music、Video、Search、Rerank 全栈端点

除聊天补全外，还落地 6 Provider/9+ 模型的 /v1/embeddings、10+ Provider/20+ 模型的 /v1/images/generations、ComfyUI+SD WebUI 的视频/音乐生成、Whisper+Nvidia NIM+ElevenLabs 的语音转写与合成、5 Provider 的 /v1/search、/v1/moderations、/v1/rerank。全部走同一份账号管理、回退、Token 计量管线。

来源：README + docs/ARCHITECTURE.md (open-sse/handlers/{embeddings,imageGeneration,audioSpeech,...})
API Key 管理、SSRF Guard 与 Compliance Audit

本地 API Key 走 HMAC（API_KEY_SECRET），按 Provider+Model 通配限定可访问范围；所有出站 fetch 经 outboundUrlGuard 拦截私网/本机/Link-local 段，URL_GUARD_BLOCKED 走 422 + 审计落库；登录页用 JWT_SECRET 签名 cookie，Settings 端运行时用 Zod 校验环境变量；CSRF + 速率限制 + IP 白/黑名单覆盖 Dashboard 路由。

来源：docs/ARCHITECTURE.md (src/shared/network/outboundUrlGuard.ts, runtimeEnv.ts, providerAudit.ts)

技术架构

整体是一个 Next.js 16 单进程：路由层用 App Router 在 src/app/api/v1/* 暴露 OpenAI 兼容 API，在 src/app/api/* 暴露管理 API，next.config.mjs 把 /v1/* 重写到 /api/v1/*。核心 SSE 与翻译逻辑被拆到 open-sse/ 这个 npm workspace 包（@omniroute/open-sse），通过 transpilePackages 引用：translator/ 注册请求和响应转换器，executors/ 一个文件一个 Provider 实现 BaseExecutor 策略模式（DefaultExecutor 默认覆盖通用 OpenAI 兼容 Provider，CodexExecutor、KiroExecutor、CursorExecutor、AntigravityExecutor 等做特殊认证和协议处理），handlers/ 编排 chatCore、embeddings、imageGeneration 等业务流。所有状态写到 better-sqlite3 的 storage.sqlite（providerConnections、combos、apiKeys、domain_fallback_chains、domain_circuit_breakers、context_handoffs 等 26 个模块），WAL 模式 + 启动迁移 + 旧 JSON→SQLite 兼容。前端 Dashboard 用 React 19 + Tailwind 4 + Recharts + Zustand + Monaco Editor。可选 MCP Server（stdio/SSE/HTTP 三种 transport）、A2A JSON-RPC 端、Electron 桌面壳、Cloudflare Quick Tunnel 共用同一个核心。整体偏「单体路由器+面板」一体化设计：好处是开箱即用、状态都在本地；潜在过度设计的地方在于把 Memory、Skills、A2A、MCP、Eval、Sync Token、WebSocket Bridge 等都塞进同一个 Next.js 进程，模块边界靠目录而非真正的服务隔离，对单人开发者足够，但对要做多租户、横向扩展的团队来说，未来很可能需要把 open-sse 拆成独立可执行进程。

来源：docs/ARCHITECTURE.md + tree.txt + package.json

项目知识图谱

知识图谱：项目核心节点（中心）+ 核心功能（内环六边形）+ 关键技术依赖（外环 chip） better-sqlite3（本地 SQLite，WAL 模式）better-sqlite3… undici + wreq-js + tls-client-node（出站请求与浏览器级 TLS 指纹）undici + wreq-… @modelcontextprotocol/sdk（MCP Server 三种 transport）@modelcontextp… jose + bcryptjs + selfsigned（JWT、密码、自签证书）jose + bcryptj… zod（运行时环境变量与请求 schema 校验）zod（运行时环境… OpenAI 兼容 /v1/* 网关与多协议格式翻译OpenAI 兼容 /v1/*… 4 级 Combo 回退与 13 种路由策略4 级 Combo 回退与 13… OAuth 代理与多账号轮转 Provider 弹性：连接冷却、断路器、Wait-For-CooldownProvider 弹性：连接… MCP Server（29 工具）+ A2A JSON-RPC 端MCP Server（29 工具… Dashboard：Combos / Health / Logs / Playground / AnalyticsDashboard：Combos /… Embeddings、Images、Audio、Music、Video、Search、Rerank 全栈端点Embeddings、Images… API Key 管理、SSRF Guard 与 Compliance AuditAPI Key 管理、SSRF… OmniRoute 项目本体 核心功能 关键依赖

中心为项目本体，内环 = 核心功能模块，外环 = 关键技术依赖；按 deep.json 中的 core_features 与 tech_stack.key_deps 自动生成

技术栈

语言TypeScript（src/）+ JavaScript（open-sse workspace），Node.js >=20.20.2 / >=22.22.2 / >=24框架Next.js 16 (App Router) + React 19 + Express 5（部分 API bridge）+ Electron 桌面壳
关键依赖
better-sqlite3（本地 SQLite，WAL 模式）undici + wreq-js + tls-client-node（出…@modelcontextprotocol/sdk（MCP Server…jose + bcryptjs + selfsigned（JWT、密码、…zod（运行时环境变量与请求 schema 校验）zustand + recharts + monaco-editor +…pino + pino-pretty（结构化日志）next-intl + 41 种语言包（i18n）
基础设施 / 部署
本地 Next.js 单进程，端口 20128（API+Dashboard 同端口或拆分到 20128/20129），SQLite 持久化（DATA_DIR / XDG_CONFIG_HOME / ~/.omniroute），可选 Cloudflare Quick Tunnel 出 HTTPS，Docker 多架构镜像 diegosouzapw/omniroute（AMD64+ARM64，base/cli 两个 profile），Electron 多平台 NSIS/DMG/AppImage 包，CI 走 GitHub Actions（ci/docker-publish/electron-release/npm-publish）
来源：package.json + .github/workflows + docs/ARCHITECTURE.md

快速上手

# 1) 全局安装并启动 npm install -g omniroute omniroute # Dashboard: http://localhost:20128 # API base : http://localhost:20128/v1 # pnpm 用户需先 approve native build： # pnpm install -g omniroute # pnpm approve-builds -g # omniroute # 2) 在 Dashboard 里：Providers 连一个上游（OAuth 或 API key），Endpoints 创建一个 API Key，Combos 配置回退链 # 3) 把任意 OpenAI 兼容工具指过来 Base URL: http://localhost:20128/v1 API Key: [Endpoints 页面复制] Model: if/kimi-k2-thinking # 任意 provider/model 前缀 # 4) 启用 MCP / A2A（可选） omniroute --mcp # MCP stdio transport curl http://localhost:20128/.well-known/agent.json # A2A Agent Card # 5) Docker 一键起 docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 20128:20128 -v omniroute-data:/app/data \ diegosouzapw/omniroute:latest # 6) 从源码运行（开发） cp .env.example .env npm install PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev # 7) 卸载 npm run uninstall # 保留 ~/.omniroute 数据 npm run uninstall:full # 连配置和数据库一起清掉
来源：README

使用场景

1) 已经在用 Claude Code / Codex CLI / Gemini CLI 的开发者，把订阅额度榨干后自动 fallback 到 GLM、Kimi、MiniMax 这种低价 API，再兜底到 Qoder、Kiro、Qwen 等免费档，避免「订阅周限到了就停工」。 2) 国内或受限地区用户，需要本地部署、配置 SOCKS5/HTTP 代理、走 OAuth 还能正确处理 unsupported_country_region_territory 的网关。 3) 个人用户搭「$0/月编程栈」：把 Kiro+Qoder+Qwen+Gemini CLI+Cloudflare AI+NVIDIA NIM 等 11 个免费 Provider 串成一个 Combo，纯免费跑 Cursor / Cline / OpenClaw。 4) 团队或工作室自部署 Agent ops：通过 MCP Server 暴露 29 个运维工具给 Claude Code/Codex 使用，配 A2A 跑长 Task，把 Combo 切换、断路器复位、配额查看做成 Agent 操作。

来源：README + 综合分析

优势与局限

优势

  • 覆盖面真大：单仓库支持 160+ Provider、16 个 Executor、4 级 Combo、Embedding/Image/Audio/Video/Music/Search/Rerank 七类多模态端点，是目前少有把「网关 + 控制台」做完整的开源项目。
  • 运维友好：Dashboard 把 Combo、Health（断路器 + p50/p95/p99）、Logs（Request/Proxy/Audit/Console）、Playground（Chat/Test Bench/Live Monitor）、Eval、API Key 全部图形化，加上 Compliance Audit v2 的分页 + SSRF 拦截审计，远超大多数代理脚本。
  • 协议层做得细：OpenAI 作为 hub 中转 4 种格式、响应清洗剥离 SDK 不识别字段、 → reasoning_content 抽取、json_schema → Gemini responseSchema、role normalization 等都解决了真实跨 Provider 兼容坑，README 里 30 个 Pain Points 多数有对应代码模块。
  • 弹性策略层次清晰：Connection Cooldown → Account Fallback → Combo Fallback → Provider Circuit Breaker 是有真分层的，配上 Quota-aware P2C、Context-Relay handoff、Anti-thundering-herd mutex，比简单的「失败就轮下一个」高一级。
  • 工程化齐全：CI 含 ci/docker-publish/electron-release/npm-publish 4 条线、test:unit + vitest + e2e + ecosystem 多套测试、husky + lint-staged + prettier + eslint + tsc 严格 typecheck-core 配置、npm package 通过 prepublishOnly + check:pack-artifact 校验，发布纪律远超个人项目水平。
  • 近 1 年迭代非常活跃：从 README 中可见 v2.0.x → v3.7.x 的清晰演进，新模型（GPT-5.5、Grok-4 Fast、GLM-5、MiniMax M2.5）和新 Provider（CrofAI、Pollinations、LongCat、Scaleway、Cloudflare AI）几乎跟随上游同周加入。

局限

  • 可维护性：单一 Next.js 进程把 OpenAI 代理、MCP Server、A2A 端、Memory/Skills、Sync Token、WebSocket Bridge、Electron 主进程都绑在一起，模块边界靠目录划分，未来想拆服务或独立部署 open-sse 难度不小；docs/ARCHITECTURE.md 自己也提到 README/CHANGELOG 与代码同步靠 check:docs-sync 脚本兜底，说明已经感受到文档漂移压力。
  • 可扩展性：新增协议（如未来某个 Provider 走非 SSE 的二进制流）时需要在 executors/、translator/、handlers/ 三处同时改动；executors 已经达到 16+ 个文件，部分如 Cursor 的 Protobuf+Checksum、Kiro 的 EventStream、Antigravity 的 429 引擎都各自实现了一套，缺一个统一抽象，长期维护成本会上升。
  • 可测试性：tests/unit 偏单元，整套 Combo + Account Fallback + Circuit Breaker + Context-Relay 这种跨模块场景主要靠 e2e（playwright）+ ecosystem 套件覆盖，CI 把 coverage 阈值设在 60%（statements/lines/functions/branches），对一个金融级路由网关来说不算高；TLS 指纹、OAuth 设备码、Codex Quota 这些与上游强耦合的路径很难在纯 mock 下回归。
  • 稳定性风险：项目内置「TLS 指纹伪装 + CLI Header 重排」绕过 Provider 反爬（README 第 3 条），账号被风控的合规风险存在；OAuth 模块跟着上游协议变（Qwen 4.15 已被标 deprecated）的速度很快，一旦上游改 endpoint 就需要紧急发版，对生产部署是慢性疼痛。
  • 性能：所有路由决策、Combo 选择、断路器状态、缓存命中查询都同步访问 better-sqlite3（虽然走 in-memory write-through），单进程 Node.js 在高 QPS 多路并发流式时受 V8 单线程限制；README 与 docs 都没给出实测的 RPS / p99 / 内存上限，水平扩展手段（如多实例间共享冷却状态）也未提及。
  • 门槛与产品定位摇摆：界面把 41 种语言、Memory/Skills、A2A、MCP、Eval、Sync Token 等新模块都堆出来，对纯粹想要「免费版 Claude Code」的用户来说选项过载；同时项目同时维护 npm 全局安装、Docker base/cli 双 profile、Electron 三平台、AUR 包、Void Linux 模板，多形态发布对小团队是甜蜜负担。
来源：综合分析（基于 README + docs/ARCHITECTURE.md + package.json + tree.txt + GitHub Releases）

最新版本

v3.7.1（2026-04-27 发布）：Codex Provider 新增 GPT-5.5（1.05M 上下文 + 工具调用 + 视觉 + 推理，cx/openai 双前缀加价目）；新增 omniroute reset-encrypted-columns CLI 把 provider_connections 中 api_key/access_token/refresh_token/id_token 加密列重置（修复 #1622）；i18n 增加 9 种语言包（孟加拉/波斯/古吉拉特/印尼/马拉地/斯瓦希里/泰米尔/泰卢固/乌尔都），合计 41 种。同时修复 GitHub Copilot 单模型 429 误锁整连接、OpenCode 配置保存破坏 MCP/自定义 Provider/注释、API Key 复制误用掩码等。上一版 v3.7.0（2026-04-26）引入 ChatGPT Web 图像生成 + 缓存、CrofAI 内建 Provider、OpenCode Zen/Go logo。

来源：GitHub Releases

总结评价

OmniRoute 当前是开源 LLM 网关里把「免费/低价路由」做得最完整、运维面板最齐的一个。如果你正在用 Claude Code、Codex CLI、Cursor、Cline 这类 OpenAI/Anthropic 兼容的编程工具，又想把 Anthropic / OpenAI 订阅额度用满后自动 fallback 到 GLM、Kimi、MiniMax、Qoder、Kiro、Gemini CLI，那它确实能让你「永不停工」，特别是配合 4 级 Combo 和 13 种调度策略。建议从 npm 全局安装起步，先在 Dashboard 里跑通 1-2 个 OAuth Provider + 1 个 Combo，再逐步把 MCP、A2A、Eval 这些进阶模块开起来；生产/团队部署优先用 Docker base 镜像并把 DATA_DIR 挂出来，避免 SQLite 数据丢失。不太适合三类人：① 只想要一个最小化、稳定不动的 OpenAI 反代脚本——OmniRoute 的功能矩阵和发版节奏都太密集；② 需要严格合规、不允许伪装 TLS 指纹或绕过区域限制的企业；③ 高 QPS、要做多实例水平扩展的服务化场景，目前架构里冷却/断路器状态依赖单进程 SQLite，上多实例需要自己拆。先试 7 天免费 Combo 跑日常编码，再决定要不要接入到团队内部。

来源：综合分析
透明度声明
本页内容由 AI（大语言模型）基于以下公开材料自动生成：GitHub README、代码目录结构、依赖文件、Release 信息。 分析时间: 2026-04-28 01:28. 质量评分: 100/100.

数据来源：README、GitHub API、依赖文件