OmniRoute 代码库全景解析OpenAI 枢纽式格式翻译、策略模式执行器与有状态 SSE 流管道【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文以 OmniRoute 仓库中的代码库文档 CODEBASE_DOCUMENTATION.md罗马尼亚语版本位于 docs/i18n/ro/docs/architecture/CODEBASE_DOCUMENTATION.md为主体完整梳理这个多提供商 AI 代理路由器的核心架构以 OpenAI 格式为枢纽hub-and-spoke的格式翻译体系、基于策略模式Strategy Pattern的提供商执行器、自注册翻译插件系统以及有状态的 SSE 流式翻译管道。读完本文你可以准确说出一个请求从 Claude CLI 进入、经chatCore编排、格式转换、执行器下发到 Anthropic/Gemini/Cursor 等上游、再逐块翻译回来的完整生命周期并能在仓库中定位到每一层对应的源码文件。1. OmniRoute 是什么AI 客户端与提供商之间的通用翻译官OmniRoute 是一个代理路由器proxy router运行在 AI 客户端Claude CLI、Codex、Cursor IDE 等与 AI 提供商Anthropic、Google、OpenAI、AWS、GitHub 等之间。它解决的核心问题是不同的 AI 客户端使用不同的语言API 格式不同的 AI 提供商也期望不同的语言。OmniRoute 在两者之间自动完成格式翻译。可以把它想象成联合国的同声传译员任何一位代表都可以说任何语言翻译官负责为另一位代表转译。OmniRoute 正是这样一个API 格式联合国——左侧是各家客户端各自的请求格式右侧是各家提供商各自的请求/响应格式中间由翻译层、执行层和服务层协同完成协议转换、凭证管理与弹性降级。2. 架构总览四层结构 枢纽式翻译2.1 整体架构图原文档给出的核心架构如下客户端 → OmniRoute 四层 → 提供商四个分层职责清晰Handler Layer处理层请求编排的中枢负责完整生命周期调度Translator Layer翻译层请求/响应体在不同格式间转换Executor Layer执行层提供商专属的请求构建、认证与重试逻辑Services Layer服务层横切的业务逻辑认证刷新、模型解析、回退、用量统计等以虚线方式支撑 Handler 与 Executor。2.2 核心原则Hub-and-Spoke 翻译所有格式翻译都以OpenAI 格式为枢纽hubClient Format → [OpenAI Hub] → Provider Format (请求方向) Provider Format → [OpenAI Hub] → Client Format (响应方向)这一设计的关键收益新增一种格式只需要编写N 个翻译器每种格式一对 to/from OpenAI而不是N²个每对组合各一个。例如 Claude ↔ Gemini 的互转不需要专门实现而是Claude → OpenAI → Gemini两跳完成。3. 项目目录结构原文档给出的目录骨架结合当前仓库实际状态说明omniroute/ ├── open-sse/ ← 核心代理库可移植、框架无关 │ ├── index.ts ← 主入口导出全部公共 API │ ├── config/ ← 配置与常量 │ ├── executors/ ← 提供商专属请求执行 │ ├── handlers/ ← 请求处理编排 │ ├── services/ ← 业务逻辑认证、模型、回退、用量 │ ├── translator/ ← 格式翻译引擎 │ │ ├── request/ ← 请求翻译器 │ │ ├── response/ ← 响应翻译器 │ │ └── helpers/ ← 共享翻译工具 │ └── utils/ ← 工具函数 ├── src/ ← 应用层Express/Worker 运行时 │ ├── app/ ← Web UI、API 路由、中间件 │ ├── lib/ ← 数据库、认证与共享库代码 │ ├── mitm/ ← 中间人代理工具 │ ├── models/ ← 数据库模型 │ ├── shared/ ← 共享工具open-sse 的封装 │ ├── sse/ ← SSE 端点处理器 │ └── store/ ← 状态管理 ├── data/ ← 运行期数据凭证、日志 │ └── provider-credentials.json (外部凭证覆盖gitignored) └── tester/ ← 测试工具需要指出的两点事实核心库入口在当前仓库中是 open-sse/index.tsTypeScript 源码而非文档早期版本中的index.jsopen-sse被设计为可移植、框架无关的库——它不依赖 Express认证、翻译、执行全部封装在内应用层src/通过src/shared/的薄封装把 open-sse 接到 Express 路由上。这正是库与应用分层的直接体现。4. 核心模块逐一拆解4.1 Config 层open-sse/config/提供商配置的单一事实来源文件职责constants.tsPROVIDERS对象所有提供商的 base URL、OAuth 凭证默认值、请求头、默认系统提示词另定义HTTP_STATUS、ERROR_TYPES、COOLDOWN_MS、BACKOFF_CONFIG、SKIP_PATTERNScredentialLoader.ts从data/provider-credentials.json读取外部凭证覆盖合并到硬编码默认值之上把密钥移出源码控制同时保持向后兼容providerModels.ts中央模型注册表提供商别名 → 模型 ID 映射getModels()、getProviderByAlias()等查询函数codexInstructions.ts注入 Codex 请求的系统指令编辑约束、沙箱规则、审批策略defaultThinkingSignature.tsClaude 与 Gemini 模型的默认 thinking 签名ollamaModels.ts本地 Ollama 模型的 Schema 定义名称、体积、家族、量化上述导出均可在入口文件得到印证open-sse/index.ts 从config/constants.ts导出PROVIDERS、OAUTH_ENDPOINTS、CACHE_TTL、DEFAULT_MAX_TOKENS、CLAUDE_SYSTEM_PROMPT、COOLDOWN_MS、BACKOFF_CONFIG并在 L14-L23 导出PROVIDER_MODELS、getProviderModels、isValidModel、getModelTargetFormat等模型注册表 API。凭证加载流程这个流程的设计意图是源码里保留一份可工作的默认凭证便于零配置启动部署时用data/provider-credentials.json该文件被 gitignore逐字段覆盖clientId、clientSecret、tokenUrl、authUrl、refreshUrl实现密钥不落库。加载实现位于 open-sse/config/credentialLoader.ts。4.2 Executorsopen-sse/executors/策略模式封装提供商差异执行器用**策略模式Strategy Pattern**封装每个提供商的专属逻辑每个执行器继承BaseExecutor按需重写基础方法。类结构如下核心执行器一览对应 open-sse/executors/ 目录执行器提供商关键特化base.ts—抽象基类URL 构建、请求头、重试逻辑、凭证刷新default.tsClaude、Gemini、OpenAI、GLM、Kimi、MiniMax标准提供商的通用 OAuth token 刷新antigravity.tsGoogle Cloud Code项目/会话 ID 生成、多 URL 回退、从错误消息文本解析自定义重试时间如 reset after 2h7m23scursor.tsCursor IDE最复杂SHA-256 校验和认证、Protobuf 请求编码、二进制 EventStream → SSE 响应解析codex.tsOpenAI Codex注入系统指令、管理 thinking 级别、剔除不支持的参数github.tsGitHub Copilot双 token 体系GitHub OAuth Copilot token、VSCode 请求头模拟kiro.tsAWS CodeWhispererAWS EventStream 二进制解析、AMZN 事件帧、token 估算index.ts—工厂提供商名 → 执行器类的映射带默认回退这些文件在当前仓库中均实际存在base.ts、default.ts、antigravity.ts、cursor.ts、codex.ts、github.ts、kiro.ts、index.ts。需要说明的是随着项目演进executors/目录已扩展到 100 个文件新增了大量 Web 系与新兴提供商执行器上表覆盖的是文档描述的核心执行器集合index.ts工厂的默认回退机制正是新增提供商不必改动调度代码的原因。4.3 Handlersopen-sse/handlers/编排层Handler 是编排层负责协调翻译、执行、流式传输与错误处理。核心 Handler文件职责chatCore.ts中央编排器约 600 行。处理完整请求生命周期格式检测 → 翻译 → 执行器分发 → 流式/非流式响应 → token 刷新 → 错误处理 → 用量记录responsesHandler.tsOpenAI Responses API 适配器Responses 格式 → Chat Completions → 交给chatCore→ 再把 SSE 转回 Responses 格式embeddings.ts嵌入生成解析 embedding 模型 → 提供商分发到提供商 API返回 OpenAI 兼容的嵌入响应支持 6 提供商imageGeneration.ts图像生成解析图像模型 → 提供商支持 OpenAI 兼容、Gemini-imageAntigravity与回退Nebius模式返回 base64 或 URL 图像对应源码chatCore.ts、responsesHandler.ts、embeddings.ts、imageGeneration.ts。chatCore 的请求生命周期从源码结构看open-sse/handlers/目录下还包含autoComboCandidates.ts、responseSanitizer.ts、usageExtractor.ts、search/、videoGeneration/、rerank.ts等文件说明 Handler 层在文档描述的基础上继续吸收了音频、检索、多模态生成等能力但chatCore的上述生命周期仍是主干路径。4.4 Servicesopen-sse/services/支撑 Handler 与 Executor 的业务逻辑文件职责provider.ts格式检测detectFormat分析请求体结构识别 Claude/OpenAI/Gemini/Antigravity/Responses 格式含用max_tokens字段作 Claude 判断启发式。另有 URL 构建、请求头构建、thinking 配置归一化。支持openai-compatible-*与anthropic-compatible-*动态提供商model.ts模型串解析claude/model-name→{provider: claude, model: model-name}、带冲突检测的别名解析、输入净化拒绝路径穿越/控制字符、支持异步别名 getter 的模型信息解析accountFallback.ts限流处理指数退避1s → 2s → 4s → 上限 2min、账户冷却管理、错误分类哪些错误触发回退tokenRefresh.ts全部提供商的 OAuth token 刷新GoogleGemini、Antigravity、Claude、Codex、Qwen、Qoder、GitHubOAuth Copilot 双 token、KiroAWS SSO OIDC Social Auth含 in-flight Promise 去重缓存与指数退避重试combo.tsCombo 模型回退模型链。模型 A 遇到可回退错误时尝试 B再尝试 C……返回真实的上游状态码usage.ts从提供商 API 拉取配额/用量数据GitHub Copilot 配额、Antigravity 模型配额、Codex 速率限制、Kiro 用量明细、Claude 设置accountSelector.ts智能账户选择评分算法综合优先级、健康状态、轮询位置与冷却状态为每个请求选出最优账户contextManager.ts请求上下文生命周期管理创建并跟踪每个请求的上下文对象请求 ID、时间戳、提供商信息用于调试与日志ipFilter.ts基于 IP 的访问控制支持 allowlist 与 blocklist 模式在处理 API 请求前校验客户端 IPsessionManager.ts客户端指纹化的会话跟踪用哈希客户端标识跟踪活跃会话、统计请求数、提供会话指标signatureCache.ts基于请求签名的去重缓存缓存近期请求签名在时间窗口内对相同请求返回缓存响应systemPrompt.ts全局系统提示词注入为所有请求前置或追加可配置系统提示词并做每提供商的兼容性处理thinkingBudget.ts推理 token 预算passthrough直通、auto剥离 thinking 配置、custom固定预算、adaptive按复杂度缩放四种模式wildcardRouter.ts通配符模型模式路由把通配模式如*/claude-*按可用性与优先级解析为具体的提供商/模型对以上 14 个服务文件在当前仓库的 open-sse/services/ 目录中全部存在该目录目前已扩展至 250 个条目含各提供商的配额抓取器、限流管理器、压缩引擎等detectFormat、parseModel、checkFallbackError、refreshAccessToken等核心 API 均可从 open-sse/index.ts 的导出清单逐一核对。Token 刷新的 in-flight 去重并发请求同时发现 token 过期时tokenRefresh.ts用共享 Promise 缓存保证只发起一次刷新实现位于 open-sse/services/tokenRefresh.ts入口导出还包含TOKEN_EXPIRY_BUFFER_MS提前刷新缓冲见 open-sse/index.ts。账户回退状态机关键语义400 不触发回退请求本身有问题换账户也无意义而 401/429/500 等错误先分类、后决定回退。冷却时间从 1s 指数增长到 2 分钟上限请求成功则重置退避级别。对应实现见 open-sse/services/accountFallback.ts其导出的isProviderInCooldown、getProviderCooldownRemainingMs、getProvidersInCooldown等函数见 open-sse/index.ts为上层提供了冷却状态的查询能力。Combo 模型链Combo 把多个provider/model串组织成一条有序回退链与账户级回退不同这里切换的是模型本身且最终向客户端返回的是最后一个模型的真实上游状态码而不是笼统的 502便于客户端区分上游限流与网关故障。实现见 open-sse/services/combo.ts。4.5 Translatoropen-sse/translator/自注册插件式格式翻译引擎翻译引擎是 OmniRoute 的技术核心采用自注册插件系统目录组织目录/文件说明request/请求体翻译器。每个文件在 import 时通过register(from, to, fn)自我注册。当前仓库中已扩展出openai-to-claude/、openai-to-gemini/、openai-responses/等子目录承载大型翻译逻辑response/流式响应块翻译器。处理 SSE 事件类型、thinking 块、工具调用。当前仓库含claude-to-openai.ts、gemini-to-openai.ts、kiro-to-openai.ts、cursor-to-openai.ts、openai-to-antigravity.ts、openai-to-claude.ts、openai-to-gemini.ts等helpers/共享工具claudeHelper系统提示词提取、thinking 配置、geminiHelperparts/contents 映射、openaiHelper格式过滤、toolCallHelperID 生成、缺失响应注入、maxTokensHelper、responsesApiHelperindex.ts翻译引擎主体translateRequest()、translateResponse()、状态管理、注册表formats.ts格式常量OPENAI、CLAUDE、GEMINI、ANTIGRAVITY、KIRO、CURSOR、OPENAI_RESPONSES关键设计自注册插件源码印证这个import 即注册的机制在仓库中可以直接读到。open-sse/translator/registry.ts 维护两张以from:to为键的 Map// registry.ts节选 const requestRegistry new Mapstring, RequestTranslator(); const responseRegistry new Mapstring, ResponseTranslator(); function makeKey(from: string, to: string) { return ${from}:${to}; } export function register( from: string, to: string, requestFn?: RequestTranslator, responseFn?: ResponseTranslator ) { const key makeKey(from, to); if (requestFn) requestRegistry.set(key, requestFn); if (responseFn) responseRegistry.set(key, responseFn); }每个翻译器文件在模块顶层调用register()// 翻译器文件在 import 时自我注册 import { register } from ../index.js; register(claude, openai, translateClaudeToOpenAI); // index 导入所有翻译器文件触发注册 import ./request/claude-to-openai.js; // ← 自注册注册表同时支持请求与响应两种函数签名RequestTranslator接收(model, body, stream?, credentials?)ResponseTranslator接收(chunk, state)——后者传入的state正是有状态流式翻译的载体见第 5.6 节。格式常量定义在 open-sse/translator/formats.ts除文档列出的七种格式外当前仓库还新增了CLOVA与CODEX两个标识。4.6 Utilsopen-sse/utils/SSE 流管道与配套工具文件职责error.tsOpenAI 兼容格式的错误响应构建、上游错误解析、从 Antigravity 错误消息中提取重试时间、SSE 错误流式输出stream.tsSSE Transform Stream——流式管道核心。两种模式TRANSLATE完整格式翻译与PASSTHROUGH归一化 提取 usage。处理块缓冲、usage 估算、内容长度跟踪。每路流独享 encoder/decoder 实例避免共享状态streamHelpers.ts底层 SSE 工具parseSSELine容忍空白字符、hasValuableContent过滤 OpenAI/Claude/Gemini 的空块、fixInvalidId、formatSSE格式感知的 SSE 序列化含perf_metrics清理usageTracking.ts从任意格式Claude/OpenAI/Gemini/Responses提取 token 用量tool/message 分离的字符/token 比率估算缓冲叠加2000 token 安全边际按格式过滤字段带 ANSI 颜色的控制台日志requestLogger.ts遗留的文件式请求日志助手为兼容性保留。当前部署建议用APP_LOG_TO_FILE输出应用日志、用调用日志call log管道持久化请求工件bypassHandler.ts拦截 Claude CLI 的特定模式标题提取、warmup、count 请求不触达任何提供商直接返回伪造响应支持流式与非流式。有意限定在 Claude CLI 范围内networkProxy.ts为指定提供商解析出站代理 URL优先级提供商专属配置 → 全局配置 → 环境变量HTTPS_PROXY/HTTP_PROXY/ALL_PROXY支持NO_PROXY排除配置缓存 30s以上文件均实际存在于 open-sse/utils/error.ts、stream.ts、streamHelpers.ts、usageTracking.ts、requestLogger.ts、bypassHandler.ts、networkProxy.ts。SSE 流式管道两个实现细节值得注意一是每路流独享 TextDecoder/TextEncoder 实例因为解码器是有状态的处理多字节字符跨 chunk 的情况多路流共享会互相污染二是空块过滤hasValuableContent针对各格式无内容 chunk的形态差异单独判定防止客户端收到无意义的data: {}。请求日志的会话目录结构logs/ └── claude_gemini_claude-sonnet_20260208_143045/ ├── 1_req_client.json ← 客户端原始请求 ├── 2_req_source.json ← 初次转换后 ├── 3_req_openai.json ← OpenAI 中间格式 ├── 4_req_target.json ← 最终目标格式 ├── 5_res_provider.txt ← 提供商 SSE 块 (流式) ├── 5_res_provider.json ← 提供商响应 (非流式) ├── 6_res_openai.txt ← OpenAI 中间块 ├── 7_res_client.txt ← 面向客户端的 SSE 块 └── 6_error.json ← 错误详情 (如有)这套编号目录是排查翻译问题的黑匣子把请求翻译链的四个中间态与响应的三个观测点全部落盘任何一环的格式偏差都可以精确定位。4.7 应用层src/目录职责src/app/Web UI、API 路由、Express 中间件、OAuth 回调处理器src/lib/数据库访问localDb.ts、usageDb.ts、认证、共享代码src/mitm/中间人代理工具拦截提供商流量src/models/数据库模型定义src/shared/open-sse 函数的封装层provider、stream、error 等src/sse/把 open-sse 库接到 Express 路由的 SSE 端点处理器src/store/应用状态管理代表性 API 路由路由方法用途/api/provider-modelsGET/POST/DELETE每提供商自定义模型的 CRUD/api/models/catalogGET按提供商分组的全部模型聚合目录chat、embedding、image、custom/api/settings/proxyGET/PUT/DELETE分层出站代理配置global/providers/combos/keys/api/settings/proxy/testPOST校验代理连通性并返回公网 IP/延迟/v1/providers/[provider]/chat/completionsPOST每提供商专属 chat completions含模型校验/v1/providers/[provider]/embeddingsPOST每提供商专属 embeddings含模型校验/v1/providers/[provider]/images/generationsPOST每提供商专属图像生成含模型校验/api/settings/ip-filterGET/PUTIP 白名单/黑名单管理/api/settings/thinking-budgetGET/PUT推理 token 预算配置passthrough/auto/custom/adaptive/api/settings/system-promptGET/PUT面向所有请求的全局系统提示词注入/api/sessionsGET活跃会话跟踪与指标/api/rate-limitsGET每账户速率限制状态这些路由把 4.4 节的服务层能力IP 过滤、thinking 预算、系统提示词、会话、限流以 REST 形式暴露给管理面板形成服务层 ↔ API 路由的完整闭环。5. 关键设计模式汇总原文档归纳了七个设计模式逐一说明其工程收益Hub-and-Spoke 翻译所有格式经由 OpenAI 格式枢纽互转新增提供商只需写一对to/from OpenAI翻译器复杂度从 N² 降到 NExecutor 策略模式每个提供商一个继承自BaseExecutor的专属执行器类executors/index.ts中的工厂在运行时按需选择自注册插件系统翻译模块 import 时经register()自我登记新增翻译器只需创建文件并 import注册表实现见 open-sse/translator/registry.ts指数退避的账户回退429/401/500 时可切换下一账户冷却时间 1s → 2s → 4s → 上限 2minCombo 模型链一个 combo 聚合多个provider/model串首个失败自动回退到下一个有状态流式翻译响应翻译通过initState()机制在 SSE 块之间维护状态thinking 块跟踪、工具调用累积、内容块索引用量安全缓冲上报的 usage 上叠加 2000 token 缓冲防止客户端因系统提示词与格式翻译的开销而触到上下文窗口上限。6. 支持的格式格式方向标识符OpenAI Chat Completionssource targetopenaiOpenAI Responses APIsource targetopenai-responsesAnthropic Claudesource targetclaudeGoogle Geminisource targetgeminiAntigravitysource targetantigravityAWS Kiro仅 targetkiroCursor仅 targetcursorKiro 与 Cursor 只作为 target是因为它们没有可供客户端使用的标准请求格式——只能把别的格式翻译成它们的私有格式而不能从它们那里接受客户端请求。格式标识符常量定义见 open-sse/translator/formats.ts。7. 支持的提供商提供商认证方式执行器关键说明Anthropic ClaudeAPI key 或 OAuthDefault使用x-api-key头Google GeminiAPI key 或 OAuthDefault使用x-goog-api-key头AntigravityOAuthAntigravity多 URL 回退、自定义重试解析OpenAIAPI keyDefault标准 Bearer 认证CodexOAuthCodex注入系统指令、管理 thinkingGitHub CopilotOAuth Copilot tokenGithub双 token、VSCode 头模拟Kiro (AWS)AWS SSO OIDC 或 SocialKiro二进制 EventStream 解析Cursor IDE校验和认证CursorProtobuf 编码、SHA-256 校验和QwenOAuthDefault标准认证QoderOAuth (Basic Bearer)Default双认证头OpenRouterAPI keyDefault标准 Bearer 认证GLM、Kimi、MiniMaxAPI keyDefaultClaude 兼容使用x-api-keyopenai-compatible-*API keyDefault动态任意 OpenAI 兼容端点anthropic-compatible-*API keyDefault动态任意 Claude 兼容端点openai-compatible-*/anthropic-compatible-*是动态提供商detectFormat与 URL/请求头构建逻辑在运行期按别名前缀解析见 open-sse/services/provider.ts无需为每个私有部署单独写执行器。8. 数据流总览8.1 流式请求8.2 非流式请求8.3 Bypass 流程Claude CLIClaude CLI 启动时会发出几类元请求提取会话标题、连接预热、token 计数它们不消耗任何真实推理。bypassHandler在 Handler 层之前把这些请求拦截下来直接按目标格式生成伪造响应返回既省配额又加快 CLI 启动——实现见 open-sse/utils/bypassHandler.ts。9. 延伸阅读在仓库中继续深入入口与公共 API 总览open-sse/index.ts翻译注册表与引擎open-sse/translator/registry.ts、open-sse/translator/index.ts、open-sse/translator/formats.ts中央编排器open-sse/handlers/chatCore.ts执行器工厂与基类open-sse/executors/index.ts、open-sse/executors/base.ts弹性与回退open-sse/services/accountFallback.ts、open-sse/services/tokenRefresh.ts、open-sse/services/combo.ts流式管道open-sse/utils/stream.ts、open-sse/utils/usageTracking.ts架构配套文档同目录ARCHITECTURE.md、ROUTER_BACKENDS.md、ADAPTIVE_ROUTING.md英文版原始文档docs/architecture/CODEBASE_DOCUMENTATION.md需要说明适用前提本文以当前仓库快照为准open-sse核心库、src/应用层的分层结构稳定但executors/与services/的规模仍在快速增长文档表格覆盖的是核心模块集合新增提供商按同一套策略模式与注册机制扩展文档中的数字如翻译器文件数为撰写时的快照值以仓库实际目录为准。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OmniRoute 代码库全景解析：OpenAI 枢纽式格式翻译、策略模式执行器与有状态 SSE 流管道
OmniRoute 代码库全景解析OpenAI 枢纽式格式翻译、策略模式执行器与有状态 SSE 流管道【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文以 OmniRoute 仓库中的代码库文档 CODEBASE_DOCUMENTATION.md罗马尼亚语版本位于 docs/i18n/ro/docs/architecture/CODEBASE_DOCUMENTATION.md为主体完整梳理这个多提供商 AI 代理路由器的核心架构以 OpenAI 格式为枢纽hub-and-spoke的格式翻译体系、基于策略模式Strategy Pattern的提供商执行器、自注册翻译插件系统以及有状态的 SSE 流式翻译管道。读完本文你可以准确说出一个请求从 Claude CLI 进入、经chatCore编排、格式转换、执行器下发到 Anthropic/Gemini/Cursor 等上游、再逐块翻译回来的完整生命周期并能在仓库中定位到每一层对应的源码文件。1. OmniRoute 是什么AI 客户端与提供商之间的通用翻译官OmniRoute 是一个代理路由器proxy router运行在 AI 客户端Claude CLI、Codex、Cursor IDE 等与 AI 提供商Anthropic、Google、OpenAI、AWS、GitHub 等之间。它解决的核心问题是不同的 AI 客户端使用不同的语言API 格式不同的 AI 提供商也期望不同的语言。OmniRoute 在两者之间自动完成格式翻译。可以把它想象成联合国的同声传译员任何一位代表都可以说任何语言翻译官负责为另一位代表转译。OmniRoute 正是这样一个API 格式联合国——左侧是各家客户端各自的请求格式右侧是各家提供商各自的请求/响应格式中间由翻译层、执行层和服务层协同完成协议转换、凭证管理与弹性降级。2. 架构总览四层结构 枢纽式翻译2.1 整体架构图原文档给出的核心架构如下客户端 → OmniRoute 四层 → 提供商四个分层职责清晰Handler Layer处理层请求编排的中枢负责完整生命周期调度Translator Layer翻译层请求/响应体在不同格式间转换Executor Layer执行层提供商专属的请求构建、认证与重试逻辑Services Layer服务层横切的业务逻辑认证刷新、模型解析、回退、用量统计等以虚线方式支撑 Handler 与 Executor。2.2 核心原则Hub-and-Spoke 翻译所有格式翻译都以OpenAI 格式为枢纽hubClient Format → [OpenAI Hub] → Provider Format (请求方向) Provider Format → [OpenAI Hub] → Client Format (响应方向)这一设计的关键收益新增一种格式只需要编写N 个翻译器每种格式一对 to/from OpenAI而不是N²个每对组合各一个。例如 Claude ↔ Gemini 的互转不需要专门实现而是Claude → OpenAI → Gemini两跳完成。3. 项目目录结构原文档给出的目录骨架结合当前仓库实际状态说明omniroute/ ├── open-sse/ ← 核心代理库可移植、框架无关 │ ├── index.ts ← 主入口导出全部公共 API │ ├── config/ ← 配置与常量 │ ├── executors/ ← 提供商专属请求执行 │ ├── handlers/ ← 请求处理编排 │ ├── services/ ← 业务逻辑认证、模型、回退、用量 │ ├── translator/ ← 格式翻译引擎 │ │ ├── request/ ← 请求翻译器 │ │ ├── response/ ← 响应翻译器 │ │ └── helpers/ ← 共享翻译工具 │ └── utils/ ← 工具函数 ├── src/ ← 应用层Express/Worker 运行时 │ ├── app/ ← Web UI、API 路由、中间件 │ ├── lib/ ← 数据库、认证与共享库代码 │ ├── mitm/ ← 中间人代理工具 │ ├── models/ ← 数据库模型 │ ├── shared/ ← 共享工具open-sse 的封装 │ ├── sse/ ← SSE 端点处理器 │ └── store/ ← 状态管理 ├── data/ ← 运行期数据凭证、日志 │ └── provider-credentials.json (外部凭证覆盖gitignored) └── tester/ ← 测试工具需要指出的两点事实核心库入口在当前仓库中是 open-sse/index.tsTypeScript 源码而非文档早期版本中的index.jsopen-sse被设计为可移植、框架无关的库——它不依赖 Express认证、翻译、执行全部封装在内应用层src/通过src/shared/的薄封装把 open-sse 接到 Express 路由上。这正是库与应用分层的直接体现。4. 核心模块逐一拆解4.1 Config 层open-sse/config/提供商配置的单一事实来源文件职责constants.tsPROVIDERS对象所有提供商的 base URL、OAuth 凭证默认值、请求头、默认系统提示词另定义HTTP_STATUS、ERROR_TYPES、COOLDOWN_MS、BACKOFF_CONFIG、SKIP_PATTERNScredentialLoader.ts从data/provider-credentials.json读取外部凭证覆盖合并到硬编码默认值之上把密钥移出源码控制同时保持向后兼容providerModels.ts中央模型注册表提供商别名 → 模型 ID 映射getModels()、getProviderByAlias()等查询函数codexInstructions.ts注入 Codex 请求的系统指令编辑约束、沙箱规则、审批策略defaultThinkingSignature.tsClaude 与 Gemini 模型的默认 thinking 签名ollamaModels.ts本地 Ollama 模型的 Schema 定义名称、体积、家族、量化上述导出均可在入口文件得到印证open-sse/index.ts 从config/constants.ts导出PROVIDERS、OAUTH_ENDPOINTS、CACHE_TTL、DEFAULT_MAX_TOKENS、CLAUDE_SYSTEM_PROMPT、COOLDOWN_MS、BACKOFF_CONFIG并在 L14-L23 导出PROVIDER_MODELS、getProviderModels、isValidModel、getModelTargetFormat等模型注册表 API。凭证加载流程这个流程的设计意图是源码里保留一份可工作的默认凭证便于零配置启动部署时用data/provider-credentials.json该文件被 gitignore逐字段覆盖clientId、clientSecret、tokenUrl、authUrl、refreshUrl实现密钥不落库。加载实现位于 open-sse/config/credentialLoader.ts。4.2 Executorsopen-sse/executors/策略模式封装提供商差异执行器用**策略模式Strategy Pattern**封装每个提供商的专属逻辑每个执行器继承BaseExecutor按需重写基础方法。类结构如下核心执行器一览对应 open-sse/executors/ 目录执行器提供商关键特化base.ts—抽象基类URL 构建、请求头、重试逻辑、凭证刷新default.tsClaude、Gemini、OpenAI、GLM、Kimi、MiniMax标准提供商的通用 OAuth token 刷新antigravity.tsGoogle Cloud Code项目/会话 ID 生成、多 URL 回退、从错误消息文本解析自定义重试时间如 reset after 2h7m23scursor.tsCursor IDE最复杂SHA-256 校验和认证、Protobuf 请求编码、二进制 EventStream → SSE 响应解析codex.tsOpenAI Codex注入系统指令、管理 thinking 级别、剔除不支持的参数github.tsGitHub Copilot双 token 体系GitHub OAuth Copilot token、VSCode 请求头模拟kiro.tsAWS CodeWhispererAWS EventStream 二进制解析、AMZN 事件帧、token 估算index.ts—工厂提供商名 → 执行器类的映射带默认回退这些文件在当前仓库中均实际存在base.ts、default.ts、antigravity.ts、cursor.ts、codex.ts、github.ts、kiro.ts、index.ts。需要说明的是随着项目演进executors/目录已扩展到 100 个文件新增了大量 Web 系与新兴提供商执行器上表覆盖的是文档描述的核心执行器集合index.ts工厂的默认回退机制正是新增提供商不必改动调度代码的原因。4.3 Handlersopen-sse/handlers/编排层Handler 是编排层负责协调翻译、执行、流式传输与错误处理。核心 Handler文件职责chatCore.ts中央编排器约 600 行。处理完整请求生命周期格式检测 → 翻译 → 执行器分发 → 流式/非流式响应 → token 刷新 → 错误处理 → 用量记录responsesHandler.tsOpenAI Responses API 适配器Responses 格式 → Chat Completions → 交给chatCore→ 再把 SSE 转回 Responses 格式embeddings.ts嵌入生成解析 embedding 模型 → 提供商分发到提供商 API返回 OpenAI 兼容的嵌入响应支持 6 提供商imageGeneration.ts图像生成解析图像模型 → 提供商支持 OpenAI 兼容、Gemini-imageAntigravity与回退Nebius模式返回 base64 或 URL 图像对应源码chatCore.ts、responsesHandler.ts、embeddings.ts、imageGeneration.ts。chatCore 的请求生命周期从源码结构看open-sse/handlers/目录下还包含autoComboCandidates.ts、responseSanitizer.ts、usageExtractor.ts、search/、videoGeneration/、rerank.ts等文件说明 Handler 层在文档描述的基础上继续吸收了音频、检索、多模态生成等能力但chatCore的上述生命周期仍是主干路径。4.4 Servicesopen-sse/services/支撑 Handler 与 Executor 的业务逻辑文件职责provider.ts格式检测detectFormat分析请求体结构识别 Claude/OpenAI/Gemini/Antigravity/Responses 格式含用max_tokens字段作 Claude 判断启发式。另有 URL 构建、请求头构建、thinking 配置归一化。支持openai-compatible-*与anthropic-compatible-*动态提供商model.ts模型串解析claude/model-name→{provider: claude, model: model-name}、带冲突检测的别名解析、输入净化拒绝路径穿越/控制字符、支持异步别名 getter 的模型信息解析accountFallback.ts限流处理指数退避1s → 2s → 4s → 上限 2min、账户冷却管理、错误分类哪些错误触发回退tokenRefresh.ts全部提供商的 OAuth token 刷新GoogleGemini、Antigravity、Claude、Codex、Qwen、Qoder、GitHubOAuth Copilot 双 token、KiroAWS SSO OIDC Social Auth含 in-flight Promise 去重缓存与指数退避重试combo.tsCombo 模型回退模型链。模型 A 遇到可回退错误时尝试 B再尝试 C……返回真实的上游状态码usage.ts从提供商 API 拉取配额/用量数据GitHub Copilot 配额、Antigravity 模型配额、Codex 速率限制、Kiro 用量明细、Claude 设置accountSelector.ts智能账户选择评分算法综合优先级、健康状态、轮询位置与冷却状态为每个请求选出最优账户contextManager.ts请求上下文生命周期管理创建并跟踪每个请求的上下文对象请求 ID、时间戳、提供商信息用于调试与日志ipFilter.ts基于 IP 的访问控制支持 allowlist 与 blocklist 模式在处理 API 请求前校验客户端 IPsessionManager.ts客户端指纹化的会话跟踪用哈希客户端标识跟踪活跃会话、统计请求数、提供会话指标signatureCache.ts基于请求签名的去重缓存缓存近期请求签名在时间窗口内对相同请求返回缓存响应systemPrompt.ts全局系统提示词注入为所有请求前置或追加可配置系统提示词并做每提供商的兼容性处理thinkingBudget.ts推理 token 预算passthrough直通、auto剥离 thinking 配置、custom固定预算、adaptive按复杂度缩放四种模式wildcardRouter.ts通配符模型模式路由把通配模式如*/claude-*按可用性与优先级解析为具体的提供商/模型对以上 14 个服务文件在当前仓库的 open-sse/services/ 目录中全部存在该目录目前已扩展至 250 个条目含各提供商的配额抓取器、限流管理器、压缩引擎等detectFormat、parseModel、checkFallbackError、refreshAccessToken等核心 API 均可从 open-sse/index.ts 的导出清单逐一核对。Token 刷新的 in-flight 去重并发请求同时发现 token 过期时tokenRefresh.ts用共享 Promise 缓存保证只发起一次刷新实现位于 open-sse/services/tokenRefresh.ts入口导出还包含TOKEN_EXPIRY_BUFFER_MS提前刷新缓冲见 open-sse/index.ts。账户回退状态机关键语义400 不触发回退请求本身有问题换账户也无意义而 401/429/500 等错误先分类、后决定回退。冷却时间从 1s 指数增长到 2 分钟上限请求成功则重置退避级别。对应实现见 open-sse/services/accountFallback.ts其导出的isProviderInCooldown、getProviderCooldownRemainingMs、getProvidersInCooldown等函数见 open-sse/index.ts为上层提供了冷却状态的查询能力。Combo 模型链Combo 把多个provider/model串组织成一条有序回退链与账户级回退不同这里切换的是模型本身且最终向客户端返回的是最后一个模型的真实上游状态码而不是笼统的 502便于客户端区分上游限流与网关故障。实现见 open-sse/services/combo.ts。4.5 Translatoropen-sse/translator/自注册插件式格式翻译引擎翻译引擎是 OmniRoute 的技术核心采用自注册插件系统目录组织目录/文件说明request/请求体翻译器。每个文件在 import 时通过register(from, to, fn)自我注册。当前仓库中已扩展出openai-to-claude/、openai-to-gemini/、openai-responses/等子目录承载大型翻译逻辑response/流式响应块翻译器。处理 SSE 事件类型、thinking 块、工具调用。当前仓库含claude-to-openai.ts、gemini-to-openai.ts、kiro-to-openai.ts、cursor-to-openai.ts、openai-to-antigravity.ts、openai-to-claude.ts、openai-to-gemini.ts等helpers/共享工具claudeHelper系统提示词提取、thinking 配置、geminiHelperparts/contents 映射、openaiHelper格式过滤、toolCallHelperID 生成、缺失响应注入、maxTokensHelper、responsesApiHelperindex.ts翻译引擎主体translateRequest()、translateResponse()、状态管理、注册表formats.ts格式常量OPENAI、CLAUDE、GEMINI、ANTIGRAVITY、KIRO、CURSOR、OPENAI_RESPONSES关键设计自注册插件源码印证这个import 即注册的机制在仓库中可以直接读到。open-sse/translator/registry.ts 维护两张以from:to为键的 Map// registry.ts节选 const requestRegistry new Mapstring, RequestTranslator(); const responseRegistry new Mapstring, ResponseTranslator(); function makeKey(from: string, to: string) { return ${from}:${to}; } export function register( from: string, to: string, requestFn?: RequestTranslator, responseFn?: ResponseTranslator ) { const key makeKey(from, to); if (requestFn) requestRegistry.set(key, requestFn); if (responseFn) responseRegistry.set(key, responseFn); }每个翻译器文件在模块顶层调用register()// 翻译器文件在 import 时自我注册 import { register } from ../index.js; register(claude, openai, translateClaudeToOpenAI); // index 导入所有翻译器文件触发注册 import ./request/claude-to-openai.js; // ← 自注册注册表同时支持请求与响应两种函数签名RequestTranslator接收(model, body, stream?, credentials?)ResponseTranslator接收(chunk, state)——后者传入的state正是有状态流式翻译的载体见第 5.6 节。格式常量定义在 open-sse/translator/formats.ts除文档列出的七种格式外当前仓库还新增了CLOVA与CODEX两个标识。4.6 Utilsopen-sse/utils/SSE 流管道与配套工具文件职责error.tsOpenAI 兼容格式的错误响应构建、上游错误解析、从 Antigravity 错误消息中提取重试时间、SSE 错误流式输出stream.tsSSE Transform Stream——流式管道核心。两种模式TRANSLATE完整格式翻译与PASSTHROUGH归一化 提取 usage。处理块缓冲、usage 估算、内容长度跟踪。每路流独享 encoder/decoder 实例避免共享状态streamHelpers.ts底层 SSE 工具parseSSELine容忍空白字符、hasValuableContent过滤 OpenAI/Claude/Gemini 的空块、fixInvalidId、formatSSE格式感知的 SSE 序列化含perf_metrics清理usageTracking.ts从任意格式Claude/OpenAI/Gemini/Responses提取 token 用量tool/message 分离的字符/token 比率估算缓冲叠加2000 token 安全边际按格式过滤字段带 ANSI 颜色的控制台日志requestLogger.ts遗留的文件式请求日志助手为兼容性保留。当前部署建议用APP_LOG_TO_FILE输出应用日志、用调用日志call log管道持久化请求工件bypassHandler.ts拦截 Claude CLI 的特定模式标题提取、warmup、count 请求不触达任何提供商直接返回伪造响应支持流式与非流式。有意限定在 Claude CLI 范围内networkProxy.ts为指定提供商解析出站代理 URL优先级提供商专属配置 → 全局配置 → 环境变量HTTPS_PROXY/HTTP_PROXY/ALL_PROXY支持NO_PROXY排除配置缓存 30s以上文件均实际存在于 open-sse/utils/error.ts、stream.ts、streamHelpers.ts、usageTracking.ts、requestLogger.ts、bypassHandler.ts、networkProxy.ts。SSE 流式管道两个实现细节值得注意一是每路流独享 TextDecoder/TextEncoder 实例因为解码器是有状态的处理多字节字符跨 chunk 的情况多路流共享会互相污染二是空块过滤hasValuableContent针对各格式无内容 chunk的形态差异单独判定防止客户端收到无意义的data: {}。请求日志的会话目录结构logs/ └── claude_gemini_claude-sonnet_20260208_143045/ ├── 1_req_client.json ← 客户端原始请求 ├── 2_req_source.json ← 初次转换后 ├── 3_req_openai.json ← OpenAI 中间格式 ├── 4_req_target.json ← 最终目标格式 ├── 5_res_provider.txt ← 提供商 SSE 块 (流式) ├── 5_res_provider.json ← 提供商响应 (非流式) ├── 6_res_openai.txt ← OpenAI 中间块 ├── 7_res_client.txt ← 面向客户端的 SSE 块 └── 6_error.json ← 错误详情 (如有)这套编号目录是排查翻译问题的黑匣子把请求翻译链的四个中间态与响应的三个观测点全部落盘任何一环的格式偏差都可以精确定位。4.7 应用层src/目录职责src/app/Web UI、API 路由、Express 中间件、OAuth 回调处理器src/lib/数据库访问localDb.ts、usageDb.ts、认证、共享代码src/mitm/中间人代理工具拦截提供商流量src/models/数据库模型定义src/shared/open-sse 函数的封装层provider、stream、error 等src/sse/把 open-sse 库接到 Express 路由的 SSE 端点处理器src/store/应用状态管理代表性 API 路由路由方法用途/api/provider-modelsGET/POST/DELETE每提供商自定义模型的 CRUD/api/models/catalogGET按提供商分组的全部模型聚合目录chat、embedding、image、custom/api/settings/proxyGET/PUT/DELETE分层出站代理配置global/providers/combos/keys/api/settings/proxy/testPOST校验代理连通性并返回公网 IP/延迟/v1/providers/[provider]/chat/completionsPOST每提供商专属 chat completions含模型校验/v1/providers/[provider]/embeddingsPOST每提供商专属 embeddings含模型校验/v1/providers/[provider]/images/generationsPOST每提供商专属图像生成含模型校验/api/settings/ip-filterGET/PUTIP 白名单/黑名单管理/api/settings/thinking-budgetGET/PUT推理 token 预算配置passthrough/auto/custom/adaptive/api/settings/system-promptGET/PUT面向所有请求的全局系统提示词注入/api/sessionsGET活跃会话跟踪与指标/api/rate-limitsGET每账户速率限制状态这些路由把 4.4 节的服务层能力IP 过滤、thinking 预算、系统提示词、会话、限流以 REST 形式暴露给管理面板形成服务层 ↔ API 路由的完整闭环。5. 关键设计模式汇总原文档归纳了七个设计模式逐一说明其工程收益Hub-and-Spoke 翻译所有格式经由 OpenAI 格式枢纽互转新增提供商只需写一对to/from OpenAI翻译器复杂度从 N² 降到 NExecutor 策略模式每个提供商一个继承自BaseExecutor的专属执行器类executors/index.ts中的工厂在运行时按需选择自注册插件系统翻译模块 import 时经register()自我登记新增翻译器只需创建文件并 import注册表实现见 open-sse/translator/registry.ts指数退避的账户回退429/401/500 时可切换下一账户冷却时间 1s → 2s → 4s → 上限 2minCombo 模型链一个 combo 聚合多个provider/model串首个失败自动回退到下一个有状态流式翻译响应翻译通过initState()机制在 SSE 块之间维护状态thinking 块跟踪、工具调用累积、内容块索引用量安全缓冲上报的 usage 上叠加 2000 token 缓冲防止客户端因系统提示词与格式翻译的开销而触到上下文窗口上限。6. 支持的格式格式方向标识符OpenAI Chat Completionssource targetopenaiOpenAI Responses APIsource targetopenai-responsesAnthropic Claudesource targetclaudeGoogle Geminisource targetgeminiAntigravitysource targetantigravityAWS Kiro仅 targetkiroCursor仅 targetcursorKiro 与 Cursor 只作为 target是因为它们没有可供客户端使用的标准请求格式——只能把别的格式翻译成它们的私有格式而不能从它们那里接受客户端请求。格式标识符常量定义见 open-sse/translator/formats.ts。7. 支持的提供商提供商认证方式执行器关键说明Anthropic ClaudeAPI key 或 OAuthDefault使用x-api-key头Google GeminiAPI key 或 OAuthDefault使用x-goog-api-key头AntigravityOAuthAntigravity多 URL 回退、自定义重试解析OpenAIAPI keyDefault标准 Bearer 认证CodexOAuthCodex注入系统指令、管理 thinkingGitHub CopilotOAuth Copilot tokenGithub双 token、VSCode 头模拟Kiro (AWS)AWS SSO OIDC 或 SocialKiro二进制 EventStream 解析Cursor IDE校验和认证CursorProtobuf 编码、SHA-256 校验和QwenOAuthDefault标准认证QoderOAuth (Basic Bearer)Default双认证头OpenRouterAPI keyDefault标准 Bearer 认证GLM、Kimi、MiniMaxAPI keyDefaultClaude 兼容使用x-api-keyopenai-compatible-*API keyDefault动态任意 OpenAI 兼容端点anthropic-compatible-*API keyDefault动态任意 Claude 兼容端点openai-compatible-*/anthropic-compatible-*是动态提供商detectFormat与 URL/请求头构建逻辑在运行期按别名前缀解析见 open-sse/services/provider.ts无需为每个私有部署单独写执行器。8. 数据流总览8.1 流式请求8.2 非流式请求8.3 Bypass 流程Claude CLIClaude CLI 启动时会发出几类元请求提取会话标题、连接预热、token 计数它们不消耗任何真实推理。bypassHandler在 Handler 层之前把这些请求拦截下来直接按目标格式生成伪造响应返回既省配额又加快 CLI 启动——实现见 open-sse/utils/bypassHandler.ts。9. 延伸阅读在仓库中继续深入入口与公共 API 总览open-sse/index.ts翻译注册表与引擎open-sse/translator/registry.ts、open-sse/translator/index.ts、open-sse/translator/formats.ts中央编排器open-sse/handlers/chatCore.ts执行器工厂与基类open-sse/executors/index.ts、open-sse/executors/base.ts弹性与回退open-sse/services/accountFallback.ts、open-sse/services/tokenRefresh.ts、open-sse/services/combo.ts流式管道open-sse/utils/stream.ts、open-sse/utils/usageTracking.ts架构配套文档同目录ARCHITECTURE.md、ROUTER_BACKENDS.md、ADAPTIVE_ROUTING.md英文版原始文档docs/architecture/CODEBASE_DOCUMENTATION.md需要说明适用前提本文以当前仓库快照为准open-sse核心库、src/应用层的分层结构稳定但executors/与services/的规模仍在快速增长文档表格覆盖的是核心模块集合新增提供商按同一套策略模式与注册机制扩展文档中的数字如翻译器文件数为撰写时的快照值以仓库实际目录为准。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考