[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-diegosouzapw--OmniRoute":3,"tool-diegosouzapw--OmniRoute":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159636,2,"2026-04-17T23:33:34",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":68,"readme_en":69,"readme_zh":70,"quickstart_zh":71,"use_case_zh":72,"hero_image_url":73,"owner_login":74,"owner_name":75,"owner_avatar_url":76,"owner_bio":77,"owner_company":78,"owner_location":79,"owner_email":77,"owner_twitter":77,"owner_website":80,"owner_url":81,"languages":82,"stars":107,"forks":108,"last_commit_at":109,"license":110,"difficulty_score":32,"env_os":111,"env_gpu":112,"env_ram":112,"env_deps":113,"category_tags":120,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":123,"updated_at":124,"faqs":125,"releases":154},9015,"diegosouzapw\u002FOmniRoute","OmniRoute","OmniRoute is an AI gateway for multi-provider LLMs: an OpenAI-compatible endpoint with smart routing, load balancing, retries, and fallbacks. Add policies, rate limits, caching, and observability for reliable, cost-aware inference.","OmniRoute 是一款专为多模型大语言应用设计的智能 AI 网关。它提供了一个完全兼容 OpenAI 标准的统一接口，让开发者只需对接一个端点，即可灵活调用全球超过 100 家提供商的 AI 模型服务，涵盖文本对话、图像生成、音视频处理及网络搜索等多种能力。\n\n在实际开发中，OmniRoute 有效解决了单一模型服务不稳定、成本高昂以及切换供应商复杂的痛点。通过内置的智能路由、负载均衡、自动重试和故障转移机制，它能确保服务持续在线，即使某个提供商出现故障，系统也会自动无缝切换至备用方案，实现真正的“零停机”。此外，它还支持策略配置、速率限制、响应缓存和全方位的可观测性监控，帮助团队在保障稳定性的同时优化推理成本。\n\n这款工具特别适合后端开发者、AI 应用架构师以及需要构建高可用 AI 服务的研究团队。其独特的技术亮点包括原生支持 MCP 服务器（集成 25 种工具）、A2A 协议以及记忆与技能系统，且全栈采用 TypeScript 编写，提供 Docker、npm 包及 Electron 桌面应用等多种部署方式，极大地降低了集成与维护门槛，让构建可靠、低成本的 AI 应用变得更加简","OmniRoute 是一款专为多模型大语言应用设计的智能 AI 网关。它提供了一个完全兼容 OpenAI 标准的统一接口，让开发者只需对接一个端点，即可灵活调用全球超过 100 家提供商的 AI 模型服务，涵盖文本对话、图像生成、音视频处理及网络搜索等多种能力。\n\n在实际开发中，OmniRoute 有效解决了单一模型服务不稳定、成本高昂以及切换供应商复杂的痛点。通过内置的智能路由、负载均衡、自动重试和故障转移机制，它能确保服务持续在线，即使某个提供商出现故障，系统也会自动无缝切换至备用方案，实现真正的“零停机”。此外，它还支持策略配置、速率限制、响应缓存和全方位的可观测性监控，帮助团队在保障稳定性的同时优化推理成本。\n\n这款工具特别适合后端开发者、AI 应用架构师以及需要构建高可用 AI 服务的研究团队。其独特的技术亮点包括原生支持 MCP 服务器（集成 25 种工具）、A2A 协议以及记忆与技能系统，且全栈采用 TypeScript 编写，提供 Docker、npm 包及 Electron 桌面应用等多种部署方式，极大地降低了集成与维护门槛，让构建可靠、低成本的 AI 应用变得更加简单高效。","# 🚀 OmniRoute — The Free AI Gateway\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory\u002FSkills Systems** & **Electron Desktop App**._\n\n**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**\n\n---\n\n\u003Cdiv align=\"center\">\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fomniroute?color=cb3837&logo=npm)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fomniroute)\n[![Docker Hub](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fv\u002Fdiegosouzapw\u002Fomniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute)\n\n![NPM Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdw\u002Fomniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002Fomniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fd18m\u002Fomniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Fdiegosouzapw\u002Fomniroute)\n![GitHub Downloads (all assets, all releases)](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fdiegosouzapw\u002Fomniroute\u002Ftotal?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_545556467cbd.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fstargazers)\n[![open issues](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_8c88f35a5dff.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues)\n[![license](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_42a83cd7f311.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fblob\u002Fmain\u002FLICENSE)\n[![last commit](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_d79aa0f451c7.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcommits\u002Fmain)\n[![total contributions](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_a86f68083c61.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw)\n[![code size](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_da3daf85b44d.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute)\n[![pr closed](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_e8960f6e7f8c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpulls?q=is%3Apr+is%3Aclosed)\n[![tag](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_989f0160de7c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Ftags)\n[![github streak](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_c91961c10855.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw)\n[![followers](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_303ba3ca98cf.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw?tab=followers)\n[![fork](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_2b0c7307947c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fnetwork\u002Fmembers)\n[![watch](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_1f0fbf74f994.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fwatchers)\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fdiegosouzapw\u002FOmniRoute)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fblob\u002Fmain\u002FLICENSE)\n[![Website](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWebsite-omniroute.online-blue?logo=google-chrome&logoColor=white)](https:\u002F\u002Fomniroute.online)\n[![WhatsApp](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 Website](https:\u002F\u002Fomniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n\u003C\u002Fdiv>\n\n🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs\u002Fi18n\u002Fpt-BR\u002FREADME.md) | 🇪🇸 [Español](docs\u002Fi18n\u002Fes\u002FREADME.md) | 🇫🇷 [Français](docs\u002Fi18n\u002Ffr\u002FREADME.md) | 🇮🇹 [Italiano](docs\u002Fi18n\u002Fit\u002FREADME.md) | 🇷🇺 [Русский](docs\u002Fi18n\u002Fru\u002FREADME.md) | 🇨🇳 [中文 (简体)](docs\u002Fi18n\u002Fzh-CN\u002FREADME.md) | 🇩🇪 [Deutsch](docs\u002Fi18n\u002Fde\u002FREADME.md) | 🇮🇳 [हिन्दी](docs\u002Fi18n\u002Fin\u002FREADME.md) | 🇹🇭 [ไทย](docs\u002Fi18n\u002Fth\u002FREADME.md) | 🇺🇦 [Українська](docs\u002Fi18n\u002Fuk-UA\u002FREADME.md) | 🇸🇦 [العربية](docs\u002Fi18n\u002Far\u002FREADME.md) | 🇯🇵 [日本語](docs\u002Fi18n\u002Fja\u002FREADME.md) | 🇻🇳 [Tiếng Việt](docs\u002Fi18n\u002Fvi\u002FREADME.md) | 🇧🇬 [Български](docs\u002Fi18n\u002Fbg\u002FREADME.md) | 🇩🇰 [Dansk](docs\u002Fi18n\u002Fda\u002FREADME.md) | 🇫🇮 [Suomi](docs\u002Fi18n\u002Ffi\u002FREADME.md) | 🇮🇱 [עברית](docs\u002Fi18n\u002Fhe\u002FREADME.md) | 🇭🇺 [Magyar](docs\u002Fi18n\u002Fhu\u002FREADME.md) | 🇮🇩 [Bahasa Indonesia](docs\u002Fi18n\u002Fid\u002FREADME.md) | 🇰🇷 [한국어](docs\u002Fi18n\u002Fko\u002FREADME.md) | 🇲🇾 [Bahasa Melayu](docs\u002Fi18n\u002Fms\u002FREADME.md) | 🇳🇱 [Nederlands](docs\u002Fi18n\u002Fnl\u002FREADME.md) | 🇳🇴 [Norsk](docs\u002Fi18n\u002Fno\u002FREADME.md) | 🇵🇹 [Português (Portugal)](docs\u002Fi18n\u002Fpt\u002FREADME.md) | 🇷🇴 [Română](docs\u002Fi18n\u002Fro\u002FREADME.md) | 🇵🇱 [Polski](docs\u002Fi18n\u002Fpl\u002FREADME.md) | 🇸🇰 [Slovenčina](docs\u002Fi18n\u002Fsk\u002FREADME.md) | 🇸🇪 [Svenska](docs\u002Fi18n\u002Fsv\u002FREADME.md) | 🇵🇭 [Filipino](docs\u002Fi18n\u002Fphi\u002FREADME.md) | 🇨🇿 [Čeština](docs\u002Fi18n\u002Fcs\u002FREADME.md)\n\n---\n\n## 🖼️ Main Dashboard\n\n\u003Cdiv align=\"center\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5f94c732a1dd.png\" alt=\"OmniRoute Dashboard\" width=\"800\"\u002F>\n\u003C\u002Fdiv>\n\n---\n\n## 📸 Dashboard Preview\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Click to see dashboard screenshots\u003C\u002Fb>\u003C\u002Fsummary>\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_d127ef9859e4.png) |\n| **Combos** | ![Combos](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_a58a61eb66a9.png) |\n| **Analytics** | ![Analytics](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_bf6d5bf391c7.png) |\n| **Health** | ![Health](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_8c9ff890221d.png) |\n| **Translator** | ![Translator](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_fb115a9f5940.png) |\n| **Settings** | ![Settings](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_f2b41b42295e.png) |\n| **CLI Tools** | ![CLI Tools](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5397760a4fc7.png) |\n| **Usage Logs** | ![Usage](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_cfbc438b666a.png) |\n| **Endpoints** | ![Endpoints](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_7e01ceb84701.png) |\n\n\u003C\u002Fdetails>\n\n---\n\n### 🤖 Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._\n\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_b0911dab9b3e.png\" alt=\"OpenClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>OpenClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 205K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FHKUDS\u002Fnanobot\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5afdb7dece24.png\" alt=\"NanoBot\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>NanoBot\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 20.9K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsipeed\u002Fpicoclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_390465706cf2.jpg\" alt=\"PicoClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>PicoClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 14.6K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fzeroclaw-labs\u002Fzeroclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_e34576ed6608.png\" alt=\"ZeroClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>ZeroClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 9.9K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fnearai\u002Fironclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_93cbef55fa68.png\" alt=\"IronClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>IronClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 2.1K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fanomalyco\u002Fopencode\">\n \u003Cimg src=\".\u002Fpublic\u002Fproviders\u002Fopencode.svg\" alt=\"OpenCode\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>OpenCode\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 106K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_64de00e34e82.png\" alt=\"Codex CLI\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Codex CLI\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 60.8K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_3ad4c120ed4f.png\" alt=\"Claude Code\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Claude Code\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 67.3K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_43f96254a435.png\" alt=\"Gemini CLI\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Gemini CLI\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 94.7K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FKilo-Org\u002Fkilocode\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_ed3af9be3533.png\" alt=\"Kilo Code\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Kilo Code\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 15.5K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\n\u003Csub>📡 All agents connect via \u003Ccode>http:\u002F\u002Flocalhost:20128\u002Fv1\u003C\u002Fcode> or \u003Ccode>http:\u002F\u002Fcloud.omniroute.online\u002Fv1\u003C\u002Fcode> — one config, unlimited models and quota\u003C\u002Fsub>\n\n---\n\n## 🤔 Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> Subscription quota expires unused every month\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> Rate limits stop you mid-coding\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> Expensive APIs ($20-50\u002Fmonth per provider)\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> Manual switching between providers\n\n**OmniRoute solves this:**\n\n- ✅ **Maximize subscriptions** - Track quota, use every bit before reset\n- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime\n- ✅ **Multi-account** - Round-robin between accounts per provider\n- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## 📧 Support\n\n> 💬 **Join our community!** [WhatsApp Group](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https:\u002F\u002Fomniroute.online)\n- **GitHub**: [github.com\u002Fdiegosouzapw\u002FOmniRoute](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute)\n- **Issues**: [github.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues)\n- **WhatsApp**: [Community Group](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https:\u002F\u002Fgithub.com\u002Fdecolua\u002F9router)\n\n### 🐛 Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker\u002FPM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## 🔄 How It Works\n\n```\n┌─────────────┐\n│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\n│ Tool │\n└──────┬──────┘\n │ http:\u002F\u002Flocalhost:20128\u002Fv1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute (Smart Router) │\n│ • Format translation (OpenAI ↔ Claude) │\n│ • Quota tracking + Embeddings + Images │\n│ • Auto token refresh │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n │ ↓ quota exhausted\n ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n │ ↓ budget limit\n ├─→ [Tier 3: CHEAP] GLM ($0.6\u002F1M), MiniMax ($0.2\u002F1M)\n │ ↓ budget limit\n └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💸 1. \"I pay for an expensive subscription but still get interrupted by limits\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDevelopers pay $20–200\u002Fmonth for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention\n- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next\n- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** — Business\u002FTeam workspace quota monitoring directly in the dashboard\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔌 2. \"I need to use multiple providers but each has a different API\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** — A single `http:\u002F\u002Flocalhost:20128\u002Fv1` serves as proxy for all 100+ providers\n- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API\n- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM\u002FERNIE\n- **Think Tag Extraction** — Extracts `\u003Cthink>` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** — `json_schema` → `responseMimeType`\u002F`responseSchema` automatic conversion\n- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python\u002FRust\u002FGo SDKs\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌐 3. \"My AI provider blocks my region\u002Fcountry\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nProviders like OpenAI\u002FCodex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection\u002Fkey\n- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🆓 4. \"I want to use AI for coding but I have no money\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nNot everyone can pay $20–200\u002Fmonth for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** — Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens\u002Fmonth free)\n- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud\u002F\u003Cmodel>` prefix\n- **Free-Only Combos** — Chain `gc\u002Fgemini-3-flash → if\u002Fkimi-k2-thinking → qw\u002Fqwen3-coder-plus` = $0\u002Fmonth with zero downtime\n- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔒 5. \"I need to protect my AI gateway from unauthorized access\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens\u002Fquota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `\u002Fdashboard\u002Fapi-manager` page\n- **Model-Level Permissions** — Restrict API keys to specific models (`openai\u002F*`, wildcard patterns), with Allow All\u002FRestrict toggle\n- **API Endpoint Protection** — Require a key for `\u002Fv1\u002Fmodels` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** — Per-IP rate limiting with configurable windows\n- **IP Filtering** — Allowlist\u002Fblocklist for access control\n- **Prompt Injection Guard** — Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** — Credentials encrypted at rest\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛑 6. \"My provider went down and I lost my coding flow\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** — Provider profiles control default account\u002Fmodel lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** — Progressive retry delays for both account\u002Fmodel lockouts and higher-level quarantine\n- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain\n- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50\u002Fp95\u002Fp99 latency\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔧 7. \"Configuring each AI tool is tedious and repetitive\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** — Guided 4-step setup for first-time users\n- **One endpoint, all models** — Configure `http:\u002F\u002Flocalhost:20128\u002Fv1` once, access 100+ providers\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔑 8. \"Managing OAuth tokens from multiple providers is hell\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nClaude Code, Codex, Gemini CLI, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN\u002FVPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** — OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** — Multiple accounts per provider via JWT\u002FID token extraction\n- **OAuth LAN\u002FRemote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS\u002FDocker\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📊 9. \"I don't know how much I'm spending or where\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** — Configurable prices per model\n- **Usage Statistics Per API Key** — Request count and last-used timestamp per key\n- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🐛 10. \"I can't diagnose errors and problems in AI calls\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** — p50\u002Fp95\u002Fp99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request\u002Fresponse payloads live in `DATA_DIR\u002Fcall_logs\u002F` and rotate independently of SQLite summaries\n- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker\u002FPM2 status). Attach it when reporting issues for instant triage.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🏗️ 11. \"Deploying and maintaining the gateway is complex\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** — `npm install -g omniroute && omniroute` — done\n- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** — Native app for Windows\u002FmacOS\u002FLinux with system tray, auto-start, offline mode\n- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers\n- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌍 12. \"The interface is English-only and my team doesn't speak English\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT\u002FBR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** — Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** — 30 complete documentation translations\n- **Language Selector** — Globe icon in header for real-time switching\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔄 13. \"I need more than chat — I need embeddings, images, audio\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** — `\u002Fv1\u002Fembeddings` with 6 providers and 9+ models\n- **Image Generation** — `\u002Fv1\u002Fimages\u002Fgenerations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** — `\u002Fv1\u002Fvideos\u002Fgenerations` — ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** — `\u002Fv1\u002Fmusic\u002Fgenerations` — ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** — `\u002Fv1\u002Faudio\u002Ftranscriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** — `\u002Fv1\u002Faudio\u002Fspeech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** — `\u002Fv1\u002Fmoderations` — Content safety checks\n- **Reranking** — `\u002Fv1\u002Frerank` — Document relevance reranking\n- **Responses API** — Full `\u002Fv1\u002Fresponses` support for Codex\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 14. \"I have no way to test and compare quality across models\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDevelopers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** — Full round-trip with visual response rendering\n- **Live Monitor** — Real-time stream of all requests flowing through the proxy\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📈 15. \"I need to scale without losing performance\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** — 5s deduplication window for identical requests\n- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence\n- **API Key Validation Cache** — 3-tier cache for production performance\n- **Health Dashboard with Telemetry** — p50\u002Fp95\u002Fp99 latency, cache stats, uptime\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🤖 16. \"I want to control model behavior globally\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool\u002Frequest is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** — Global prompt applied to all requests\n- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** — Global strategies that determine how requests are distributed\n- **Wildcard Router** — `provider\u002F*` patterns route dynamically to any provider\n- **Combo Enable\u002FDisable Toggle** — Toggle combos directly from the dashboard\n- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** — Enable\u002Fdisable all connections for a provider with one click\n- **Blocked Providers** — Exclude specific providers from `\u002Fv1\u002Fmodels` listing\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧰 17. \"I need MCP tools as first-class product capabilities\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧠 18. \"I need A2A orchestration with sync + stream task paths\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST \u002Fa2a`) with `message\u002Fsend` and `message\u002Fstream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks\u002Fget` and `tasks\u002Fcancel`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛰️ 19. \"I need real MCP process health, not guessed status\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process\u002Fuptime\u002Fheartbeat freshness\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📋 20. \"I need auditable MCP tool execution\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success\u002Ffailure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔐 21. \"I need scoped MCP permissions per integration\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>⚙️ 22. \"I need operational controls without redeploying\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔄 23. \"I need live A2A task lifecycle visibility and cancellation\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing\u002Ffiltering by state\u002Fskill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌊 24. \"I need active stream metrics for A2A load\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🪪 25. \"I need standard agent discovery for clients\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `\u002F.well-known\u002Fagent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧭 26. \"I need protocol discoverability in the product UX\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online\u002FOffline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 27. \"I need end-to-end protocol validation with real clients\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📡 28. \"I need unified observability across all interfaces\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards\u002Flogs\u002Fanalytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💼 29. \"I need one runtime for proxy + tools + agent orchestration\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🚀 30. \"I need to ship agentic workflows without glue-code sprawl\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📚 31. \"My long sessions crash with 'context_length_exceeded' limits\"\u003C\u002Fb>\u003C\u002Fsummary>\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n\u003C\u002Fdetails>\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc\u002Fclaude-opus-4-6\n 2. glm\u002Fglm-4.7\n 3. if\u002Fkimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc\u002Fgemini-3-flash\n 2. if\u002Fkimi-k2-thinking\n 3. qw\u002Fqwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24\u002F7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc\u002Fclaude-opus-4-6\n 2. cx\u002Fgpt-5.2-codex\n 3. glm\u002Fglm-4.7\n 4. minimax\u002FMiniMax-M2.1\n 5. if\u002Fkimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message\u002Fsend` and `message\u002Fstream`\n3) Observe via \u002Fdashboard\u002Fendpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## 🆓 Start Free — Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0\u002Fmonth**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K\u002Fmo free** |\n| 5 | `\u002Fdashboard\u002Fcombos` → **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE\u002FCLI to:** `http:\u002F\u002Flocalhost:20128\u002Fv1` · API Key: `any-string` · Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok\u002Fday), LongCat API key (50M tokens\u002Fday!), Cloudflare Workers AI (10K Neurons\u002Fday, 50+ models).\n\n## ⚡ Quick Start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc\u002Fcore`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages → approve\n> omniroute\n> ```\n\nDashboard opens at `http:\u002F\u002Flocalhost:20128` and API base URL is `http:\u002F\u002Flocalhost:20128\u002Fv1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical\u002FAPI port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http:\u002F\u002Flocalhost:20128\u002Fv1\n# Dashboard: http:\u002F\u002Flocalhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~\u002F.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request\u002Fproxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `\u002Fv1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup \u002F waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream\u002Ffetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard → `Endpoints` and create an API key.\n3. (Optional) Open Dashboard → `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http:\u002F\u002Flocalhost:20128\u002Fv1\nAPI Key: [copy from Endpoint page]\nModel: if\u002Fkimi-k2-thinking (or any provider\u002Fmodel prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http:\u002F\u002Flocalhost:20128\u002F.well-known\u002Fagent.json\n```\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:20128\u002Fa2a \\\n -H 'content-type: application\u002Fjson' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message\u002Fsend\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http:\u002F\u002Flocalhost:20129 npm run dev\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Void Linux (`xbps-src` template)\u003C\u002Fb>\u003C\u002Fsummary>\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs\u002Fomniroute\u002Ftemplate`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \u003Czenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\"\ndistfiles=\"https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Farchive\u002Frefs\u002Ftags\u002Fv${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"\u002Fvar\u002Flib\u002Fomniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps – skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next\u002Fstatic .next\u002Fstandalone\u002F.next\u002Fstatic\n\t[ -d public ] && cp -r public .next\u002Fstandalone\u002Fpublic || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC\u002FCXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=\u002Fusr\u002Flib\u002Fnode_modules\u002Fnpm\u002Fnode_modules\u002Fnode-gyp\u002Fbin\u002Fnode-gyp.js\n\t(cd node_modules\u002Fbetter-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next\u002Fstandalone\u002Fnode_modules\u002Fbetter-sqlite3\u002Fbuild\u002FRelease\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules\u002Fbetter-sqlite3\u002Fbuild\u002FRelease\u002Fbetter_sqlite3.node \"$_bs3_release\u002F\"\n\n\t# 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next\u002Fstandalone\u002Fnode_modules\u002F@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport – required by pino's worker thread\n\t# split2 – dep of pino-abstract-transport\n\t# process-warning – dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules\u002F$_mod\" .next\u002Fstandalone\u002Fnode_modules\u002F\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr\u002Flib\u002Fomniroute\u002F.next\n\n\tvcopy .next\u002Fstandalone\u002F. usr\u002Flib\u002Fomniroute\u002F.next\u002Fstandalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard\u002Fsettings \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard\u002Fproviders; do\n\t\ttouch \"${DESTDIR}\u002Fusr\u002Flib\u002Fomniroute\u002F${_d}\u002F.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}\u002Fomniroute\" \u003C\u003C'EOF'\n#!\u002Fbin\u002Fsh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}\u002F.local\u002Fshare}\u002Fomniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node \u002Fusr\u002Flib\u002Fomniroute\u002F.next\u002Fstandalone\u002Fserver.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}\u002Fomniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 🐳 Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:\u002Fapp\u002Fdata \\\n diegosouzapw\u002Fomniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:\u002Fapp\u002Fdata \\\n diegosouzapw\u002Fomniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `\u002Fv1` endpoint, and shows the generated `https:\u002F\u002F*.trycloudflare.com\u002Fv1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` \u002F `arm64`.\n- Managed Quick Tunnels default to HTTP\u002F2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=\u002Fabsolute\u002Fpath\u002Fto\u002Fcloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw\u002Fomniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:\u002Fapp\u002Fdata\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https:\u002F\u002Fyour-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https:\u002F\u002Fyour-domain.com --to http:\u002F\u002Fomniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw\u002Fomniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw\u002Fomniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## 🖥️ Desktop App — Offline & Always-On\n\n> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- 🖥️ **Native Window** — Dedicated app window with system tray integration\n- 🔄 **Auto-Start** — Launch OmniRoute on system login\n- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues\n- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux)\n- 🌐 **Offline Mode** — Works fully offline with bundled server\n\n### Quick Start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n📖 Full documentation: [`electron\u002FREADME.md`](electron\u002FREADME.md)\n\n---\n\n## 💰 Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20\u002Fmo | 5h + weekly | Already subscribed |\n| | Codex (Plus\u002FPro) | $20-200\u002Fmo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K\u002Fmo + 1K\u002Fday | Everyone! |\n| | GitHub Copilot | $10-19\u002Fmo | Monthly | GitHub users |\n| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok\u002Fday) | 60K TPM \u002F 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama\u002FGemma |\n| | DeepSeek V3.2 | $0.27\u002F$1.10 per 1M | None | Best price\u002Fquality reasoning |\n| | xAI Grok-4 Fast | **$0.20\u002F$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20\u002F$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5\u002F1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6\u002F1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 🆕 | $0.3\u002F1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2\u002F1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9\u002Fmo flat | 10M tokens\u002Fmo | Predictable cost |\n| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet\u002FHaiku (AWS Builder) |\n| | LongCat Flash-Lite 🆕 | **$0** (50M tok\u002Fday 🔥) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req\u002F15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons\u002Fday) | ~150 resp\u002Fday | 50+ models, global edge |\n| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU\u002FGDPR, Qwen3 235B, Llama 70B |\n\n> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20\u002F$0.50\u002FM (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**💡 $0 Combo Stack — The Complete Free Setup:**\n\n```\n# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever\nKiro (kr\u002F) → Claude Sonnet\u002FHaiku UNLIMITED\nQoder (if\u002F) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc\u002F) → LongCat-Flash-Lite — 50M tokens\u002Fday 🔥\nPollinations (pol\u002F) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\nQwen (qw\u002F) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini\u002F) → Gemini 2.5 Flash — 1,500 req\u002Fday free API key\nCloudflare AI (cf\u002F) → Llama 70B, Gemma 3, Mistral — 10K Neurons\u002Fday\nScaleway (scw\u002F) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\nGroq (groq\u002F) → Llama\u002FGemma ultra-fast — 14.4K req\u002Fday\nNVIDIA NIM (nvidia\u002F) → 70+ open models — 40 RPM forever\nCerebras (cerebras\u002F) → Llama\u002FQwen world-fastest — 1M tok\u002Fday\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever.\n\n---\n\n---\n\n## 🆓 Free Models — What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo.\n\n### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr\u002F` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr\u002F` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr\u002F` | **Unlimited** | Latest Opus via Kiro |\n\n### 🟢 QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if\u002F` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if\u002F` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if\u002F` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if\u002F` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if\u002F` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### 🟡 QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw\u002F` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw\u002F` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw\u002F` | **Unlimited** | No reported cap |\n| `vision-model` | `qw\u002F` | **Unlimited** | Multimodal (images) |\n\n### 🟣 GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc\u002F` | **180K tok\u002Fmonth** + 1K\u002Fday | Monthly reset |\n| `gemini-2.5-pro` | `gc\u002F` | 180K\u002Fmonth (shared pool) | High quality |\n\n### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai\u002Fkimi-k2.5` (Kimi K2.5), `z-ai\u002Fglm4.7` (GLM 4.7), `deepseek-ai\u002Fdeepseek-v3.2` (DeepSeek V3.2), `nvidia\u002Fllama-3.3-70b-instruct`, `deepseek\u002Fdeepseek-r1`\n\n### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens\u002Fday** | 60K TPM \u002F 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ (Free API Key — console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc\u002F` | **50M tokens** 💥 | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc\u002F` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc\u002F` | 500K tokens | Reasoning \u002F CoT |\n| `LongCat-Flash-Thinking-2601` | `lc\u002F` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc\u002F` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https:\u002F\u002Flongcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### 🟢 POLLINATIONS AI (No API Key Required) 🆕\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol\u002F` | 1 req\u002F15s | GPT-5 |\n| `claude` | `pol\u002F` | 1 req\u002F15s | Anthropic Claude |\n| `gemini` | `pol\u002F` | 1 req\u002F15s | Google Gemini |\n| `deepseek` | `pol\u002F` | 1 req\u002F15s | DeepSeek V3 |\n| `llama` | `pol\u002F` | 1 req\u002F15s | Meta Llama 4 Scout |\n| `mistral` | `pol\u002F` | 1 req\u002F15s | Mistral AI |\n\n> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp \u002F 500s audio \u002F 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf\u002Fmeta\u002Fllama-3.3-70b-instruct`, `@cf\u002Fgoogle\u002Fgemma-3-12b-it`, `@cf\u002Fopenai\u002Fwhisper-large-v3-turbo` (free audio!), `@cf\u002Fqwen\u002Fqwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https:\u002F\u002Fdash.cloudflare.com). Store Account ID in provider settings.\n\n### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU\u002FGDPR compliant. Get API key at [console.scaleway.com](https:\u002F\u002Fconsole.scaleway.com).\n\n> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr\u002F) → Claude Sonnet\u002FHaiku UNLIMITED\n> Qoder (if\u002F) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc\u002F) → LongCat-Flash-Lite — 50M tokens\u002Fday 🔥\n> Pollinations (pol\u002F) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed\n> Qwen (qw\u002F) → qwen3-coder models UNLIMITED\n> Gemini (gemini\u002F) → Gemini 2.5 Flash — 1,500 req\u002Fday free\n> Cloudflare AI (cf\u002F) → 50+ models — 10K Neurons\u002Fday\n> Scaleway (scw\u002F) → Qwen3 235B, Llama 70B — 1M free tokens (EU)\n> Groq (groq\u002F) → Llama\u002FGemma — 14.4K req\u002Fday ultra-fast\n> NVIDIA NIM (nvidia\u002F) → 70+ open models — 40 RPM forever\n> Cerebras (cerebras\u002F) → Llama\u002FQwen world-fastest — 1M tok\u002Fday\n> ```\n\n## 🎙️ Free Transcription Combo\n\n> Transcribe any audio\u002Fvideo for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |\n| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |\n| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `\u002Fdashboard\u002Fcombos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram\u002Fnova-3 → uses $200 free first\n [2] assemblyai\u002Funiversal-3-pro → fallback when Deepgram credits run out\n [3] groq\u002Fwhisper-large-v3 → free forever, emergency fallback\n```\n\nThen in `\u002Fdashboard\u002Fmedia` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.\n\n## 💡 Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### 🆕 New — v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `\u002Fv1\u002Fws` — full streaming over WS with session auth (API key or session cookie) |\n| 🔑 **Sync Tokens & Config Bundle** | Issue\u002Frevoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API |\n| 🔢 **Hybrid Token Counting** | Uses provider-side `\u002Fmessages\u002Fcount_tokens` when available; falls back to estimation — accurate usage tracking without guessing |\n| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches |\n| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private\u002Flocal URLs with retry, timeout, and SSRF protection |\n| 🔄 **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types |\n| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request |\n| 🗑️ **Uninstall \u002F Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods |\n| 🔧 **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N\u002FM active`) on provider pages |\n| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 Fast Family** | xAI models at $0.20\u002F$0.50\u002FM — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5\u002F1M — newest flagship from the GLM family |\n| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30\u002F1M — significant upgrade from M2.1 |\n| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true\u002Ffalse` in registry — AutoCombo skips non-tool-capable models |\n| 🌍 **Multilingual Intent Detection** | PT\u002FZH\u002FES\u002FAR keywords in AutoCombo scoring — better model selection for non-English content |\n| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data |\n| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges |\n| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins |\n\n### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **Model Playground** | Dashboard page to test any model directly — provider\u002Fmodel\u002Fendpoint selectors, Monaco Editor, streaming, abort, timing |\n| 🔏 **CLI Fingerprint Matching** | Per-provider header\u002Fbody ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `\u002Fapi\u002Facp\u002Fagents` endpoint |\n| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID |\n| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### 🤖 Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP Server (25 tools)** | IDE\u002Fagent tools via 3 transports: stdio, SSE (`\u002Fapi\u002Fmcp\u002Fsse`), Streamable HTTP (`\u002Fapi\u002Fmcp\u002Fstream`). 18 core + 3 memory + 4 skill tools |\n| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| 🎚️ **Service Enable\u002FDisable Toggles** | ON\u002FOFF switches for MCP and A2A with settings persistence (default: OFF) |\n| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| 📋 **MCP Audit Trail** | Filterable audit logs with success\u002Ffailure and key attribution |\n| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| 📡 **A2A Task Lifecycle Management** | List\u002Ffilter tasks, inspect events\u002Fartifacts, cancel running tasks |\n| 📋 **Agent Card Discovery** | `\u002F.well-known\u002Fagent.json` for client auto-discovery |\n| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### 🧠 Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free |\n| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |\n| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control |\n| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| 🌐 **Wildcard Router** | `provider\u002F*` dynamic routing |\n| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models |\n| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding\u002Fvision\u002Fanalysis\u002Fsummarization) |\n| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| 💬 **System Prompt Injection** | Global behavior controls applied consistently |\n| 📄 **Responses API Compatibility** | Full `\u002Fv1\u002Fresponses` support for Codex and advanced agentic workflows |\n\n### 🎵 Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **Image Generation** | `\u002Fv1\u002Fimages\u002Fgenerations` with cloud and local backends |\n| 📐 **Embeddings** | `\u002Fv1\u002Fembeddings` for search and RAG pipelines |\n| 🎤 **Audio Transcription** | `\u002Fv1\u002Faudio\u002Ftranscriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4\u002FMP3\u002FWAV support |\n| 🔊 **Text-to-Speech** | `\u002Fv1\u002Faudio\u002Fspeech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| 🎬 **Video Generation** | `\u002Fv1\u002Fvideos\u002Fgenerations` (ComfyUI + SD WebUI workflows) |\n| 🎵 **Music Generation** | `\u002Fv1\u002Fmusic\u002Fgenerations` (ComfyUI workflows) |\n| 🛡️ **Moderations** | `\u002Fv1\u002Fmoderations` safety checks |\n| 🔀 **Reranking** | `\u002Fv1\u002Frerank` for relevance scoring |\n| 🔍 **Web Search** 🆕 | `\u002Fv1\u002Fsearch` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free\u002Fmonth, auto-failover, cache |\n\n### 🛡️ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **Circuit Breakers** | Per-model trip\u002Frecover with threshold controls |\n| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry\u002Frate events |\n| 🧠 **Semantic + Signature Cache** | Cost\u002Flatency reduction with two cache layers |\n| ⚡ **Request Idempotency** | Duplicate protection window |\n| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** |\n| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |\n| 🌐 **IP Filtering** | Allowlist\u002Fblocklist control for exposed deployments |\n| 📊 **Editable Rate Limits** | Configurable global\u002Fprovider-level limits with persistence |\n| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| 🚪 **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| 🔑 **API Key Management + Scoping** | Secure key issuance\u002Frotation and model\u002Fprovider controls |\n| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| 🛡️ **Protected `\u002Fmodels`** | Optional auth gating and provider hiding for model catalog |\n| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private\u002Flocal URLs, retries, SSRF protection |\n| 🔄 **Cooldown-Aware Retries** 🆕 | Auto-retry chat on model cooldowns; configurable `requestRetry` \u002F `maxRetryIntervalSec` |\n| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages |\n| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### 📊 Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| 📝 **Request + Proxy Logging** | Full request\u002Fresponse and proxy logging |\n| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |\n| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| 🔍 **Request Telemetry** | p50\u002Fp95\u002Fp99 latency and request tracing |\n| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility |\n| 📈 **Analytics Visualizations** | Model\u002Fprovider usage insights and trend views |\n| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies |\n| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing |\n| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal |\n\n### ☁️ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |\n| 🔑 **API Key Model Filtering** | Native \u002Fv1\u002Fmodels response filtered via assigned Bearer context roles |\n| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| 🔄 **Backup\u002FRestore** | Export\u002Fimport and disaster recovery flows |\n| 🧙 **Onboarding Wizard** | First-run guided setup |\n| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| 🎮 **Model Playground** | Test any provider\u002Fmodel\u002Fendpoint from the dashboard |\n| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| 🧹 **Clear All Models** | One-click model list clearing in provider details |\n| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings |\n| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features |\n| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location |\n| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `\u002Fv1\u002Fws` |\n| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc\u002Fclaude-opus-4-6\n 2. nvidia\u002Fllama-3.3-70b\n 3. glm\u002Fglm-4.7\n 4. if\u002Fkimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`\u002Fapi\u002Fmcp\u002F*`, `\u002Fapi\u002Fa2a\u002F*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request\u002Fresponse round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> 📖 **[MCP Server README](open-sse\u002Fmcp-server\u002FREADME.md)** — Tool reference, IDE configs, and client examples\n>\n> 📖 **[A2A Server README](src\u002Flib\u002Fa2a\u002FREADME.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## 🧪 Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true\u002Ffalse | `(output) => output.length > 10` |\n\n---\n\n## 📖 Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧩 MCP Setup (Model Context Protocol)\u003C\u002Fb>\u003C\u002Fsummary>\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `\u002Fdashboard\u002Fmcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET \u002Fapi\u002Fmcp\u002Fstatus`\n- `GET \u002Fapi\u002Fmcp\u002Ftools`\n- `GET \u002Fapi\u002Fmcp\u002Faudit`\n- `GET \u002Fapi\u002Fmcp\u002Faudit\u002Fstats`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🤝 A2A Setup (Agent2Agent)\u003C\u002Fb>\u003C\u002Fsummary>\n\nDiscover the agent:\n\n```bash\ncurl http:\u002F\u002Flocalhost:20128\u002F.well-known\u002Fagent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:20128\u002Fa2a \\\n -H 'content-type: application\u002Fjson' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message\u002Fsend\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET \u002Fapi\u002Fa2a\u002Fstatus`\n- `GET \u002Fapi\u002Fa2a\u002Ftasks`\n- `GET \u002Fapi\u002Fa2a\u002Ftasks\u002F:id`\n- `POST \u002Fapi\u002Fa2a\u002Ftasks\u002F:id\u002Fcancel`\n\nOperational UI:\n\n- `\u002Fdashboard\u002Fa2a` for task\u002Fstate\u002Fstream observability and smoke actions\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 End-to-end protocol validation\u003C\u002Fb>\u003C\u002Fsummary>\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect\u002Flist\u002Fcall\n- A2A discovery\u002Fsend\u002Fstream\u002Fget\u002Fcancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💳 Subscription Providers\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Claude Code (Pro\u002FMax)\n\n```bash\nDashboard → Providers → Connect Claude Code\n→ OAuth login → Auto token refresh\n→ 5-hour + weekly quota tracking\n\nModels:\n cc\u002Fclaude-opus-4-6\n cc\u002Fclaude-sonnet-4-5-20250929\n cc\u002Fclaude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus\u002FPro)\n\n```bash\nDashboard → Providers → Connect Codex\n→ OAuth login (port 1455)\n→ 5-hour + weekly reset\n\nModels:\n cx\u002Fgpt-5.2-codex\n cx\u002Fgpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON\u002FOFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON\u002FOFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K\u002Fmonth!)\n\n```bash\nDashboard → Providers → Connect Gemini CLI\n→ Google OAuth\n→ 180K completions\u002Fmonth + 1K\u002Fday\n\nModels:\n gc\u002Fgemini-3-flash-preview\n gc\u002Fgemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard → Providers → Connect GitHub\n→ OAuth via GitHub\n→ Monthly reset (1st of month)\n\nModels:\n gh\u002Fgpt-5\n gh\u002Fclaude-4.5-sonnet\n gh\u002Fgemini-3.1-pro-preview\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔑 API Key Providers\u003C\u002Fb>\u003C\u002Fsummary>\n\n### NVIDIA NIM (FREE developer access — 70+ models)\n\n1. Sign up: [build.nvidia.com](https:\u002F\u002Fbuild.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard → Add Provider → NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia\u002Fllama-3.3-70b-instruct`, `nvidia\u002Fmistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https:\u002F\u002Fplatform.deepseek.com)\n2. Get API key\n3. Dashboard → Add Provider → DeepSeek\n\n**Models:** `deepseek\u002Fdeepseek-chat`, `deepseek\u002Fdeepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https:\u002F\u002Fconsole.groq.com)\n2. Get API key (free tier included)\n3. Dashboard → Add Provider → Groq\n\n**Models:** `groq\u002Fllama-3.3-70b`, `groq\u002Fmixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference — best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https:\u002F\u002Fopenrouter.ai)\n2. Get API key\n3. Dashboard → Add Provider → OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💰 Cheap Providers (Backup)\u003C\u002Fb>\u003C\u002Fsummary>\n\n### GLM-4.7 (Daily reset, $0.6\u002F1M)\n\n1. Sign up: [Zhipu AI](https:\u002F\u002Fopen.bigmodel.cn\u002F)\n2. Get API key from Coding Plan\n3. Dashboard → Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm\u002Fglm-4.7`\n\n**Pro Tip:** Coding Plan offers 3× quota at 1\u002F7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20\u002F1M)\n\n1. Sign up: [MiniMax](https:\u002F\u002Fwww.minimax.io\u002F)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `minimax\u002FMiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9\u002Fmonth flat)\n\n1. Subscribe: [Moonshot AI](https:\u002F\u002Fplatform.moonshot.ai\u002F)\n2. Get API key\n3. Dashboard → Add API Key\n\n**Use:** `kimi\u002Fkimi-latest`\n\n**Pro Tip:** Fixed $9\u002Fmonth for 10M tokens = $0.90\u002F1M effective cost!\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🆓 FREE Providers (Emergency Backup)\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard → Connect Qoder\n→ Qoder OAuth login\n→ Unlimited usage\n\nModels:\n if\u002Fkimi-k2-thinking\n if\u002Fqwen3-coder-plus\n if\u002Fglm-4.7\n if\u002Fminimax-m2\n if\u002Fdeepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard → Connect Qwen\n→ Device code authorization\n→ Unlimited usage\n\nModels:\n qw\u002Fqwen3-coder-plus\n qw\u002Fqwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard → Connect Kiro\n→ AWS Builder ID or Google\u002FGitHub\n→ Unlimited usage\n\nModels:\n kr\u002Fclaude-sonnet-4.5\n kr\u002Fclaude-haiku-4.5\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🎨 Create Combos\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Example 1: Maximize Subscription → Cheap Backup\n\n```\nDashboard → Combos → Create New\n\nName: premium-coding\nModels:\n 1. cc\u002Fclaude-opus-4-6 (Subscription primary)\n 2. glm\u002Fglm-4.7 (Cheap backup, $0.6\u002F1M)\n 3. minimax\u002FMiniMax-M2.1 (Cheapest fallback, $0.20\u002F1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc\u002Fgemini-3-flash-preview (180K free\u002Fmonth)\n 2. if\u002Fkimi-k2-thinking (unlimited)\n 3. qw\u002Fqwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔧 CLI Integration\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Cursor IDE\n\n```\nSettings → Models → Advanced:\n OpenAI API Base URL: http:\u002F\u002Flocalhost:20128\u002Fv1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc\u002Fclaude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~\u002F.claude\u002Fsettings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http:\u002F\u002Flocalhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 — Dashboard (recommended):**\n\n```\nDashboard → CLI Tools → OpenClaw → Select Model → Apply\n```\n\n**Option 2 — Manual:** Edit `~\u002F.openclaw\u002Fopenclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http:\u002F\u002F127.0.0.1:20128\u002Fv1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline \u002F Continue \u002F RooCode\n\n```\nSettings → API Configuration:\n Provider: OpenAI Compatible\n Base URL: http:\u002F\u002Flocalhost:20128\u002Fv1\n API Key: [from OmniRoute dashboard]\n Model: if\u002Fkimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n\u002Fconnect\n# Select \"Other\" → Enter ID: \"omniroute\" → Enter your OmniRoute API key\n```\n\n**Step 2:** Create\u002Fedit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk\u002Fopenai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http:\u002F\u002Flocalhost:20128\u002Fv1\"\n },\n \"models\": {\n \"cc\u002Fclaude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg\u002Fgemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if\u002Fkimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n\u002Fmodels\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `\u002Fv1\u002Fmodels` endpoint to the `models` section. Use the format `provider\u002Fmodel-id` from your OmniRoute dashboard.\n\n\u003C\u002Fdetails>\n\n---\n\n## 🐛 Troubleshooting\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Click to expand troubleshooting guide\u003C\u002Fb>\u003C\u002Fsummary>\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted → Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out → Fallback to GLM\u002FMiniMax\n- Add combo: `cc\u002Fclaude-opus-4-6 → glm\u002Fglm-4.7 → if\u002Fkimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard → Provider → Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard → Costs\n- Switch primary model to GLM\u002FMiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard\u002FAPI ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard\u002FNext.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard\u002Fpublic URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request\u002Fresponse payloads are written to `DATA_DIR\u002Fcall_logs\u002F` as one JSON artifact per request\n- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs\u002F` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs\u002Fapplication\u002Fapp.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `\u002Fmodels` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `\u002Fv1` suffix\n\n### 🔐 OAuth on a Remote Server\n\n\u003Ca name=\"oauth-on-a-remote-server\">\u003C\u002Fa>\n\u003Ca name=\"oauth-em-servidor-remoto\">\u003C\u002Fa>\n\n> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity \u002F Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https:\u002F\u002Fomniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials](https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps:\u002F\u002Fyour-server.com\u002Fcallback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http:\u002F\u002F45.33.32.156:20128\u002Fcallback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard → Providers → Antigravity (or Gemini CLI) → OAuth\n\nGoogle will now redirect correctly to `https:\u002F\u002Fyour-server.com\u002Fcallback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🇧🇷 Versão em Português\u003C\u002Fb>\u003C\u002Fsummary>\n\n#### Por que o OAuth do Antigravity \u002F Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https:\u002F\u002Fomniroute.meuservidor.com`), o Google rejeita a autenticação com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solução: Configure suas próprias credenciais OAuth\n\nVocê precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials](https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps:\u002F\u002Fseu-servidor.com\u002Fcallback\n```\n\n> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http:\u002F\u002F45.33.32.156:20128\u002Fcallback`).\n\n**4. Salve e copie as credenciais**\n\nApós criar, o Google mostrará o **Client ID** e o **Client Secret**.\n\n**5. Configure as variáveis de ambiente**\n\nNo seu `.env` (ou nas variáveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard → Providers → Antigravity (ou Gemini CLI) → OAuth\n\nAgora o Google redirecionará corretamente para `https:\u002F\u002Fseu-servidor.com\u002Fcallback` e a autenticação funcionará.\n\n---\n\n#### Workaround temporário (sem configurar credenciais próprias)\n\nSe não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirá a URL de autorização do Google\n2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue)\n4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.\n\n\u003C\u002Fdetails>\n\n---\n\n\u003C\u002Fdetails>\n\n## 🛠️ Tech Stack\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Click to expand tech stack details\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 — **100% TypeScript** across `src\u002F` and `open-sse\u002F` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I\u002FO validation, API contracts)\n- **Protocols**: MCP (stdio\u002FHTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI\u002FCD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https:\u002F\u002Fomniroute.online)\n- **Package**: [npmjs.com\u002Fpackage\u002Fomniroute](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fomniroute)\n- **Docker**: [hub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n\u003C\u002Fdetails>\n\n---\n\n## 📖 Documentation\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs\u002FUSER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs\u002FAPI_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse\u002Fmcp-server\u002FREADME.md) | 25 MCP tools, IDE configs, Python\u002FTS\u002FGo clients |\n| [A2A Server](src\u002Flib\u002Fa2a\u002FREADME.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs\u002Fauto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs\u002Ffeatures\u002Fcontext-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs\u002FTROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs\u002FARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs\u002FCODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs\u002FUNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs\u002FENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs\u002Fopenapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs\u002FVM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs\u002FFEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs\u002FRELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## 🗺️ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### 🔜 Coming Soon\n\n- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE\n- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework\n- 📦 **Batch API** — Asynchronous batch processing for bulk requests\n- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata\n- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider\n\n> 📝 Full feature specifications available in [`docs\u002Fnew-features\u002F`](docs\u002Fnew-features\u002F) (217 detailed specs)\n\n---\n\n## 👥 Contributors\n\n[![Contributors](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_76e4b6504592.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fgraphs\u002Fcontributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature\u002Famazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature\u002Famazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release — npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https:\u002F\u002Fstarchart.cc\u002Fdiegosouzapw\u002FOmniRoute.svg?variant=adaptive)](https:\u002F\u002Fstarchart.cc\u002Fdiegosouzapw\u002FOmniRoute)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to **[9router](https:\u002F\u002Fgithub.com\u002Fdecolua\u002F9router)** by **[decolua](https:\u002F\u002Fgithub.com\u002Fdecolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003Cdiv align=\"center\">\n \u003Csub>Built with ❤️ for developers who code 24\u002F7\u003C\u002Fsub>\n \u003Cbr\u002F>\n \u003Csub>\u003Ca href=\"https:\u002F\u002Fomniroute.online\">omniroute.online\u003C\u002Fa>\u003C\u002Fsub>\n\u003C\u002Fdiv>\n\u003C!-- GitHub Discussions enabled for community Q&A -->\n","# 🚀 OmniRoute — 免费的 AI 网关\n\n### 永不停歇地编码。智能路由至**免费及低成本的 AI 模型**，并具备自动回退机制。\n\n_您的通用 API 代理——一个端点，100 多家服务提供商，零 downtime。现已支持**MCP 服务器（25 种工具）**、**A2A 协议**、**记忆\u002F技能系统**以及**Electron 桌面应用**。_\n\n**聊天补全 • 嵌入 • 图像生成 • 视频 • 音乐 • 音频 • 重排序 • **网页搜索** • MCP 服务器 • A2A 协议 • 100% TypeScript**\n\n---\n\n\u003Cdiv align=\"center\">\n\n[![npm 版本](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fomniroute?color=cb3837&logo=npm)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fomniroute)\n[![Docker Hub](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fv\u002Fdiegosouzapw\u002Fomniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute)\n\n![NPM 下载量](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdw\u002Fomniroute?label=npm%20down%20week&color=red)\n![NPM 下载量](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002Fomniroute?label=npm%20down%20month&color=red)\n\n![NPM 下载量](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fd18m\u002Fomniroute?label=npm%20down%20year&color=red)\n![Docker 拉取次数](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Fdiegosouzapw\u002Fomniroute)\n![GitHub 下载量（所有资产、所有版本）](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fdiegosouzapw\u002Fomniroute\u002Ftotal?style=flat&label=eletron%20donwloads&color=blue)\n\n[![星标](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_545556467cbd.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fstargazers)\n[![开放问题](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_8c88f35a5dff.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues)\n[![许可证](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_42a83cd7f311.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fblob\u002Fmain\u002FLICENSE)\n[![最近一次提交](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_d79aa0f451c7.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcommits\u002Fmain)\n[![总贡献](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_a86f68083c61.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw)\n[![代码规模](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_da3daf85b44d.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute)\n[![已关闭 PR](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_e8960f6e7f8c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpulls?q=is%3Apr+is%3Aclosed)\n[![标签](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_989f0160de7c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Ftags)\n[![GitHub 连续签到](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_c91961c10855.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw)\n[![关注者](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_303ba3ca98cf.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw?tab=followers)\n[![分支](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_2b0c7307947c.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fnetwork\u002Fmembers)\n[![观看者](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_1f0fbf74f994.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fwatchers)\n\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fdiegosouzapw\u002FOmniRoute)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fblob\u002Fmain\u002FLICENSE)\n[![官网](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWebsite-omniroute.online-blue?logo=google-chrome&logoColor=white)](https:\u002F\u002Fomniroute.online)\n[![WhatsApp](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[🌐 官网](https:\u002F\u002Fomniroute.online) • [🚀 快速入门](#-quick-start) • [💡 功能](#-key-features) • [📖 文档](#-documentation) • [💰 定价一览](#-pricing-at-a-glance) • [💬 WhatsApp](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n\u003C\u002Fdiv>\n\n🌐 **支持语言：** 🇺🇸 [英语](README.md) | 🇧🇷 [巴西葡萄牙语](docs\u002Fi18n\u002Fpt-BR\u002FREADME.md) | 🇪🇸 [西班牙语](docs\u002Fi18n\u002Fes\u002FREADME.md) | 🇫🇷 [法语](docs\u002Fi18n\u002Ffr\u002FREADME.md) | 🇮🇹 [意大利语](docs\u002Fi18n\u002Fit\u002FREADME.md) | 🇷🇺 [俄语](docs\u002Fi18n\u002Fru\u002FREADME.md) | 🇨🇳 [简体中文](docs\u002Fi18n\u002Fzh-CN\u002FREADME.md) | 🇩🇪 [德语](docs\u002Fi18n\u002Fde\u002FREADME.md) | 🇮🇳 [印地语](docs\u002Fi18n\u002Fin\u002FREADME.md) | 🇹🇭 [泰语](docs\u002Fi18n\u002Fth\u002FREADME.md) | 🇺🇦 [乌克兰语](docs\u002Fi18n\u002Fuk-UA\u002FREADME.md) | 🇸🇦 [阿拉伯语](docs\u002Fi18n\u002Far\u002FREADME.md) | 🇯🇵 [日语](docs\u002Fi18n\u002Fja\u002FREADME.md) | 🇻🇳 [越南语](docs\u002Fi18n\u002Fvi\u002FREADME.md) | 🇧🇬 [保加利亚语](docs\u002Fi18n\u002Fbg\u002FREADME.md) | 🇩🇰 [丹麦语](docs\u002Fi18n\u002Fda\u002FREADME.md) | 🇫🇮 [芬兰语](docs\u002Fi18n\u002Ffi\u002FREADME.md) | 🇮🇱 [希伯来语](docs\u002Fi18n\u002Fhe\u002FREADME.md) | 🇭🇺 [匈牙利语](docs\u002Fi18n\u002Fhu\u002FREADME.md) | 🇮🇩 [印尼语](docs\u002Fi18n\u002Fid\u002FREADME.md) | 🇰🇷 [韩语](docs\u002Fi18n\u002Fko\u002FREADME.md) | 🇲🇾 [马来语](docs\u002Fi18n\u002Fms\u002FREADME.md) | 🇳🇱 [荷兰语](docs\u002Fi18n\u002Fnl\u002FREADME.md) | 🇳🇴 [挪威语](docs\u002Fi18n\u002Fno\u002FREADME.md) | 🇵🇹 [葡萄牙语](docs\u002Fi18n\u002Fpt\u002FREADME.md) | 🇷🇴 [罗马尼亚语](docs\u002Fi18n\u002Fro\u002FREADME.md) | 🇵🇱 [波兰语](docs\u002Fi18n\u002Fpl\u002FREADME.md) | 🇸🇰 [斯洛伐克语](docs\u002Fi18n\u002Fsk\u002FREADME.md) | 🇸🇪 [瑞典语](docs\u002Fi18n\u002Fsv\u002FREADME.md) | 🇵🇭 [菲律宾语](docs\u002Fi18n\u002Fphi\u002FREADME.md) | 🇨🇿 [捷克语](docs\u002Fi18n\u002Fcs\u002FREADME.md)\n\n---\n\n## 🖼️ 主仪表盘\n\n\u003Cdiv align=\"center\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5f94c732a1dd.png\" alt=\"OmniRoute 仪表盘\" width=\"800\"\u002F>\n\u003C\u002Fdiv>\n\n---\n\n## 📸 仪表盘预览\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>点击查看仪表盘截图\u003C\u002Fb>\u003C\u002Fsummary>\n\n| 页面 | 截图 |\n| -------------- | ------------------------------------------------- |\n| **服务提供商** | ![服务提供商](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_d127ef9859e4.png) |\n| **组合** | ![组合](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_a58a61eb66a9.png) |\n| **分析** | ![分析](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_bf6d5bf391c7.png) |\n| **健康状况** | ![健康状况](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_8c9ff890221d.png) |\n| **翻译器** | ![翻译器](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_fb115a9f5940.png) |\n| **设置** | ![设置](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_f2b41b42295e.png) |\n| **CLI 工具** | ![CLI 工具](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5397760a4fc7.png) |\n| **使用日志** | ![使用情况](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_cfbc438b666a.png) |\n| **端点** | ![端点](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_7e01ceb84701.png) |\n\n\u003C\u002Fdetails>\n\n---\n\n### 🤖 您喜爱的编码助手的免费 AI 提供商\n\n_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具——一个用于无限编码的免费 API 网关。_\n\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_b0911dab9b3e.png\" alt=\"OpenClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>OpenClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 205K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FHKUDS\u002Fnanobot\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_5afdb7dece24.png\" alt=\"NanoBot\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>NanoBot\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 20.9K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsipeed\u002Fpicoclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_390465706cf2.jpg\" alt=\"PicoClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>PicoClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 14.6K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fzeroclaw-labs\u002Fzeroclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_e34576ed6608.png\" alt=\"ZeroClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>ZeroClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 9.9K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fnearai\u002Fironclaw\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_93cbef55fa68.png\" alt=\"IronClaw\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>IronClaw\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 2.1K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fanomalyco\u002Fopencode\">\n \u003Cimg src=\".\u002Fpublic\u002Fproviders\u002Fopencode.svg\" alt=\"OpenCode\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>OpenCode\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 106K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_64de00e34e82.png\" alt=\"Codex CLI\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Codex CLI\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 60.8K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_3ad4c120ed4f.png\" alt=\"Claude Code\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Claude Code\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 67.3K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_43f96254a435.png\" alt=\"Gemini CLI\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Gemini CLI\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 94.7K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" width=\"110\">\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FKilo-Org\u002Fkilocode\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_ed3af9be3533.png\" alt=\"Kilo Code\" width=\"48\"\u002F>\u003Cbr\u002F>\n \u003Cb>Kilo Code\u003C\u002Fb>\n \u003C\u002Fa>\u003Cbr\u002F>\n \u003Csub>⭐ 15.5K\u003C\u002Fsub>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\n\u003Csub>📡 所有助手都通过 \u003Ccode>http:\u002F\u002Flocalhost:20128\u002Fv1\u003C\u002Fcode> 或 \u003Ccode>http:\u002F\u002Fcloud.omniroute.online\u002Fv1\u003C\u002Fcode> 连接——只需一次配置，即可使用无限模型和配额。\u003C\u002Fsub>\n\n---\n\n## 🤔 为什么选择 OmniRoute？\n\n**停止浪费金钱和遭遇限制：**\n\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> 订阅配额每月未用完即失效\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> 速率限制让您在编码途中被迫中断\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> 昂贵的 API（每家提供商每月需支付 $20–50）\n- \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F✗-e74c3c?style=flat-square\" height=\"16\"\u002F> 需手动切换各家提供商\n\n**OmniRoute 解决了这些问题：**\n\n- ✅ **最大化订阅价值** - 跟踪配额，在重置前充分利用每一滴资源\n- ✅ **自动回退** - 订阅 → API 密钥 → 廉价方案 → 免费方案，全程无停机\n- ✅ **多账户支持** - 在同一提供商的不同账户间轮询使用\n- ✅ **通用性** - 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw 以及任何其他 CLI 工具\n\n---\n\n## 📧 支持\n\n> 💬 **加入我们的社区！** [WhatsApp 群组](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧并随时了解最新动态。\n\n- **官网**: [omniroute.online](https:\u002F\u002Fomniroute.online)\n- **GitHub**: [github.com\u002Fdiegosouzapw\u002FOmniRoute](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute)\n- **问题追踪**: [github.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues)\n- **WhatsApp**: [社区群组](https:\u002F\u002Fchat.whatsapp.com\u002FJI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **贡献**: 参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，提交拉取请求，或选择一个 `good first issue`\n- **原始项目**: [9router by decolua](https:\u002F\u002Fgithub.com\u002Fdecolua\u002F9router)\n\n### 🐛 如何报告 bug？\n\n在提交问题时，请运行 system-info 命令并附上生成的文件：\n\n```bash\nnpm run system-info\n```\n\n该命令会生成一个 `system-info.txt` 文件，其中包含您的 Node.js 版本、OmniRoute 版本、操作系统详情、已安装的 CLI 工具（qoder、gemini、claude、codex、antigravity、droid 等）、Docker\u002FPM2 的状态以及系统软件包信息——所有这些内容都能帮助我们快速复现您的问题。请将此文件直接附加到您的 GitHub 问题中。\n\n---\n\n## 🔄 工作原理\n\n```\n┌─────────────┐\n│ 您的 CLI │ (Claude Code、Codex、Gemini CLI、OpenClaw、Cursor、Cline...)\n│ 工具 │\n└──────┬──────┘\n │ http:\u002F\u002Flocalhost:20128\u002Fv1\n ↓\n┌─────────────────────────────────────────┐\n│ OmniRoute（智能路由） │\n│ • 格式转换（OpenAI ↔ Claude） │\n│ • 配额跟踪 + 嵌入向量 + 图像处理 │\n│ • 自动刷新令牌 │\n└──────┬──────────────────────────────────┘\n │\n ├─→ [第一层：订阅] Claude Code、Codex、Gemini CLI\n │ ↓ 配额用尽\n ├─→ [第二层：API 密钥] DeepSeek、Groq、xAI、Mistral、NVIDIA NIM 等\n │ ↓ 预算限制\n ├─→ [第三层：廉价方案] GLM（$0.6\u002F100 万 token）、MiniMax（$0.2\u002F100 万 token）\n │ ↓ 预算限制\n └─→ [第四层：免费方案] Qoder、Qwen、Kiro（无限用量）\n\n结果：持续编码，成本极低\n```\n\n---\n\n## 🎯 OmniRoute 解决的问题——30 个真实痛点与用例\n\n> **每位使用 AI 工具的开发者每天都会遇到这些问题。** OmniRoute 就是为解决这些问题而生——从成本超支到地区性封锁，从 OAuth 流程故障到协议操作及企业级可观ability。\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💸 1. “我付了昂贵的订阅费，却仍会被限流打断”\u003C\u002Fb>\u003C\u002Fsummary>\n\n开发者每月需支付 $20–200 不等，以使用 Claude Pro、Codex Pro 或 GitHub Copilot。即便付费，配额也有限制——每日使用时长上限、每周限制，或是每分钟的速率限制。在编码过程中，服务提供商突然停止响应，导致开发者思路中断，效率大打折扣。\n\n**OmniRoute 如何解决这个问题：**\n\n- **智能四层回退** — 如果订阅配额用尽，自动切换到 API Key → 低价 → 免费方案，全程无需人工干预\n- **提供商限制跟踪** — 缓存的配额快照按服务器端计划刷新（默认 `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`），同时支持在 UI 中手动刷新\n- **多账户支持** — 每个提供商支持多个账户，自动轮询切换——当一个账户用尽时，无缝切换到下一个\n- **自定义组合链** — 可自定义回退链，提供 13 种负载均衡策略（优先级、加权、先填满、轮询、P2C、随机、最少使用、成本优化、严格随机、自动、lkgp、上下文优化、**上下文中继**）\n- **结构化组合构建器** — 分步骤构建组合，明确选择提供商、模型和账户，支持重复提供商及固定目标账户\n- **配额感知的 P2C 策略** — 基于二的幂次账户选择现会考虑配额余量、退避机制、近期错误以及连续使用情况\n- **Codex 企业配额** — 直接在仪表板中监控企业\u002F团队工作区的配额\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔌 2. “我需要使用多家提供商，但它们的 API 各不相同”\u003C\u002Fb>\u003C\u002Fsummary>\n\nOpenAI 使用一种格式，Claude（Anthropic）使用另一种，Gemini 则是第三种。如果开发者想测试不同提供商的模型或在它们之间进行回退，就需要重新配置 SDK、更换端点，并处理不兼容的格式问题。而一些自定义提供商（如 FriendLI、NIM）还拥有非标准的模型端点。\n\n**OmniRoute 如何解决这个问题：**\n\n- **统一端点** — 单一的 `http:\u002F\u002Flocalhost:20128\u002Fv1` 作为所有 100 多家提供商的代理\n- **格式转换** — 自动且透明地实现 OpenAI ↔ Claude ↔ Gemini ↔ Responses API 的格式互转\n- **响应净化** — 去除非标准字段（`x_groq`、`usage_breakdown`、`service_tier`），避免这些字段导致 OpenAI SDK v1.83+ 出错\n- **角色归一化** — 将非 OpenAI 提供商的 `developer` 角色转换为 `system`；将 GLM\u002FERNIE 的 `system` 角色转换为 `user`\n- **“思考”标签提取** — 从 DeepSeek R1 等模型中提取 `\u003Cthink>` 块，并将其标准化为 `reasoning_content`\n- **Gemini 的结构化输出** — 自动将 `json_schema` 转换为 `responseMimeType`\u002F`responseSchema`\n- **`stream` 默认为 `false`** — 符合 OpenAI 规范，避免在 Python\u002FRust\u002FGo SDK 中出现意外的 SSE 流\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌐 3. “我的 AI 提供商屏蔽了我的地区\u002F国家”\u003C\u002Fb>\u003C\u002Fsummary>\n\n像 OpenAI 和 Codex 这样的提供商会屏蔽某些地理区域的访问。用户在进行 OAuth 授权或 API 调用时，经常会遇到 `unsupported_country_region_territory` 错误。这对来自发展中国家的开发者来说尤其令人沮丧。\n\n**OmniRoute 如何解决这个问题：**\n\n- **三层代理配置** — 支持全局（所有流量）、单提供商（仅针对某一家提供商）以及单连接\u002F密钥级别的代理配置\n- **彩色代理标识** — 可视化指示：🟢 全局代理，🟡 提供商代理，🔵 连接代理，始终显示当前 IP 地址\n- **通过代理交换 OAuth Token** — OAuth 流程也经过代理，从而解决 `unsupported_country_region_territory` 问题\n- **通过代理测试连接** — 连接测试均使用已配置的代理（不再直接绕过）\n- **SOCKS5 支持** — 完全支持 SOCKS5 代理用于出站路由\n- **TLS 指纹欺骗** — 通过 `wreq-js` 模拟浏览器 TLS 指纹，以绕过机器人检测\n- **CLI 指纹匹配** — 重新排列请求头和请求体字段，使其与原生 CLI 二进制文件的签名一致，从而大幅降低账号被标记的风险。同时保留代理 IP——既能保持隐蔽性，又能实现 IP 匿名化\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🆓 4. “我想用 AI 编程，但我没钱”\u003C\u002Fb>\u003C\u002Fsummary>\n\n并非所有人都能负担每月 20 至 200 美元的 AI 订阅费用。学生、来自新兴国家的开发者、业余爱好者和自由职业者都需要以零成本获取高质量的模型。\n\n**OmniRoute 如何解决这个问题：**\n\n- **内置免费层级提供商** — 原生支持 100% 免费的提供商：Qoder（通过 OAuth 提供 5 款无限量模型：kimi-k2-thinking、qwen3-coder-plus、deepseek-r1、minimax-m2、kimi-k2）；Qwen（4 款无限量模型：qwen3-coder-plus、qwen3-coder-flash、qwen3-coder-next、视觉模型）；Kiro（Claude + AWS Builder ID 免费）；Gemini CLI（每月 18 万 token 免费）\n- **Ollama Cloud** — 在 `api.ollama.com` 上托管的 Ollama 模型，提供免费的“轻量使用”层级；使用 `ollamacloud\u002F\u003Cmodel>` 前缀\n- **纯免费组合链** — 将 `gc\u002Fgemini-3-flash → if\u002Fkimi-k2-thinking → qw\u002Fqwen3-coder-plus` 组合起来，即可实现每月零成本且无中断的服务\n- **NVIDIA NIM 免费访问** — 在 build.nvidia.com 上可获得约 40 RPM 的开发者永久免费访问权限，涵盖 70 多种模型（正从积分模式过渡到纯速率限制模式）\n- **成本优化策略** — 自动选择最便宜可用提供商的路由策略\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔒 5. “我需要保护我的 AI 网关免受未经授权的访问”\u003C\u002Fb>\u003C\u002Fsummary>\n\n当将 AI 网关暴露到网络（LAN、VPS、Docker）时，任何拥有该地址的人都可以消耗开发者的令牌或配额。如果没有保护措施，API 就容易遭到滥用、提示注入等攻击。\n\n**OmniRoute 如何解决这个问题：**\n\n- **API 密钥管理** — 提供按提供商生成、轮换和范围限定密钥的功能，并设有专门的 `\u002Fdashboard\u002Fapi-manager` 页面\n- **模型级权限控制** — 可将 API 密钥限制在特定模型上（如 `openai\u002F*` 或通配符模式），并提供“允许全部”或“限制”开关\n- **API 端点保护** — 要求访问 `\u002Fv1\u002Fmodels` 必须使用密钥，并可阻止特定提供商出现在列表中\n- **认证防护 + CSRF 保护** — 所有仪表板路由均受到 `withAuth` 中间件和 CSRF 令牌的保护\n- **速率限制器** — 基于 IP 的速率限制，窗口时间可配置\n- **IP 过滤** — 提供白名单和黑名单功能，用于访问控制\n- **提示注入防护** — 对恶意提示模式进行净化处理\n- **AES-256-GCM 加密** — 静态存储中的凭据采用加密保护\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛑 6. “我的提供商宕机了，我的编程流程中断了”\u003C\u002Fb>\u003C\u002Fsummary>\n\nAI 提供商可能会变得不稳定，返回 5xx 错误，或遭遇临时的速率限制。如果开发者只依赖一家提供商，就会被打断。如果没有熔断机制，反复重试可能导致应用程序崩溃。\n\n**OmniRoute 如何解决这个问题：**\n\n- **设置驱动的锁定层级** — 提供商配置文件可在同一界面控制默认账户\u002F模型锁定、全局模型隔离以及提供商熔断机制，同时显式上游的 `Retry-After` 窗口仍具有更高优先级\n- **指数退避** — 针对账户\u002F模型锁定以及更高级别的隔离，逐步延长重试间隔\n- **防羊群效应** — 使用互斥锁和信号量保护，防止并发重试风暴\n- **组合回退链** — 如果主提供商失败，系统会自动按链路顺序切换，无需人工干预\n- **组合熔断器** — 自动禁用组合链中出现故障的提供商\n- **健康仪表板** — 提供运行时间监控、熔断状态、锁定情况、缓存统计信息以及 p50\u002Fp95\u002Fp99 延迟数据\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔧 7. “配置每个 AI 工具既繁琐又重复”\u003C\u002Fb>\u003C\u002Fsummary>\n\n开发者会使用 Cursor、Claude Code、Codex CLI、OpenClaw、Gemini CLI、Kilo Code 等工具。每款工具的配置都不一样（API 端点、密钥、模型）。当切换供应商或模型时，重新配置非常耗时。\n\n**OmniRoute 如何解决这个问题：**\n\n- **CLI 工具仪表板** — 专用页面，支持 Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline 的一键设置\n- **GitHub Copilot 配置生成器** — 可为 VS Code 生成 `chatLanguageModels.json` 文件，并支持批量选择模型\n- **入门向导** — 针对首次使用的用户，提供四步引导式设置流程\n- **一个端点，支持所有模型** — 只需配置一次 `http:\u002F\u002Flocalhost:20128\u002Fv1`，即可访问 100 多家服务提供商\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔑 8. “管理多个供应商的 OAuth 令牌简直太麻烦了”\u003C\u002Fb>\u003C\u002Fsummary>\n\nClaude Code、Codex、Gemini CLI、Copilot 等工具都使用 OAuth 2.0 协议，且令牌会过期。开发者需要不断重新认证，还会遇到 `client_secret is missing`、`redirect_uri_mismatch` 等问题，以及在远程服务器上出现的各种失败情况。尤其是在局域网或 VPS 上使用 OAuth 时，问题更加突出。\n\n**OmniRoute 如何解决这个问题：**\n\n- **自动刷新令牌** — OAuth 令牌会在过期前在后台自动刷新\n- **内置 OAuth 2.0 (PKCE)** — 自动化流程适用于 Claude Code、Codex、Gemini CLI、Copilot、Kiro、Qwen、Qoder 等工具\n- **多账号 OAuth** — 通过提取 JWT\u002FID 令牌，支持同一供应商下的多个账号\n- **局域网\u002F远程 OAuth 修复** — 自动检测私有 IP 以设置 `redirect_uri`，同时提供手动 URL 模式用于远程服务器\n- **Nginx 后端 OAuth 支持** — 使用 `window.location.origin` 以兼容反向代理\n- **远程 OAuth 指南** — 提供 Google Cloud 凭证在 VPS\u002FDocker 环境中的详细步骤指南\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📊 9. “我不知道自己花了多少钱，也不知道花在了哪里”\u003C\u002Fb>\u003C\u002Fsummary>\n\n开发者会使用多家付费服务提供商，但却没有统一的费用视图。每个服务商都有自己的计费仪表板，但缺乏整合后的汇总信息。这可能导致意外的成本累积。\n\n**OmniRoute 如何解决这个问题：**\n\n- **成本分析仪表板** — 按照每个供应商跟踪每次调用的费用，并进行预算管理\n- **分级预算限制** — 为每个级别设置支出上限，超出后会自动切换到备用方案\n- **按模型定价配置** — 可针对不同模型自定义价格\n- **按 API 密钥的使用统计** — 记录每个密钥的请求次数及最后使用时间\n- **分析仪表板** — 包括统计卡片、模型使用图表、供应商表格等，显示成功率和延迟信息\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🐛 10. “我无法诊断 AI 调用中的错误和问题”\u003C\u002Fb>\u003C\u002Fsummary>\n\n当调用失败时，开发者往往不清楚是由于速率限制、令牌过期、格式错误，还是服务提供商自身的问题。日志分散在不同的终端中，缺乏可观ability，调试只能靠反复试错。\n\n**OmniRoute 如何解决这个问题：**\n\n- **统一日志仪表板** — 分为四个标签页：请求日志、代理日志、审计日志和控制台\n- **控制台日志查看器** — 实时终端风格的查看器，带有颜色编码等级、自动滚动、搜索和筛选功能\n- **SQLite 摘要日志** — 请求和代理日志索引可在重启后继续查询，而无需将大型负载数据块加载到 SQLite 中\n- **翻译 Playground** — 提供四种调试模式：Playground（格式转换）、Chat Tester（往返测试）、Test Bench（批量测试）和 Live Monitor（实时监控）\n- **请求遥测** — 提供 p50\u002Fp95\u002Fp99 延迟信息以及 X-Request-Id 追踪\n- **基于文件的详细记录** — 应用日志会根据大小、保留天数和归档次数轮转；详细的请求\u002F响应负载则保存在 `DATA_DIR\u002Fcall_logs\u002F` 目录下，并独立于 SQLite 摘要日志进行轮转\n- **系统信息报告** — 运行 `npm run system-info` 可生成包含完整环境信息的 `system-info.txt` 文件（Node 版本、OmniRoute 版本、操作系统、CLI 工具、Docker\u002FPM2 状态等）。提交问题时附上该文件，可帮助快速定位问题。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🏗️ 11. “部署和维护网关很复杂”\u003C\u002Fb>\u003C\u002Fsummary>\n\n在不同环境中（本地、VPS、Docker、云）安装、配置和维护 AI 代理是一项繁重的工作。硬编码路径、目录权限错误（EACCES）、端口冲突以及跨平台构建等问题都会增加难度。\n\n**OmniRoute 如何解决这个问题：**\n\n- **npm 全局安装** — `npm install -g omniroute && omniroute`，简单完成\n- **Docker 多平台支持** — 原生支持 AMD64 和 ARM64 架构（Apple Silicon、AWS Graviton、Raspberry Pi）\n- **Docker Compose 配置文件** — 提供 `base`（不包含 CLI 工具）和 `cli`（包含 Claude Code、Codex、OpenClaw）两种配置\n- **Electron 桌面应用** — 适用于 Windows\u002FmacOS\u002FLinux 的原生应用，配备系统托盘、开机自启动和离线模式\n- **分端口模式** — API 和仪表板分别运行在不同端口上，适用于高级场景（反向代理、容器网络）\n- **云端同步** — 通过 Cloudflare Workers 在不同设备之间同步配置\n- **数据库备份** — 自动备份、恢复、导出和导入所有设置，并提供 `DISABLE_SQLITE_AUTO_BACKUP` 选项，方便外部管理备份\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌍 12. “界面只有英文，我的团队不会说英语”\u003C\u002Fb>\u003C\u002Fsummary>\n\n非英语国家的团队，尤其是拉丁美洲、亚洲和欧洲的团队，常常因为界面仅支持英文而面临困难。语言障碍不仅降低了产品的采用率，还增加了配置错误的可能性。\n\n**OmniRoute 如何解决这个问题：**\n\n- **仪表板国际化 — 支持 30 种语言** — 所有 500 多个文本键均已翻译，包括阿拉伯语、保加利亚语、丹麦语、德语、西班牙语、芬兰语、法语、希伯来语、印地语、匈牙利语、印尼语、意大利语、日语、韩语、马来语、荷兰语、挪威语、波兰语、葡萄牙语（PT\u002FBR）、罗马尼亚语、俄语、斯洛伐克语、瑞典语、泰语、乌克兰语、越南语、中文、菲律宾语以及英语\n- **RTL 支持** — 对阿拉伯语和希伯来语提供从右到左的支持\n- **多语言 README 文档** — 提供 30 种语言的完整文档翻译\n- **语言选择器** — 页眉处的地球图标，可实时切换语言\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔄 13. “我需要的不仅仅是聊天功能——我还想要嵌入向量、图片和音频”\u003C\u002Fb>\u003C\u002Fsummary>\n\nAI 不仅仅局限于聊天补全。开发者还需要生成图片、转录音频、创建用于 RAG 的嵌入向量、对文档进行重新排序以及内容审核等功能。而每种功能对应的 API 端点和格式都不相同。\n\n**OmniRoute 如何解决这个问题：**\n\n- **嵌入** — `\u002Fv1\u002Fembeddings`，支持 6 家供应商和 9 模型以上\n- **图像生成** — `\u002Fv1\u002Fimages\u002Fgenerations`，支持 10 家供应商和 20 模型以上（OpenAI、xAI、Together、Fireworks、Nebius、Hyperbolic、NanoBanana、Antigravity、SD WebUI、ComfyUI）\n- **文本转视频** — `\u002Fv1\u002Fvideos\u002Fgenerations` — ComfyUI（AnimateDiff、SVD）和 SD WebUI\n- **文本转音乐** — `\u002Fv1\u002Fmusic\u002Fgenerations` — ComfyUI（Stable Audio Open、MusicGen）\n- **音频转录** — `\u002Fv1\u002Faudio\u002Ftranscriptions` — Whisper + Nvidia NIM、HuggingFace、Qwen3\n- **文本转语音** — `\u002Fv1\u002Faudio\u002Fspeech` — ElevenLabs、Nvidia NIM、HuggingFace、Coqui、Tortoise、Qwen3、**Inworld**、**Cartesia**、**PlayHT**，以及现有供应商\n- **内容审核** — `\u002Fv1\u002Fmoderations` — 内容安全检查\n- **重排序** — `\u002Fv1\u002Frerank` — 文档相关性重排序\n- **响应 API** — 对 Codex 的完整 `\u002Fv1\u002Fresponses` 支持\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 14. “我没有办法测试和比较不同模型的质量”\u003C\u002Fb>\u003C\u002Fsummary>\n\n开发者希望知道哪种模型最适合自己的应用场景——代码生成、翻译、推理等——但手动比较效率太低。目前还没有集成的评估工具。\n\n**OmniRoute 如何解决：**\n\n- **LLM 评估** — 使用预加载的 10 个案例进行黄金集测试，涵盖问候语、数学、地理、代码生成、JSON 格式合规性、翻译、Markdown 和安全性拒绝等内容\n- **4 种匹配策略** — `exact`、`contains`、`regex` 和 `custom`（JS 函数）\n- **翻译器 Playground 测试台** — 批量测试，支持多组输入和预期输出，并可跨供应商对比\n- **聊天测试器** — 全流程交互，可视化响应结果\n- **实时监控** — 实时展示所有通过代理的请求流\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📈 15. “我需要在不降低性能的情况下扩展规模”\u003C\u002Fb>\u003C\u002Fsummary>\n\n随着请求量的增长，如果没有缓存机制，相同的查询会导致重复计算，浪费成本。而缺乏幂等性则会使重复请求白白占用处理资源。此外，还需遵守各供应商的速率限制。\n\n**OmniRoute 如何解决：**\n\n- **语义缓存** — 两层缓存（签名 + 语义），有效降低成本并减少延迟\n- **请求幂等性** — 为相同请求提供 5 秒去重窗口\n- **速率限制检测** — 分别跟踪每个供应商的 RPM、最小间隔和最大并发数\n- **可编辑的速率限制** — 在“设置 → 弹性”中配置默认值，并持久化保存\n- **API 密钥验证缓存** — 三层缓存，确保生产环境性能\n- **健康仪表盘与遥测** — 提供 p50\u002Fp95\u002Fp99 延迟、缓存统计和运行时间等信息\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🤖 16. “我想全局控制模型行为”\u003C\u002Fb>\u003C\u002Fsummary>\n\n开发者希望所有响应都以特定语言呈现、采用特定语气，或者限制推理 token 数量。如果要在每个工具或每次请求中单独配置，显然不现实。\n\n**OmniRoute 如何解决：**\n\n- **系统提示注入** — 全局应用到所有请求的提示\n- **思考预算验证** — 每个请求的推理 token 分配控制（透传、自动、自定义、适应性）\n- **9 种路由策略** — 全局策略决定请求如何分发\n- **通配符路由器** — 使用 `provider\u002F*` 模式动态路由到任意供应商\n- **组合启用\u002F禁用切换** — 可直接在仪表盘上切换组合\n- **手动组合排序** — 拖动组合卡片调整顺序，并将排序结果持久化到 SQLite 中\n- **供应商开关** — 一键启用或禁用某个供应商的所有连接\n- **被屏蔽的供应商** — 将特定供应商从 `\u002Fv1\u002Fmodels` 列表中排除\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧰 17. “我需要将 MCP 工具作为一级产品功能”\u003C\u002Fb>\u003C\u002Fsummary>\n\n许多 AI 网关仅将 MCP 隐藏为实现细节，而团队需要一个可见且易于管理的操作层。\n\n**OmniRoute 如何解决：**\n\n- MCP 出现在仪表盘导航和端点协议选项卡中\n- 专门的 MCP 管理页面，包含流程、工具、作用域和审计记录\n- 内置快速入门指南，用于 `omniroute --mcp` 和客户端接入\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧠 18. “我需要同步与流式任务路径的 A2A 协调”\u003C\u002Fb>\u003C\u002Fsummary>\n\n智能体工作流既需要直接回复，也需要长时间的流式执行，并能够控制其生命周期。\n\n**OmniRoute 如何解决：**\n\n- A2A JSON-RPC 端点（`POST \u002Fa2a`），支持 `message\u002Fsend` 和 `message\u002Fstream`\n- SSE 流式传输，可传递终端状态\n- 任务生命周期 API，用于 `tasks\u002Fget` 和 `tasks\u002Fcancel`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛰️ 19. “我需要真实的 MCP 进程健康状况，而不是猜测的状态”\u003C\u002Fb>\u003C\u002Fsummary>\n\n运维团队需要了解 MCP 是否真正存活，而不仅仅是 API 是否可达。\n\n**OmniRoute 如何解决：**\n\n- 运行时心跳文件，包含 PID、时间戳、传输方式、工具数量和作用域模式\n- MCP 状态 API 结合心跳和近期活动情况\n- UI 状态卡片显示进程\u002F运行时间\u002F心跳新鲜度\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📋 20. “我需要可审计的 MCP 工具执行记录”\u003C\u002Fb>\u003C\u002Fsummary>\n\n当工具修改配置或触发运维操作时，团队需要具备法医级别的可追溯性。\n\n**OmniRoute 如何解决：**\n\n- 基于 SQLite 的审计日志记录 MCP 工具调用\n- 支持按工具、成功\u002F失败、API 密钥筛选，并提供分页功能\n- 仪表盘审计表格及自动化统计端点\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔐 21. “我需要按集成划分的 MCP 权限”\u003C\u002Fb>\u003C\u002Fsummary>\n\n不同的客户应仅拥有对工具类别的最小权限访问。\n\n**OmniRoute 如何解决：**\n\n- 10 种细粒度的 MCP 作用域，用于控制工具访问\n- 在 MCP 管理界面中强制实施作用域并控制可见性\n- 为运维工具设置安全的默认配置\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>⚙️ 22. “我需要无需重新部署即可进行的运维控制”\u003C\u002Fb>\u003C\u002Fsummary>\n\n团队需要在突发事件或成本事件发生时，快速调整运行时配置。\n\n**OmniRoute 如何解决：**\n\n- 直接在 MCP 仪表盘上切换组合激活状态\n- 从预定义的策略包中应用弹性配置\n- 从同一运维面板重置熔断器状态\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔄 23. “我需要实时查看和取消 A2A 任务生命周期”\u003C\u002Fb>\u003C\u002Fsummary>\n\n如果没有生命周期的可见性，任务故障将难以诊断。\n\n**OmniRoute 如何解决：**\n\n- 按状态和技能列出并筛选任务，支持分页\n- 可深入查看任务元数据、事件和产物\n- 提供任务取消端点和 UI 操作，并带有确认提示\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌊 24. “我需要 A2A 负载的实时流指标”\u003C\u002Fb>\u003C\u002Fsummary>\n\n流式工作流需要对并发性和实时连接有清晰的运营洞察。\n\n**OmniRoute 如何解决：**\n\n- 将活跃流计数器集成到 A2A 状态中\n- 显示最后任务的时间戳和各状态下的任务数量\n- A2A 仪表盘卡片，用于实时监控运营状况\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🪪 25. “我需要面向客户的标准化智能体发现”\u003C\u002Fb>\u003C\u002Fsummary>\n\n外部客户和编排器需要机器可读的元数据来进行接入。\n\n**OmniRoute 如何解决：**\n\n- 代理卡片在 `\u002F.well-known\u002Fagent.json` 中公开\n- 管理 UI 中展示了功能和技能\n- A2A 状态 API 包含用于自动化的发现元数据\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧭 26. “我需要在产品用户体验中实现协议可发现性”\u003C\u002Fb>\u003C\u002Fsummary>\n\n如果用户无法发现协议接口，采用率和支持质量就会下降。\n\n**OmniRoute 的解决方案：**\n\n- 整合的 **端点** 页面，设有代理、MCP、A2A 和 API 端点选项卡\n- MCP 和 A2A 的内联服务状态切换（在线\u002F离线）\n- 从概览页面到专用管理选项卡的链接\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 27. “我需要使用真实客户端进行端到端协议验证”\u003C\u002Fb>\u003C\u002Fsummary>\n\n仅靠模拟测试不足以在发布前验证协议兼容性。\n\n**OmniRoute 的解决方案：**\n\n- E2E 套件会启动应用，并使用真实的 MCP SDK 客户端传输层\n- A2A 客户端测试涵盖发现、发送、流式传输、获取和取消流程\n- 对 MCP 审计和 A2A 任务 API 进行交叉检查断言\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📡 28. “我需要跨所有接口的统一可观测性”\u003C\u002Fb>\u003C\u002Fsummary>\n\n按协议划分可观测性会导致盲区并延长 MTTR。\n\n**OmniRoute 的解决方案：**\n\n- 在一个产品中提供统一的仪表盘、日志和分析\n- 覆盖 OpenAI、MCP 和 A2A 层的健康状况、审计和请求遥测\n- 提供用于状态监控和自动化的运营 API\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💼 29. “我需要一个运行时来同时处理代理、工具和代理编排”\u003C\u002Fb>\u003C\u002Fsummary>\n\n运行多个独立的服务会增加运营成本并引入更多故障模式。\n\n**OmniRoute 的解决方案：**\n\n- 将兼容 OpenAI 的代理、MCP 服务器和 A2A 服务器集成在一个堆栈中\n- 共享身份验证、弹性、数据存储和可观测性\n- 在所有交互界面中保持一致的策略模型\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🚀 30. “我需要在不产生大量胶水代码的情况下部署智能体工作流”\u003C\u002Fb>\u003C\u002Fsummary>\n\n当团队拼接多个临时服务和脚本时，开发速度会显著下降。\n\n**OmniRoute 的解决方案：**\n\n- 面向客户端和智能体的统一端点策略\n- 内置的协议管理 UI 和冒烟测试路径\n- 生产就绪的基础架构（安全性、日志记录、弹性和备份）\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📚 31. “我的长时间会话会因‘context_length_exceeded’限制而崩溃”\u003C\u002Fb>\u003C\u002Fsummary>\n\n在深度调试过程中，包含工具结果的长对话历史会迅速超出提供商的令牌窗口，导致请求失败和孤立的上下文。\n\n**OmniRoute 的解决方案：**\n\n- **主动上下文压缩** — 在请求到达上游之前评估令牌预算，并通过智能二分查找机制主动修剪旧的对话历史。\n- **结构完整性保护** — 自动跟踪显式的 `tool_use` 定义，并确保如果工具输入被截断，其对应的 `tool_result` 也会被安全移除，从而防止 API 验证错误。\n- **多层丢弃** — 逐步丢弃系统消息、常规消息，最终严格执行长度限制，同时不破坏对话逻辑。\n\n\u003C\u002Fdetails>\n\n\n\n### 示例剧本（集成用例）\n\n**剧本 A：最大化付费订阅 + 廉价备份**\n\n```txt\n组合：“maximize-claude”\n 1. cc\u002Fclaude-opus-4-6\n 2. glm\u002Fglm-4.7\n 3. if\u002Fkimi-k2-thinking\n\n月度成本：$20 + 少量备份支出\n结果：更高品质，几乎零中断\n```\n\n**剧本 B：零成本编码栈**\n\n```txt\n组合：“free-forever”\n 1. gc\u002Fgemini-3-flash\n 2. if\u002Fkimi-k2-thinking\n 3. qw\u002Fqwen3-coder-plus\n\n月度成本：$0\n结果：稳定的免费编码工作流\n```\n\n**剧本 C：24\u002F7 永久可用的后备链**\n\n```txt\n组合：“always-on”\n 1. cc\u002Fclaude-opus-4-6\n 2. cx\u002Fgpt-5.2-codex\n 3. glm\u002Fglm-4.7\n 4. minimax\u002FMiniMax-M2.1\n 5. if\u002Fkimi-k2-thinking\n\n结果：为关键任务负载提供深度后备能力\n```\n\n**剧本 D：使用 MCP + A2A 进行智能体操作**\n\n```txt\n1) 启动 MCP 传输（`omniroute --mcp`）以进行工具驱动的操作\n2) 通过 `message\u002Fsend` 和 `message\u002Fstream` 运行 A2A 任务\n3) 通过 \u002Fdashboard\u002Fendpoint（MCP 和 A2A 选项卡）进行观察\n4) 使用内联状态控件切换服务\n```\n\n---\n\n## 🆓 免费开始 — 零配置成本\n\n> 在几分钟内即可设置 AI 编码，每月费用为 **$0**。连接这些免费账户，并使用内置的 **Free Stack** 组合。\n\n| 步骤 | 操作 | 解锁的提供商 |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | 连接 **Kiro**（AWS Builder ID OAuth） | Claude Sonnet 4.5、Haiku 4.5 — **无限量** |\n| 2 | 连接 **Qoder**（Google OAuth） | kimi-k2-thinking、qwen3-coder-plus、deepseek-r1... — **无限量** |\n| 3 | 连接 **Qwen**（设备码） | qwen3-coder-plus、qwen3-coder-flash... — **无限量** |\n| 4 | 连接 **Gemini CLI**（Google OAuth） | gemini-3-flash、gemini-2.5-pro — **每月免费 18 万次调用** |\n| 5 | `\u002Fdashboard\u002Fcombos` → **Free Stack ($0)** 模板 | 自动轮换所有免费提供商 |\n\n**将任何 IDE\u002FCLI 指向：** `http:\u002F\u002Flocalhost:20128\u002Fv1` · API 密钥：`any-string` · 完成。\n\n> **可选额外覆盖（同样免费）：** Groq API 密钥（免费 30 RPM）、NVIDIA NIM（免费 40 RPM，70 多种模型）、Cerebras（每天 100 万个 token）、LongCat API 密钥（每天 5000 万个 token！）、Cloudflare Workers AI（每天 1 万个神经元，50 多种模型）。\n\n## ⚡ 快速入门\n\n### 1) 安装并运行\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm 用户：** 安装后运行 `pnpm approve-builds -g` 以启用 `better-sqlite3` 和 `@swc\u002Fcore` 所需的原生构建脚本：\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # 选择所有包 → 批准\n> omniroute\n> ```\n\n仪表盘将在 `http:\u002F\u002Flocalhost:20128` 打开，API 基础 URL 为 `http:\u002F\u002Flocalhost:20128\u002Fv1`。\n\n| 命令 | 描述 |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | 启动服务器（`PORT=20128`，API 和仪表盘在同一端口） |\n| `omniroute --port 3000` | 将标准\u002FAPI 端口设置为 3000 |\n| `omniroute --mcp` | 启动 MCP 服务器（stdio 传输） |\n| `omniroute --no-open` | 不自动打开浏览器 |\n| `omniroute --help` | 显示帮助 |\n\n可选的分端口模式：\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http:\u002F\u002Flocalhost:20128\u002Fv1\n# Dashboard: http:\u002F\u002Flocalhost:20129\n```\n\n### 2) 卸载\n\n当您不再需要 OmniRoute 时，我们提供了两个快速脚本来进行干净卸载：\n\n| 命令 | 操作 |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | 移除系统应用，但会**保留您的数据库和配置**在 `~\u002F.omniroute` 中。 |\n| `npm run uninstall:full` | 移除应用并永久**清除所有配置、密钥和数据库**。 |\n\n> 注意：要运行这些命令，请导航到 OmniRoute 项目文件夹（如果您克隆了它），然后执行。或者，如果已全局安装，您可以直接运行 `npm uninstall -g omniroute`。\n\n### 长时间流式传输超时\n\n对于大多数部署，您只需要：\n\n| 变量 | 默认 | 用途 |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | 上游响应开始超时的共享基线，隐藏的 Undici 超时、TLS 指纹请求以及 API 网关请求\u002F代理超时 |\n| `STREAM_IDLE_TIMEOUT_MS` | 继承自 `REQUEST_TIMEOUT_MS` | 流式传输块之间的最大间隔，超过该时间 OmniRoute 将中止 SSE 流 |\n\n向后兼容性得以保留：现有的 `FETCH_TIMEOUT_MS`、`API_BRIDGE_PROXY_TIMEOUT_MS` 等各层超时变量仍然有效，并会覆盖共享基线。\n\n对于与 Claude Code 兼容的上游服务（`anthropic-compatible-cc-*`），OmniRoute 还会根据解析后的 fetch 超时值推导出 outbound 的 `X-Stainless-Timeout` 头，以确保提供商端的读取超时与您的环境配置保持一致。\n\n对于第三方与 Claude Code 兼容的反向代理，OmniRoute 会将默认的 `anthropic-beta` 设置得较为保守，并且当 `Client Cache Control` 保持为 `Auto` 时，只会转发客户端提供的 `cache_control` 标记。如果请求中不包含 `cache_control`，OmniRoute 不会注入网关自身的标记。\n\n如果您需要更精细的控制，还可以使用高级覆盖选项：\n\n| 变量 | 默认 | 用途 |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | 继承自 `REQUEST_TIMEOUT_MS` | 上游响应开始前的超时，直到收到响应头为止 |\n| `FETCH_HEADERS_TIMEOUT_MS` | 继承自 `FETCH_TIMEOUT_MS` | Undici 接收上游响应头的时间限制 |\n| `FETCH_BODY_TIMEOUT_MS` | 继承自 `FETCH_TIMEOUT_MS` | Undici 上游数据块之间的时间限制（设置为 `0` 则禁用） |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP 连接超时 |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici 空闲保持连接的套接字超时 |\n| `TLS_CLIENT_TIMEOUT_MS` | 继承自 `FETCH_TIMEOUT_MS` | 通过 `wreq-js` 发起的 TLS 指纹请求的超时 |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | 继承自 `REQUEST_TIMEOUT_MS` 或 `30000` | 从 API 端口到仪表板端口的 `\u002Fv1` 代理转发超时 |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | API 网关服务器上的入站请求超时 |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | API 网关服务器上的入站头部超时 |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | API 网关服务器上的保持连接超时 |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | API 网关服务器上的套接字非活动超时（设置为 `0` 则禁用）|\n\n对于流式请求，`FETCH_TIMEOUT_MS` 仅涵盖连接建立和等待第一个上游响应的过程。一旦流开始传输，OmniRoute 只会在实际停滞（`STREAM_IDLE_TIMEOUT_MS`）或 Undici 数据块长时间无活动（`FETCH_BODY_TIMEOUT_MS`）时才会中断流。\n\n如果您在 Nginx、Caddy、Cloudflare 或其他反向代理之后运行 OmniRoute，请确保代理的超时设置也高于 OmniRoute 的流式传输或 fetch 超时。\n\n### 2) 连接提供商并创建您的 API 密钥\n\n1. 打开仪表板 → `Providers`，至少连接一个提供商（OAuth 或 API 密钥）。\n2. 打开仪表板 → `Endpoints`，创建一个 API 密钥。\n3. （可选）打开仪表板 → `Combos`，设置您的回退链。\n\n### 3) 将您的编码工具指向 OmniRoute\n\n```txt\n基础 URL：http:\u002F\u002Flocalhost:20128\u002Fv1\nAPI 密钥：[从 Endpoint 页面复制]\n模型：if\u002Fkimi-k2-thinking（或任何提供商\u002F模型前缀）\n```\n\n适用于 Claude Code、Codex CLI、Gemini CLI、Cursor、Cline、OpenClaw、OpenCode 以及与 OpenAI 兼容的 SDK。\n\n### 4) 启用并验证协议（v2.0）\n\n**MCP（用于工具驱动的操作）：**\n\n```bash\nomniroute --mcp\n```\n\n然后通过 `stdio` 连接您的 MCP 客户端，并测试以下工具：\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A（用于代理间工作流）：**\n\n```bash\ncurl http:\u002F\u002Flocalhost:20128\u002F.well-known\u002Fagent.json\n```\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:20128\u002Fa2a \\\n -H 'content-type: application\u002Fjson' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message\u002Fsend\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"给我一个简短的配额摘要。\"}]}}'\n```\n\n### 5) 全流程端到端验证（推荐）\n\n```bash\nnpm run test:protocols:e2e\n```\n\n此套件会针对正在运行的应用程序验证真实的 MCP 和 A2A 客户端流程。\n\n### 替代方案：从源代码运行\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http:\u002F\u002Flocalhost:20129 npm run dev\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Void Linux (`xbps-src` 模板)\u003C\u002Fb>\u003C\u002Fsummary>\n\n对于 Void Linux 用户，您可以使用 `xbps-src` 构建原生软件包。将以下内容保存为 `srcpkgs\u002Fomniroute\u002Ftemplate`：\n\n```bash\n\n# ‘omniroute’ 的模板文件\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"支持多模型提供商的智能路由通用 AI 网关\"\nmaintainer=\"zenobit \u003Czenobit@disroot.org>\"\nlicense=\"MIT\"\nhomepage=\"https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\"\ndistfiles=\"https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Farchive\u002Frefs\u002Ftags\u002Fv${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"\u002Fvar\u002Flib\u002Fomniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# 根据目标 CPU 架构确定 node-gyp 使用的架构\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) 安装所有依赖 – 跳过脚本（do_build 中无网络，原生模块将在下面单独编译；better-sqlite3 是 serverExternalPackage，因此 Next.js 在 next build 期间不会执行它）\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) 构建 Next.js 单体包\n\tnpm run build\n\n\t# 3) 将静态资源复制到单体包中\n\tcp -r .next\u002Fstatic .next\u002Fstandalone\u002F.next\u002Fstatic\n\t[ -d public ] && cp -r public .next\u002Fstandalone\u002Fpublic || true\n\n\t# 4) 为目标架构编译 better-sqlite3 的原生绑定。\n\t# 直接使用 node-gyp，以便利用 xbps-src 交叉工具链中的 CC\u002FCXX，而不会被 npm 修改。\n\tlocal _node_gyp=\u002Fusr\u002Flib\u002Fnode_modules\u002Fnpm\u002Fnode_modules\u002Fnode-gyp\u002Fbin\u002Fnode-gyp.js\n\t(cd node_modules\u002Fbetter-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) 将编译好的绑定放入单体包中\n\tlocal _bs3_release=.next\u002Fstandalone\u002Fnode_modules\u002Fbetter-sqlite3\u002Fbuild\u002FRelease\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules\u002Fbetter-sqlite3\u002Fbuild\u002FRelease\u002Fbetter_sqlite3.node \"$_bs3_release\u002F\"\n\n\t# 6) 移除特定于架构的 sharp 包 – 上游设置了 images.unoptimized=true，因此运行时不会使用 sharp；x64 的 .so 文件会破坏 aarch64 的剥离过程\n\trm -rf .next\u002Fstandalone\u002Fnode_modules\u002F@img\n\n\t# 7) 复制 Next.js 静态分析遗漏的 pino 运行时依赖：\n\t# pino-abstract-transport – pino 工作线程所需\n\t# split2 – pino-abstract-transport 的依赖\n\t# process-warning – pino 自身的依赖\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules\u002F$_mod\" .next\u002Fstandalone\u002Fnode_modules\u002F\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr\u002Flib\u002Fomniroute\u002F.next\n\n\tvcopy .next\u002Fstandalone\u002F. usr\u002Flib\u002Fomniroute\u002F.next\u002Fstandalone\n\n\t# 防止安装后钩子删除空的 Next.js 应用路由器目录\n\tfor _d in \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard\u002Fsettings \\\n\t\t.next\u002Fstandalone\u002F.next\u002Fserver\u002Fapp\u002Fdashboard\u002Fproviders; do\n\t\ttouch \"${DESTDIR}\u002Fusr\u002Flib\u002Fomniroute\u002F${_d}\u002F.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}\u002Fomniroute\" \u003C\u003C'EOF'\n#!\u002Fbin\u002Fsh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}\u002F.local\u002Fshare}\u002Fomniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node \u002Fusr\u002Flib\u002Fomniroute\u002F.next\u002Fstandalone\u002Fserver.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}\u002Fomniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 🐳 Docker\n\nOmniRoute 已作为公共 Docker 镜像发布在 [Docker Hub](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute) 上。\n\n**快速运行：**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:\u002Fapp\u002Fdata \\\n diegosouzapw\u002Fomniroute:latest\n```\n\n**使用环境文件：**\n\n```bash\n# 先复制并编辑 .env 文件\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:\u002Fapp\u002Fdata \\\n diegosouzapw\u002Fomniroute:latest\n```\n\n**使用 Docker Compose：**\n\n```bash\n# 基础配置文件（不包含 CLI 工具）\ndocker compose --profile base up -d\n\n# CLI 配置文件（内置 Claude Code、Codex、OpenClaw）\ndocker compose --profile cli up -d\n```\n\nDocker 部署的仪表板现在新增了一键式 **Cloudflare Quick Tunnel** 功能，位于“仪表板 → 终端节点”中。首次启用时，系统仅在需要时下载 `cloudflared`，启动一个临时隧道连接到当前的 `\u002Fv1` 端点，并将生成的 `https:\u002F\u002F*.trycloudflare.com\u002Fv1` URL 直接显示在您正常的公开 URL 下方。\n\n注意事项：\n\n- Quick Tunnel URL 是临时的，每次重启后都会变化。\n- Quick Tunnels 不会在 OmniRoute 或容器重启后自动恢复。如有需要，请从仪表板重新启用。\n- 当前的托管安装支持 Linux、macOS 和 Windows 的 `x64` 和 `arm64` 架构。\n- 托管的 Quick Tunnels 默认使用 HTTP\u002F2 传输协议，以避免在受限的容器环境中出现嘈杂的 QUIC UDP 缓冲警告。如果您希望使用其他传输方式，可以设置 `CLOUDFLARED_PROTOCOL=quic` 或 `auto`。\n- Docker 镜像捆绑了系统 CA 根证书，并将其传递给托管的 `cloudflared`，从而避免在容器内部建立隧道时出现 TLS 信任失败。\n- SQLite 以 WAL 模式运行。应允许 `docker stop` 完成，以便 OmniRoute 可以将最新更改检查点写回 `storage.sqlite`。\n- 捆绑的 Compose 文件已设置 40 秒的停止宽限期。如果您直接运行镜像，请保持 `--stop-timeout 40`（或类似设置），以免手动停止中断关闭清理流程。\n- 如果您希望 OmniRoute 使用现有的二进制文件而不是下载新版本，可以设置 `CLOUDFLARED_BIN=\u002Fabsolute\u002Fpath\u002Fto\u002Fcloudflared`。\n\n**使用 Docker Compose 结合 Caddy（HTTPS 自动 TLS）：**\n\nOmniRoute 可以通过 Caddy 的自动 SSL 证书颁发功能安全地对外暴露。请确保您的域名 DNS A 记录指向服务器的 IP 地址。\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw\u002Fomniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:\u002Fapp\u002Fdata\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https:\u002F\u002Fyour-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https:\u002F\u002Fyour-domain.com --to http:\u002F\u002Fomniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| 镜像 | 标签 | 大小 | 描述 |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw\u002Fomniroute` | `latest` | ~250MB | 最新稳定版 |\n| `diegosouzapw\u002Fomniroute` | `3.6.2` | ~250MB | 当前版本 |\n\n---\n\n## 🖥️ 桌面应用 — 离线且常驻\n\n> 🆕 **全新！** OmniRoute 现已推出适用于 Windows、macOS 和 Linux 的 **原生桌面应用程序**。\n\n将 OmniRoute 作为独立的桌面应用运行——无需终端、无需浏览器，本地模型也不需要互联网连接。基于 Electron 的应用包含：\n\n- 🖥️ **原生窗口** — 专用应用窗口，支持系统托盘集成\n- 🔄 **自动启动** — 在系统登录时自动启动 OmniRoute\n- 🔔 **原生通知** — 在配额用尽或服务提供商出现问题时接收提醒\n- ⚡ **一键安装** — NSIS（Windows）、DMG（macOS）、AppImage（Linux）\n- 🌐 **离线模式** — 搭载内置服务器，完全离线工作\n\n### 快速入门\n\n```bash\n# 开发模式\nnpm run electron:dev\n\n# 构建适用于您平台的版本\nnpm run electron:build # 当前平台\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) — x64 和 arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### 系统托盘\n\n最小化后，OmniRoute 会驻留在系统托盘中，并提供快速操作：\n\n- 打开仪表板\n- 更改服务器端口\n- 退出应用\n\n📖 完整文档：[`electron\u002FREADME.md`](electron\u002FREADME.md)\n\n---\n\n## 💰 价格一览\n\n| 层级 | 提供商 | 费用 | 配额重置 | 适合人群 |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **💳 订阅** | Claude Code (Pro) | $20\u002F月 | 5小时 + 每周 | 已订阅用户 |\n| | Codex (Plus\u002FPro) | $20–200\u002F月 | 5小时 + 每周 | OpenAI 用户 |\n| | Gemini CLI | **免费** | 18万\u002F月 + 1千\u002F天 | 人人适用！ |\n| | GitHub Copilot | $10–19\u002F月 | 每月 | GitHub 用户 |\n| **🔑 API 密钥** | NVIDIA NIM | **免费**（开发环境永久免费） | ~40 RPM | 70+ 开源模型 |\n| | Cerebras | **免费**（每天100万标记） | 6万 TPM \u002F 30 RPM | 全球最快的 |\n| | Groq | **免费**（30 RPM） | 1.44万 RPD | 超高速 Llama\u002FGemma |\n| | DeepSeek V3.2 | $0.27\u002F$1.10 每100万标记 | 无 | 理论推理性价比最高 |\n| | xAI Grok-4 Fast | **$0.20\u002F$0.50 每100万标记** 🆕 | 无 | 最快且支持工具调用，超低成本 |\n| | xAI Grok-4（标准版） | $0.20\u002F$1.50 每100万标记 🆕 | 无 | xAI 的旗舰推理模型 |\n| | Mistral | 免费试用 + 付费 | 速率限制 | 欧洲人工智能 |\n| | OpenRouter | 按使用付费 | 无 | 超过100个模型聚合 |\n| **💰 廉价** | GLM-5（通过 Z.AI）🆕 | $0.5\u002F100万标记 | 每日10点 | 输出高达12.8万标记，最新旗舰 |\n| | GLM-4.7 | $0.6\u002F100万标记 | 每日10点 | 预算型备份 |\n| | MiniMax M2.5 🆕 | $0.3\u002F100万输入标记 | 5小时滚动 | 理论推理及智能任务 |\n| | MiniMax M2.1 | $0.2\u002F100万标记 | 5小时滚动 | 最经济实惠的选择 |\n| | Kimi K2.5（Moonshot API）🆕 | 按使用付费 | 无 | 直接访问 Moonshot API |\n| | Kimi K2 | $9\u002F月固定费用 | 每月1000万标记 | 成本可预测 |\n| **🆓 免费** | Qoder | **$0** | 无限量 | 5个模型无限量使用 |\n| | Qwen | **$0** | 无限量 | 4个模型无限量使用 |\n| | Kiro | **$0** | 无限量 | Claude Sonnet\u002FHaiku（AWS Builder） |\n| | LongCat Flash-Lite 🆕 | **$0**（每日5000万标记🔥） | 1 RPS | 地球上最大的免费配额 |\n| | Pollinations AI 🆕 | **$0**（无需密钥） | 每15秒1次请求 | GPT-5、Claude、DeepSeek、Llama 4 |\n| | Cloudflare Workers AI 🆕 | **$0**（每天1万个神经元） | 每天约150次响应 | 超过50个模型，全球边缘计算节点 |\n| | Scaleway AI 🆕 | **$0**（总共100万标记） | 速率限制 | 欧盟\u002FGDPR，Qwen3 235B，Llama 70B |\n\n> 🆕 **2026年3月新增模型：** Grok-4 Fast 系列，定价为每100万标记$0.20\u002F$0.50（基准测试耗时1143毫秒，比 Gemini 2.5 Flash 快30%）；GLM-5 通过 Z.AI 提供，输出高达12.8万标记；MiniMax M2.5 推理模型；DeepSeek V3.2 更新定价；Kimi K2.5 通过 Moonshot 直接 API 提供。\n\n**💡 $0 组合堆栈 — 完全免费配置：**\n\n```\n# 🆒 2026年终极免费堆栈 — 11家服务商，永久$0\nKiro (kr\u002F) → Claude Sonnet\u002FHaiku 无限量\nQoder (if\u002F) → kimi-k2-thinking、qwen3-coder-plus、deepseek-r1 无限量\nLongCat Lite (lc\u002F) → LongCat-Flash-Lite — 每日5000万标记🔥\nPollinations (pol\u002F) → GPT-5、Claude、DeepSeek、Llama 4 — 不需密钥\nQwen (qw\u002F) → qwen3-coder-plus、qwen3-coder-flash、qwen3-coder-next 无限量\nGemini (gemini\u002F) → Gemini 2.5 Flash — 每天1500次请求免费API密钥\nCloudflare AI (cf\u002F) → Llama 70B、Gemma 3、Mistral — 每天1万个神经元\nScaleway (scw\u002F) → Qwen3 235B、Llama 70B — 100万免费标记（欧盟）\nGroq (groq\u002F) → Llama\u002FGemma 超高速 — 每天1.44万次请求\nNVIDIA NIM (nvidia\u002F) → 70+ 开源模型 — 永久40 RPM\nCerebras (cerebras\u002F) → Llama\u002FQwen 全球最快 — 每天100万标记\n```\n\n**零成本。永不停歇地编码。** 将这些配置为一个 OmniRoute 组合，所有备用方案都会自动切换——无需手动操作。\n\n---\n\n---\n\n## 🆒 免费模型 — 您真正能获得什么\n\n> 以下所有模型均 **100% 免费，无需任何信用卡信息**。当某个模型的配额用尽时，OmniRoute 会自动在它们之间切换——将它们全部组合起来，即可获得牢不可破的 $0 组合。\n\n### 🔵 CLAUDE 模型（通过 Kiro — AWS Builder ID）\n\n| 模型 | 前缀 | 限制 | 速率限制 |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr\u002F` | **无限量** | 未报告每日上限 |\n| `claude-haiku-4.5` | `kr\u002F` | **无限量** | 未报告每日上限 |\n| `claude-opus-4.6` | `kr\u002F` | **无限量** | Kiro 提供的最新 Opus |\n\n### 🟢 QODER 模型（通过 qodercli 免费 PAT）\n\n| 模型 | 前缀 | 限制 | 速率限制 |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if\u002F` | **无限** | 未报告上限 |\n| `qwen3-coder-plus` | `if\u002F` | **无限** | 未报告上限 |\n| `deepseek-r1` | `if\u002F` | **无限** | 未报告上限 |\n| `minimax-m2.1` | `if\u002F` | **无限** | 未报告上限 |\n| `kimi-k2` | `if\u002F` | **无限** | 未报告上限 |\n\n> 推荐连接方式：**个人访问令牌 + `qodercli`**。浏览器 OAuth 处于实验阶段，默认已禁用，除非配置了 `QODER_OAUTH_*` 环境变量。\n\n### 🟡 QWEN 模型（设备码认证）\n\n| 模型 | 前缀 | 限制 | 速率限制 |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw\u002F` | **无限** | 未报告上限 |\n| `qwen3-coder-flash` | `qw\u002F` | **无限** | 未报告上限 |\n| `qwen3-coder-next` | `qw\u002F` | **无限** | 未报告上限 |\n| `vision-model` | `qw\u002F` | **无限** | 多模态（图像） |\n\n### 🟣 GEMINI CLI（Google OAuth）\n\n| 模型 | 前缀 | 限制 | 速率限制 |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc\u002F` | **18万 token\u002F月** + 1千\u002Fday | 每月重置 |\n| `gemini-2.5-pro` | `gc\u002F` | 18万\u002F月（共享池） | 高质量 |\n\n### ⚫ NVIDIA NIM（免费 API 密钥 — build.nvidia.com）\n\n| 等级 | 日限额 | 速率限制 | 备注 |\n| ---------- | -------- | ---------- | ------------------------------------------------------ |\n| 免费（开发） | 无 token 上限 | **~40 RPM** | 70+ 模型；将于 2025 年中过渡到纯速率限制 |\n\n热门免费模型：`moonshotai\u002Fkimi-k2.5`（Kimi K2.5）、`z-ai\u002Fglm4.7`（GLM 4.7）、`deepseek-ai\u002Fdeepseek-v3.2`（DeepSeek V3.2）、`nvidia\u002Fllama-3.3-70b-instruct`、`deepseek\u002Fdeepseek-r1`\n\n### ⚪ CEREBRAS（免费 API 密钥 — inference.cerebras.ai）\n\n| 等级 | 日限额 | 速率限制 | 备注 |\n| ---- | ------------ | ------------ | ------------------------------------------- |\n| 免费 | **100万 tokens\u002F天** | 6万 TPM \u002F 30 RPM | 全球最快的 LLM 推理；每日重置 |\n\n免费可用：`llama-3.3-70b`、`llama-3.1-8b`、`deepseek-r1-distill-llama-70b`\n\n### 🔴 GROQ（免费 API 密钥 — console.groq.com）\n\n| 等级 | 日限额 | 速率限制 | 备注 |\n| ---- | -------- | ------------ | ----------------------------------------- |\n| 免费 | **1.44万 RPD** | 每模型 30 RPM | 无需信用卡；超出限额返回 429 错误，不收费 |\n\n免费可用：`llama-3.3-70b-versatile`、`gemma2-9b-it`、`mixtral-8x7b`、`whisper-large-v3`\n\n### 🔴 LONGCAT AI（免费 API 密钥 — longcat.chat）🆕\n\n| 模型 | 前缀 | 每日免费配额 | 备注 |\n| ----------------------------- | ------ | ------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc\u002F` | **5000万 tokens** 💥 | 史上最大免费配额 |\n| `LongCat-Flash-Chat` | `lc\u002F` | 50万 tokens | 多轮对话 |\n| `LongCat-Flash-Thinking` | `lc\u002F` | 50万 tokens | 推理 \u002F CoT |\n| `LongCat-Flash-Thinking-2601` | `lc\u002F` | 50万 tokens | 2026年1月版本 |\n| `LongCat-Flash-Omni-2603` | `lc\u002F` | 50万 tokens | 多模态 |\n\n> 在公开测试期间完全免费。请使用邮箱或电话在 [longcat.chat](https:\u002F\u002Flongcat.chat) 注册。每日 UTC 时间 00:00 重置。\n\n### 🟢 POLLINATIONS AI（无需 API 密钥）🆕\n\n| 模型 | 前缀 | 速率限制 | 背后提供者 |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol\u002F` | 1 请求\u002F15秒 | GPT-5 |\n| `claude` | `pol\u002F` | 1 请求\u002F15秒 | Anthropic Claude |\n| `gemini` | `pol\u002F` | 1 请求\u002F15秒 | Google Gemini |\n| `deepseek` | `pol\u002F` | 1 请求\u002F15秒 | DeepSeek V3 |\n| `llama` | `pol\u002F` | 1 请求\u002F15秒 | Meta Llama 4 Scout |\n| `mistral` | `pol\u002F` | 1 请求\u002F15秒 | Mistral AI |\n\n> ✨ **零摩擦：** 无需注册，无需 API 密钥。将 Pollinations 提供者添加到设置中，API 密钥字段留空即可立即使用。\n\n### 🟠 CLOUDFLARE WORKERS AI（免费 API 密钥 — cloudflare.com）🆕\n\n| 等级 | 每日神经元 | 等效用量 | 备注 |\n| ---- | -------- | --------------------------------------- | ----------------------- |\n| 免费 | **1万个** | ~150 次 LLM 回答 \u002F 500 秒音频 \u002F 1.5万 次嵌入 | 全球边缘节点，50+ 模型 |\n\n热门免费模型：`@cf\u002Fmeta\u002Fllama-3.3-70b-instruct`、`@cf\u002Fgoogle\u002Fgemma-3-12b-it`、`@cf\u002Fopenai\u002Fwhisper-large-v3-turbo`（免费音频！）、`@cf\u002Fqwen\u002Fqwen2.5-coder-15b-instruct`\n\n> 需要从 [dash.cloudflare.com](https:\u002F\u002Fdash.cloudflare.com) 获取 API Token 和 Account ID。将 Account ID 存储在提供商设置中。\n\n### 🟣 SCALEWAY AI（100万免费 tokens — scaleway.com）🆕\n\n| 等级 | 免费配额 | 地点 | 备注 |\n| ---- | ----------- | ---------- | ----------------------------------- |\n| 免费 | **100万 tokens** | 🇫🇷 巴黎，欧盟 | 在限额内无需信用卡 |\n\n免费可用：`qwen3-235b-a22b-instruct-2507`（Qwen3 235B！）、`llama-3.1-70b-instruct`、`mistral-small-3.2-24b-instruct-2506`、`deepseek-v3-0324`\n\n> 符合欧盟\u002FGDPR 标准。在 [console.scaleway.com](https:\u002F\u002Fconsole.scaleway.com) 获取 API 密钥。\n\n> **💡 终极免费堆栈（11 家提供商，永久免费）：**\n>\n> ```\n> Kiro (kr\u002F) → Claude Sonnet\u002FHaiku 无限\n> Qoder (if\u002F) → kimi-k2-thinking、qwen3-coder-plus、deepseek-r1 无限\n> LongCat Lite (lc\u002F) → LongCat-Flash-Lite — 每日 5000万 tokens 🔥\n> Pollinations (pol\u002F) → GPT-5、Claude、DeepSeek、Llama 4 — 无需密钥\n> Qwen (qw\u002F) → qwen3-coder 模型 无限\n> Gemini (gemini\u002F) → Gemini 2.5 Flash — 每日 1500 次请求免费\n> Cloudflare AI (cf\u002F) → 50+ 模型 — 每日 1万 Neurons\n> Scaleway (scw\u002F) → Qwen3 235B、Llama 70B — 100万免费 tokens（欧盟）\n> Groq (groq\u002F) → Llama\u002FGemma — 每日 1.44万次请求超快速\n> NVIDIA NIM (nvidia\u002F) → 70+ 开放模型 — 永久 40 RPM\n> Cerebras (cerebras\u002F) → Llama\u002FQwen 全球最快 — 每日 100万 tok\n> ```\n\n## 🎙️ 免费转录组合\n\n> 以 **$0** 转录任何音频\u002F视频 — Deepgram 提供 $200 免费额度，AssemblyAI 作为 $50 的备选方案，Groq Whisper 则是无限量的紧急备用。\n\n| 提供商 | 免费额度 | 最佳模型 | 速率限制 |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| 🟢 **Deepgram** | **$200 免费**（注册即得） | `nova-3` — 准确性最高，支持 30 多种语言 | 免费额度无 RPM 限制 |\n| 🔵 **AssemblyAI** | **$50 免费**（注册即得） | `universal-3-pro` — 支持章节划分、情感分析及 PII 识别 | 免费额度无 RPM 限制 |\n| 🔴 **Groq** | **永久免费** | `whisper-large-v3` — OpenAI Whisper | 30 RPM（有限制） |\n\n**推荐组合，在 `\u002Fdashboard\u002Fcombos` 中：**\n\n```\n名称: free-transcription\n策略: 优先级\n节点:\n [1] deepgram\u002Fnova-3 → 首先使用 $200 免费额度\n [2] assemblyai\u002Funiversal-3-pro → 当 Deepgram 额度用完时切换至该模型\n [3] groq\u002Fwhisper-large-v3 → 永久免费，作为紧急备用\n```\n\n然后在 `\u002Fdashboard\u002Fmedia` → **转录** 选项卡：上传任意音频或视频文件 → 选择你的组合端点 → 即可获得支持格式的转录结果。\n\n## 💡 核心功能\n\nOmniRoute v3.6 不仅仅是一个中继代理，更是一个运营平台。\n\n### 🆕 新功能 — v3.6.x 亮点（2026 年 4 月）\n\n| 功能 | 描述 |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 **V1 WebSocket 桥接** | OpenAI 兼容的 WebSocket 流量已升级并通过 `\u002Fv1\u002Fws` 进行代理转发 — 支持完整的流式传输，并带有会话认证（API 密钥或会话 Cookie） |\n| 🔑 **同步令牌与配置包** | 为配置同步端点颁发\u002F撤销同步令牌。配置包采用 ETag 版本控制，实现高效带宽的轮询 |\n| 🧠 **GLM Thinking (glmt) 预设** | GLM Thinking 已注册为一等公民：最大 65,536 个 token，思考预算 24,576 个，超时 900 秒，使用情况同步及定价 — 与 Claude 兼容的 API |\n| 🔢 **混合 token 计数** | 在可用时使用提供商端的 `\u002Fmessages\u002Fcount_tokens`；若不可用则回退到估算 — 精确跟踪用量，无需猜测 |\n| 🌱 **模型别名自动初始化** | 启动时规范化 30 多种跨代理方言别名 — 再也不会出现路由不匹配 |\n| 🛡️ **安全的出站请求** | 所有提供商验证和模型发现都通过受保护的请求层进行，阻止私有\u002F本地 URL，同时具备重试、超时和 SSRF 防护功能 |\n| 🔄 **冷却时间感知的重试** | 聊天请求在遇到模型范围内的冷却时间时会自动重试，可配置 `requestRetry` 和 `maxRetryIntervalSec` |\n| 🔍 **运行时环境验证** | 启动时使用 Zod 模式验证所有环境变量 — 清晰地提示缺失的密钥、无效的 URL 或错误的类型 |\n| 📋 **合规审计扩展** | 结构化审计日志，支持分页、请求上下文、认证事件、提供商 CRUD 事件以及 SSRF 阻止的验证日志 |\n| 🔐 **TPS 日志指标** | 日志详情模态显示每秒 token 数（TPS）— 快速查看每次请求的性能 |\n| 🗑️ **卸载 \u002F 完全卸载** | `npm run uninstall` 保留数据，`npm run uninstall:full` 删除所有内容 — 适用于所有安装方式的干净卸载 |\n| 🔧 **OAuth 环境修复** | OAuth 提供商的一键“修复环境”操作可恢复缺失的环境变量，并修复损坏的认证状态 |\n| 🔒 **优雅的 Electron 关闭** | Electron 的 `before-quit` 会优雅地关闭 Next.js，防止桌面关闭时 SQLite WAL 数据库锁 |\n| 👁️ **模型可见性切换** | 提供商页面上提供按模型切换可见性的按钮（👁 图标），并配有搜索过滤器和活跃计数徽章（`N\u002FM active`） |\n| 📧 **电子邮件隐私遮蔽** | OAuth 账户邮箱被遮蔽（`di*****@g****.com`），鼠标悬停时显示完整地址 |\n| 🔗 **上下文接力策略** | 组合策略可在会话持续期间通过结构化的交接摘要来保持会话连续性，即使账户在对话中途切换 |\n| 🛡️ **代理加固** | 令牌健康检查、API 密钥验证以及 undici 分发器均遵循代理配置 |\n| ⚠️ **Node.js 24 登录警告** | 登录页面主动检测不兼容的 Node.js 版本，并显示明确的警告横幅 |\n| 📎 **Gemini PDF 附件** | PDF 附件通过 `inline_data` 和通用 base64 检测正确路由至 Gemini |\n| 🔒 **CodeQL 安全加固** | 解决了 SSRF、不安全随机性、多项式 ReDoS 以及不完全的 URL 净化告警 |\n\n### 🆕 新功能 — 受 ClawRouter 启发的改进（2026 年 3 月）\n\n| 功能 | 描述 |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| ⚡ **Grok-4 快速家族** | xAI 模型价格为 $0.20\u002F$0.50\u002FM — 基准测试耗时 1143ms（比 Gemini 2.5 Flash 快 30%） |\n| 🧠 **GLM-5 通过 Z.AI** | 输出上下文 128K，$0.5\u002F1M — GLM 家族最新旗舰 |\n| 🔮 **MiniMax M2.5** | 推理 + 代理任务价格为 $0.30\u002F1M — 相较于 M2.1 有显著提升 |\n| 🎯 **每模型的 toolCalling 标志** | 注册表中每个模型都有 `toolCalling: true\u002Ffalse` 标志 — AutoCombo 会跳过不具备工具调用能力的模型 |\n| 🌍 **多语言意图检测** | AutoCombo 评分中加入 PT\u002FZH\u002FES\u002FAR 关键词 — 更好地为非英语内容选择模型 |\n| 📊 **基于基准测试的回退机制** | 实时请求中的 p95 延迟数据会反馈到组合评分中 — AutoCombo 从实际数据中学习 |\n| 🔁 **请求去重** | 基于内容哈希的去重窗口 — 多智能体场景下安全，避免重复计费 |\n| 🔌 **可插拔的 RouterStrategy** | 可扩展的 `RouterStrategy` 接口 — 可以添加自定义路由逻辑作为插件 |\n\n### 🚀 之前的 v2.0.9+ — Playground、CLI 指纹匹配与 ACP\n\n| 功能 | 作用 |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🎮 **模型 Playground** | 仪表板页面，可直接测试任意模型——提供提供商\u002F模型\u002F端点选择器、Monaco 编辑器、流式传输、取消请求、计时功能 |\n| 🔏 **CLI 指纹匹配** | 针对不同提供商的请求头\u002F请求体顺序进行匹配，以适配原生 CLI 签名——可在设置 > 安全中为每个提供商单独开启或关闭。**您的代理 IP 将被保留** |\n| 🤝 **ACP 支持（Agent Client Protocol）** | CLI 代理发现（Codex、Claude、Goose、Gemini CLI、OpenClaw 等 9 种），进程启动器，以及 `\u002Fapi\u002Facp\u002Fagents` 端点 |\n| 🤖 **ACP 代理仪表板** | 调试 › 代理页面——以网格形式展示 14 个代理，显示其安装状态、版本，并提供用于任何 CLI 工具的自定义代理表单。**OpenCode 用户**会看到一个“下载 opencode.json”按钮，可自动生成包含所有可用模型的即用配置文件。 |\n| 🔧 **自定义模型 `apiFormat` 路由** | 具有 `apiFormat: \"responses\"` 的自定义模型现在能够正确路由到 Responses API 转换器 |\n| 🏢 **Codex 工作空间隔离** | 每个邮箱可拥有多个 Codex 工作空间——OAuth 会根据工作空间 ID 正确分离连接 |\n| 🔄 **Electron 自动更新** | 桌面应用会检查更新，并在重启时自动安装 |\n\n### 🤖 代理与协议操作（v2.0）\n\n| 功能 | 作用 |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| 🔧 **MCP 服务器（25 种工具）** | 通过三种传输方式提供 IDE\u002F代理工具：stdio、SSE (`\u002Fapi\u002Fmcp\u002Fsse`)、可流式 HTTP (`\u002Fapi\u002Fmcp\u002Fstream`)。包括 18 种核心工具、3 种内存工具和 4 种技能工具 |\n| 🤝 **A2A 服务器（JSON-RPC + SSE）** | 代理间任务执行，支持同步与流式流程 |\n| 🧭 **整合端点页面** | 带有端点代理、MCP、A2A 和 API 端点选项卡的管理页面 |\n| 🎚️ **服务启用\u002F禁用切换** | MCP 和 A2A 的开关，具有设置持久化功能（默认为关闭） |\n| 🛰️ **MCP 运行时心跳** | 实时进程状态（PID、运行时间、心跳年龄、传输方式、作用域模式） |\n| 📋 **MCP 审计日志** | 可筛选的成功\u002F失败审计日志，并标注关键责任人 |\n| 🔐 **MCP 作用域强制** | 10 种细粒度的作用域权限，用于控制工具访问 |\n| 📡 **A2A 任务生命周期管理** | 列出\u002F筛选任务、查看事件\u002F成果、取消正在运行的任务 |\n| 📋 **代理卡片发现** | 通过 `\u002F.well-known\u002Fagent.json` 实现客户端自动发现 |\n| 🧪 **协议端到端测试框架** | 在 `test:protocols:e2e` 中运行真实的 MCP SDK 和 A2A 客户端流程 |\n| ⚙️ **运维控制** | 通过组合开关应用韧性配置文件，并从统一控制界面重置断路器 |\n\n### 🧠 路由与智能\n\n| 功能 | 作用 |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| 🎯 **智能四层回退** | 自动路由：订阅 → API 密钥 → 低价 → 免费 |\n| 📊 **实时配额跟踪** | 实时显示各提供商的令牌数量及重置倒计时 |\n| 🔄 **格式转换** | OpenAI ↔ Claude ↔ Gemini ↔ 支持符合 Schema 的响应转换 |\n| 👥 **多账号支持** | 每个提供商支持多个账号，并进行智能选择 |\n| 🔄 **自动刷新令牌** | OAuth 令牌自动刷新，并具备重试机制 |\n| 🎨 **自定义组合** | 13 种负载均衡策略 + 回退链控制 |\n| 🔗 **上下文传递** | 会话轮换账号时，保持会话连续性 |\n| 🌐 **通配符路由器** | `provider\u002F*` 动态路由 |\n| 🧠 **思维预算控制** | 直通、自动、自定义及自适应推理限制 |\n| 🔀 **模型别名** | 内置 + 自定义模型别名及迁移移安全 |\n| ⚡ **后台降级** | 将低优先级的后台任务路由至更便宜的模型 |\n| 🧪 **任务感知智能路由** | 根据内容类型（编码\u002F视觉\u002F分析\u002F摘要）自动选择模型 |\n| 🔄 **A2A 代理工作流** | 用于有状态多步代理执行的确定性有限状态机编排器 |\n| 🔀 ** adaptive 路由** | 基于令牌用量和提示复杂度动态调整路由策略 |\n| 🎲 **提供商多样性** | 基于香农熵评分平衡自动组合的流量分配 |\n| 💬 **系统提示注入** | 全局行为控制一致应用 |\n| 📄 **Responses API 兼容性** | 完全支持 `\u002Fv1\u002Fresponses`，适用于 Codex 和高级代理工作流 |\n\n### 🎵 多模态 API\n\n| 功能 | 作用 |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🖼️ **图像生成** | `\u002Fv1\u002Fimages\u002Fgenerations` 支持云端和本地后端 |\n| 📐 **嵌入** | `\u002Fv1\u002Fembeddings` 用于搜索和 RAG 流程 |\n| 🎤 **音频转录** | `\u002Fv1\u002Faudio\u002Ftranscriptions` — 7 家提供商（Deepgram Nova 3、AssemblyAI、Groq Whisper、HuggingFace、ElevenLabs、OpenAI、Azure），自动语言检测，支持 MP4\u002FMP3\u002FWAV 格式 |\n| 🔊 **文本转语音** | `\u002Fv1\u002Faudio\u002Fspeech` — 10 家提供商（ElevenLabs、OpenAI、Deepgram、Cartesia、PlayHT、HuggingFace、Nvidia NIM、Inworld、Coqui、Tortoise），并提供准确的错误信息 |\n| 🎬 **视频生成** | `\u002Fv1\u002Fvideos\u002Fgenerations`（ComfyUI + SD WebUI 工作流） |\n| 🎵 **音乐生成** | `\u002Fv1\u002Fmusic\u002Fgenerations`（ComfyUI 工作流） |\n| 🛡️ **内容审核** | `\u002Fv1\u002Fmoderations` 安全检查 |\n| 🔀 **重排序** | `\u002Fv1\u002Frerank` 用于相关性评分 |\n| 🔍 **网页搜索** 🆕 | `\u002Fv1\u002Fsearch` — 5 家提供商（Serper、Brave、Perplexity、Exa、Tavily），每月免费额度超过 6,500 次，自动故障转移，带缓存 |\n\n### 🛡️ 弹性、安全与治理\n\n| 功能 | 作用 |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| 🔌 **熔断器** | 每个模型独立触发与恢复，支持阈值控制 |\n| 🎯 **端点感知模型** | 自定义模型声明支持的端点及 API 格式 |\n| 🛡️ **防击垮保护** | 在重试\u002F速率限制场景中使用互斥锁和信号量保护 |\n| 🧠 **语义+签名缓存** | 通过两层缓存降低开销与延迟 |\n| ⚡ **请求幂等性** | 重复请求防护窗口 |\n| 🔒 **TLS 指纹欺骗** | 类似浏览器的 TLS 指纹 — **降低机器人检测与账号标记风险** |\n| 🔏 **CLI 指纹匹配** | 匹配原生 CLI 请求签名 — **在保留代理 IP 的同时降低封禁风险** |\n| 🌐 **IP 过滤** | 对公开部署进行白名单\u002F黑名单控制 |\n| 📊 **可编辑的速率限制** | 可配置的全局\u002F提供商级别限流，并支持持久化 |\n| 📉 **优雅降级** | 多层能力回退机制，保护核心网关操作 |\n| 📜 **配置审计追踪** | 基于差异的变更跟踪，防止运营漂移，并支持简单回滚 |\n| ⏳ **提供商健康同步** | 主动监控 Token 过期，在授权失败前触发告警 |\n| 🚪 **自动禁用被封账号** | 运营熔断机制，自动永久封禁被阻止的 Token 账号 |\n| 🔑 **API 密钥管理 + 范围控制** | 安全的密钥发放\u002F轮换，以及模型和提供商权限控制 |\n| 👁️ **范围受限的 API 密钥显示** 🆕 | 通过 `ALLOW_API_KEY_REVEAL` 选项选择性恢复 API 密钥 |\n| 🛡️ **受保护的 `\u002Fmodels`** | 模型目录可选认证与提供商隐藏功能 |\n| 🛡️ **安全的出站请求** 🆕 | 为提供商调用提供防护 — 阻止私有\u002F本地 URL、实现重试机制，并防范 SSRF |\n| 🔄 **冷却时间感知的重试** 🆕 | 在模型冷却时自动重试聊天；可配置 `requestRetry` 和 `maxRetryIntervalSec` |\n| 🔍 **运行时环境验证** 🆕 | 启动时基于 Zod 的环境 Schema 验证，提供可操作的错误信息 |\n| 📋 **合规审计 v2** 🆕 | 分页、请求上下文、认证事件、提供商 CRUD 操作，以及对 SSRF 的日志记录 |\n\n### 📊 可观测性与分析\n\n| 功能 | 作用 |\n| ------------------------------ | ----------------------------------------------------- |\n| 📝 **请求 + 代理日志记录** | 记录完整的请求\u002F响应及代理日志 |\n| 📉 **流式详细日志** 🆕 | 将 SSE 数据流干净地重构到 UI 中 |\n| 📋 **统一日志仪表盘** | 在一个页面中查看请求、代理、审计和控制台视图 |\n| 🔍 **请求遥测** | 提供 p50\u002Fp95\u002Fp99 延迟及请求追踪 |\n| 🏥 **健康仪表盘** | 显示 uptime、熔断状态、锁定情况及缓存统计 |\n| 💰 **成本跟踪** | 预算控制及按模型定价的可见性 |\n| 📈 **分析可视化** | 提供模型\u002F提供商使用洞察及趋势视图 |\n| 🧪 **评估框架** | 使用可配置的匹配策略进行黄金集测试 |\n| 📡 **实时诊断** 🆕 | 绕过语义缓存，实现准确的组合式实时测试 |\n| 🔐 **TPS 日志指标** 🆕 | 在日志详情模态框中显示每秒令牌数 |\n\n### ☁️ 部署与平台\n\n| 功能 | 作用 |\n| ------------------------------ | --------------------------------------------------------------------- |\n| 🌐 **随处部署** | 支持 localhost、VPS、Docker 及云环境 |\n| 🚇 **Cloudflare Tunnel** 🆕 | 从仪表盘一键集成 Quick Tunnel |\n| 🔑 **API 密钥模型过滤** | 原生 \u002Fv1\u002Fmodels 响应可根据分配的 Bearer 上下文角色进行过滤 |\n| ⚡ **智能缓存绕过** | 可配置的 TTL 策略及强制重新获取数据的控制 |\n| 🔄 **备份\u002F恢复** | 支持导出\u002F导入及灾难恢复流程 |\n| 🧙 **引导向导** | 首次运行时的引导式设置 |\n| 🔧 **CLI 工具仪表盘** | 为常用编程工具提供一键式设置 |\n| 🎮 **模型 Playground** | 可从仪表盘测试任意提供商\u002F模型\u002F端点 |\n| 🔏 **CLI 指纹切换** | 在设置 > 安全中按提供商启用指纹匹配 |\n| 🌐 **i18n（30 种语言）** | 全面支持仪表盘与文档的语言，并覆盖 RTL 排版 |\n| 🧹 **清除所有模型** | 在提供商详情中一键清空模型列表 |\n| 👁️ **侧边栏控件** 🆕 | 可在外观设置中隐藏组件与集成 |\n| 📋 **问题模板** | 提供标准化的 GitHub 模板，用于报告 Bug 和功能需求 |\n| 📂 **自定义数据目录** | 支持通过 `DATA_DIR` 覆盖存储位置 |\n| 🌐 **V1 WebSocket 桥接** 🆕 | 通过 `\u002Fv1\u002Fws` 代理兼容 OpenAI 的 WebSocket 流量 |\n| 🔑 **同步 Token 与 Bundle** 🆕 | 支持 ETag 的配置同步 Token 及版本化的 Bundle 端点 |\n\n### 功能深度解析\n\n#### 智能回退与实用的成本控制\n\n```txt\n组合: \"my-coding-stack\"\n 1. cc\u002Fclaude-opus-4-6\n 2. nvidia\u002Fllama-3.3-70b\n 3. glm\u002Fglm-4.7\n 4. if\u002Fkimi-k2-thinking\n```\n\n当配额、速率或健康状态出现问题时，OmniRoute 会自动切换到下一个候选模型，无需手动干预。\n\n#### 可视化且可操作的协议管理\n\n- MCP 和 A2A 在 UI 和文档中均可发现（不隐藏）\n- 协议状态 API 提供实时运行数据（`\u002Fapi\u002Fmcp\u002F*`, `\u002Fapi\u002Fa2a\u002F*`）\n- 仪表板包含日常运维操作（组合切换、熔断器重置、任务取消）\n\n#### 转换器 + 验证工作流\n\n转换器区域包括：\n\n- **游乐场**：请求转换检查\n- **聊天测试器**：完整的请求\u002F响应往返\n- **测试台**：一次运行多个用例\n- **实时监控**：实时流量视图\n\n此外，还可以通过 `npm run test:protocols:e2e` 使用真实客户端进行协议验证。\n\n> 📖 **[MCP 服务器 README](open-sse\u002Fmcp-server\u002FREADME.md)** — 工具参考、IDE 配置和客户端示例\n>\n> 📖 **[A2A 服务器 README](src\u002Flib\u002Fa2a\u002FREADME.md)** — 技能、JSON-RPC 方法、流式传输和任务生命周期\n\n## 🧪 评估 (Evals)\n\nOmniRoute 内置了一个评估框架，用于根据黄金数据集测试 LLM 的响应质量。可通过仪表板中的 **Analytics → Evals** 访问。\n\n### 内置黄金数据集\n\n预加载的“OmniRoute 黄金数据集”包含以下测试用例：\n\n- 问候语、数学、地理、代码生成\n- JSON 格式合规性、翻译、Markdown 生成\n- 安全拒绝（有害内容）、计数、布尔逻辑\n\n### 评估策略\n\n| 策略 | 描述 | 示例 |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | 输出必须完全匹配 | `\"4\"` |\n| `contains` | 输出必须包含子字符串（不区分大小写） | `\"Paris\"` |\n| `regex` | 输出必须匹配正则表达式 | `\"1.*2.*3\"` |\n| `custom` | 自定义 JS 函数返回 true\u002Ffalse | `(output) => output.length > 10` |\n\n---\n\n## 📖 设置指南\n\n### 协议设置（MCP + A2A）\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧩 MCP 设置（模型上下文协议）\u003C\u002Fb>\u003C\u002Fsummary>\n\n以 stdio 模式启动 MCP 传输：\n\n```bash\nomniroute --mcp\n```\n\n推荐的验证流程如下：\n\n1. 通过 stdio 连接你的 MCP 客户端。\n2. 运行 `omniroute_get_health`。\n3. 运行 `omniroute_list_combos`。\n4. 打开 `\u002Fdashboard\u002Fmcp` 确认心跳、活动和审计记录。\n\n用于自动化的有用 API：\n\n- `GET \u002Fapi\u002Fmcp\u002Fstatus`\n- `GET \u002Fapi\u002Fmcp\u002Ftools`\n- `GET \u002Fapi\u002Fmcp\u002Faudit`\n- `GET \u002Fapi\u002Fmcp\u002Faudit\u002Fstats`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🤝 A2A 设置（Agent2Agent）\u003C\u002Fb>\u003C\u002Fsummary>\n\n发现代理：\n\n```bash\ncurl http:\u002F\u002Flocalhost:20128\u002F.well-known\u002Fagent.json\n```\n\n发送任务：\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:20128\u002Fa2a \\\n -H 'content-type: application\u002Fjson' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message\u002Fsend\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"总结配额状态。\"}]}}'\n```\n\n管理生命周期：\n\n- `GET \u002Fapi\u002Fa2a\u002Fstatus`\n- `GET \u002Fapi\u002Fa2a\u002Ftasks`\n- `GET \u002Fapi\u002Fa2a\u002Ftasks\u002F:id`\n- `POST \u002Fapi\u002Fa2a\u002Ftasks\u002F:id\u002Fcancel`\n\n运维 UI：\n\n- `\u002Fdashboard\u002Fa2a` 用于任务\u002F状态\u002F流的可观ability 和快速操作\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 端到端协议验证\u003C\u002Fb>\u003C\u002Fsummary>\n\n使用真实客户端验证两个协议：\n\n```bash\nnpm run test:protocols:e2e\n```\n\n这将验证：\n\n- MCP SDK 客户端连接\u002F列表\u002F调用\n- A2A 发现\u002F发送\u002F流式传输\u002F获取\u002F取消\n- 在 MCP 审计和 A2A 任务管理 API 中交叉核对数据\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💳 订阅提供商\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Claude Code (Pro\u002FMax)\n\n```bash\n仪表板 → 供应商 → 连接 Claude Code\n→ OAuth 登录 → 自动刷新令牌\n→ 5 小时 + 每周配额跟踪\n\n模型：\n cc\u002Fclaude-opus-4-6\n cc\u002Fclaude-sonnet-4-5-20250929\n cc\u002Fclaude-haiku-4-5-20251001\n```\n\n**专业提示：** 复杂任务使用 Opus，追求速度则用 Sonnet。OmniRoute 会按模型分别跟踪配额！\n\n### OpenAI Codex (Plus\u002FPro)\n\n```bash\n仪表板 → 供应商 → 连接 Codex\n→ OAuth 登录（端口 1455）\n→ 5 小时 + 每周重置\n\n模型：\n cx\u002Fgpt-5.2-codex\n cx\u002Fgpt-5.1-codex-max\n```\n\n#### Codex 账户限额管理（5h + 每周）\n\n每个 Codex 账户现在在 `仪表板 -> 供应商` 中都有策略开关：\n\n- `5h`（开启\u002F关闭）：强制执行 5 小时窗口阈值政策。\n- `Weekly`（开启\u002F关闭）：强制执行每周窗口阈值政策。\n- 阈值行为：当启用的窗口使用率达到或超过 90% 时，该账户会被跳过。\n- 轮转行为：OmniRoute 会自动路由到下一个符合条件的 Codex 账户。\n-重置行为：当提供商的 `resetAt` 时间过去后，该账户会自动重新进入轮转（无需手动重新启用）。\n\n场景：\n\n- `5h ON` + `Weekly ON`：任一窗口达到阈值时，账户会被跳过。\n- `5h OFF` + `Weekly ON`：只有每周用量会阻止该账户。\n- `5h ON` + `Weekly OFF`：只有 5 小时用量会阻止该账户。\n- 当 `resetAt` 过去后，账户会自动重新进入轮转（无需手动重新启用）。\n\n### Gemini CLI (免费 18 万\u002F月！)\n\n```bash\n仪表板 → 供应商 → 连接 Gemini CLI\n→ Google OAuth\n→ 每月 18 万次补全 + 每日 1 千次\n\n模型：\n gc\u002Fgemini-3-flash-preview\n gc\u002Fgemini-2.5-pro\n```\n\n**超值选择：** 巨大的免费层级！请在付费层级之前优先使用。\n\n### GitHub Copilot\n\n```bash\n仪表板 → 供应商 → 连接 GitHub\n→ 通过 GitHub 进行 OAuth\n→ 每月重置（每月 1 日）\n\n模型：\n gh\u002Fgpt-5\n gh\u002Fclaude-4.5-sonnet\n gh\u002Fgemini-3.1-pro-preview\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔑 API 密钥提供商\u003C\u002Fb>\u003C\u002Fsummary>\n\n### NVIDIA NIM (免费开发者访问 — 70+ 模型)\n\n1. 注册：[build.nvidia.com](https:\u002F\u002Fbuild.nvidia.com)\n2. 获取免费 API 密钥（包含 1000 次推理积分）\n3. 仪表板 → 添加供应商 → NVIDIA NIM：\n - API 密钥：`nvapi-your-key`\n\n**模型：** `nvidia\u002Fllama-3.3-70b-instruct`、`nvidia\u002Fmistral-7b-instruct` 以及 50 多种其他模型\n\n**专业提示：** 兼容 OpenAI 的 API — 可无缝对接 OmniRoute 的格式转换！\n\n### DeepSeek\n\n1. 注册：[platform.deepseek.com](https:\u002F\u002Fplatform.deepseek.com)\n2. 获取 API 密钥\n3. 仪表板 → 添加供应商 → DeepSeek\n\n**模型：** `deepseek\u002Fdeepseek-chat`、`deepseek\u002Fdeepseek-coder`\n\n### Groq（提供免费层级！）\n\n1. 注册：[console.groq.com](https:\u002F\u002Fconsole.groq.com)\n2. 获取 API 密钥（包含免费层级）\n3. 仪表板 → 添加供应商 → Groq\n\n**模型：** `groq\u002Fllama-3.3-70b`、`groq\u002Fmixtral-8x7b`\n\n**专业提示：** 超高速推理 — 非常适合实时编码！\n\n### OpenRouter（100+ 模型）\n\n1. 注册：[openrouter.ai](https:\u002F\u002Fopenrouter.ai)\n2. 获取 API 密钥\n3. 仪表板 → 添加提供商 → OpenRouter\n\n**模型：** 通过一个 API 密钥即可访问来自所有主要提供商的 100 多种模型。\n\n**仪表板行为：** OpenRouter 模型从“可用模型”中管理。手动添加、导入和自动同步都会更新同一列表。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💰 廉价提供商（备用）\u003C\u002Fb>\u003C\u002Fsummary>\n\n### GLM-4.7（每日重置，$0.6\u002F1M）\n\n1. 注册：[Zhipu AI](https:\u002F\u002Fopen.bigmodel.cn\u002F)\n2. 从 Coding Plan 获取 API 密钥\n3. 仪表板 → 添加 API 密钥：\n - 提供商：`glm`\n - API 密钥：`your-key`\n\n**使用：** `glm\u002Fglm-4.7`\n\n**实用技巧：** Coding Plan 以七分之一的价格提供三倍配额！每日上午 10:00 重置。\n\n### MiniMax M2.1（5 小时重置，$0.20\u002F1M）\n\n1. 注册：[MiniMax](https:\u002F\u002Fwww.minimax.io\u002F)\n2. 获取 API 密钥\n3. 仪表板 → 添加 API 密钥\n\n**使用：** `minimax\u002FMiniMax-M2.1`\n\n**实用技巧：** 长上下文（1M tokens）中最便宜的选择！\n\n### Kimi K2（$9\u002F月固定）\n\n1. 订阅：[Moonshot AI](https:\u002F\u002Fplatform.moonshot.ai\u002F)\n2. 获取 API 密钥\n3. 仪表板 → 添加 API 密钥\n\n**使用：** `kimi\u002Fkimi-latest`\n\n**实用技巧：** 固定 $9\u002F月可使用 10M tokens，相当于 $0.90\u002F1M 的有效成本！\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🆓 免费提供商（应急备用）\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Qoder（通过 OAuth 提供 5 种免费模型）\n\n```bash\n仪表板 → 连接 Qoder\n→ Qoder OAuth 登录\n→ 无限使用\n\n模型：\n if\u002Fkimi-k2-thinking\n if\u002Fqwen3-coder-plus\n if\u002Fglm-4.7\n if\u002Fminimax-m2\n if\u002Fdeepseek-r1\n```\n\n### Qwen（通过设备码提供 4 种免费模型）\n\n```bash\n仪表板 → 连接 Qwen\n→ 设备码授权\n→ 无限使用\n\n模型：\n qw\u002Fqwen3-coder-plus\n qw\u002Fqwen3-coder-flash\n```\n\n### Kiro（Claude 免费版）\n\n```bash\n仪表板 → 连接 Kiro\n→ AWS Builder ID 或 Google\u002FGitHub\n→ 无限使用\n\n模型：\n kr\u002Fclaude-sonnet-4.5\n kr\u002Fclaude-haiku-4.5\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🎨 创建组合\u003C\u002Fb>\u003C\u002Fsummary>\n\n### 示例 1：最大化订阅 → 廉价备份\n\n```\n仪表板 → 组合 → 新建\n\n名称：premium-coding\n模型：\n 1. cc\u002Fclaude-opus-4-6（订阅主模型）\n 2. glm\u002Fglm-4.7（廉价备份，$0.6\u002F1M）\n 3. minimax\u002FMiniMax-M2.1（最便宜的后备，$0.20\u002F1M）\n\n在 CLI 中使用：premium-coding\n```\n\n### 示例 2：纯免费（零成本）\n\n```\n名称：free-combo\n模型：\n 1. gc\u002Fgemini-3-flash-preview（每月 18 万次免费调用）\n 2. if\u002Fkimi-k2-thinking（无限使用）\n 3. qw\u002Fqwen3-coder-plus（无限使用）\n\n成本：永远 $0！\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔧 CLI 集成\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Cursor IDE\n\n```\n设置 → 模型 → 高级：\n OpenAI API 基础 URL：http:\u002F\u002Flocalhost:20128\u002Fv1\n OpenAI API 密钥：[来自 OmniRoute 仪表板]\n 模型：cc\u002Fclaude-opus-4-6\n```\n\n### Claude Code\n\n使用仪表板中的“CLI 工具”页面进行一键配置，或手动编辑 `~\u002F.claude\u002Fsettings.json`。\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http:\u002F\u002Flocalhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**选项 1 — 仪表板（推荐）：**\n\n```\n仪表板 → CLI 工具 → OpenClaw → 选择模型 → 应用\n```\n\n**选项 2 — 手动：** 编辑 `~\u002F.openclaw\u002Fopenclaw.json`：\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http:\u002F\u002F127.0.0.1:20128\u002Fv1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **注意：** OpenClaw 只能在本地 OmniRoute 上运行。为避免 IPv6 解析问题，请使用 `127.0.0.1` 而不是 `localhost`。\n\n### Cline \u002F Continue \u002F RooCode\n\n```\n设置 → API 配置：\n 提供商：OpenAI 兼容\n 基础 URL：http:\u002F\u002Flocalhost:20128\u002Fv1\n API 密钥：[来自 OmniRoute 仪表板]\n 模型：if\u002Fkimi-k2-thinking\n```\n\n### OpenCode\n\n**步骤 1：** 将 OmniRoute 添加为自定义提供商：\n\n```bash\nopencode\n\u002Fconnect\n# 选择“其他”→ 输入 ID：“omniroute”→ 输入你的 OmniRoute API 密钥\n```\n\n**步骤 2：** 在项目根目录创建或编辑 `opencode.json`：\n\n```json\n{\n \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk\u002Fopenai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http:\u002F\u002Flocalhost:20128\u002Fv1\"\n },\n \"models\": {\n \"cc\u002Fclaude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg\u002Fgemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if\u002Fkimi-k2-thinking\": { \"name\": \"Kimi K2（免费）\" }\n }\n }\n }\n}\n```\n\n**步骤 3：** 在 OpenCode 中选择模型：\n\n```bash\n\u002Fmodels\n# 从列表中选择任意 OmniRoute 模型\n```\n\n> **提示：** 将你 OmniRoute `\u002Fv1\u002Fmodels` 端点中提供的任何模型添加到“models”部分。使用来自 OmniRoute 仪表板的格式“provider\u002Fmodel-id”。\n\n\u003C\u002Fdetails>\n\n---\n\n## 🐛 故障排除\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>点击展开故障排除指南\u003C\u002Fb>\u003C\u002Fsummary>\n\n**“语言模型未提供消息”**\n\n- 提供商配额已耗尽 → 检查仪表板上的配额跟踪器\n- 解决方案：使用组合后备或切换到更便宜的层级\n\n**速率限制**\n\n- 订阅配额用尽 → 切换到 GLM\u002FMiniMax\n- 添加组合：`cc\u002Fclaude-opus-4-6 → glm\u002Fglm-4.7 → if\u002Fkimi-k2-thinking`\n\n**OAuth 令牌过期**\n\n- OmniRoute 会自动刷新\n- 如果问题仍然存在：仪表板 → 提供商 → 重新连接\n\n**费用过高**\n\n- 检查仪表板 → 成本中的使用统计\n- 将主模型切换到 GLM\u002FMiniMax\n- 对于非关键任务，使用免费层级（Gemini CLI、Qoder）\n\n**仪表板\u002FAPI 端口错误**\n\n- `PORT` 是标准基础端口（默认也是 API 端口）\n- `API_PORT` 仅覆盖 OpenAI 兼容 API 监听器\n- `DASHBOARD_PORT` 仅覆盖仪表板\u002FNext.js 监听器\n- 将 `NEXT_PUBLIC_BASE_URL` 设置为你的仪表板\u002F公共 URL（用于 OAuth 回调）\n\n**云同步错误**\n\n- 确认 `BASE_URL` 指向你正在运行的实例\n- 确认 `CLOUD_URL` 指向你期望的云端点\n- 保持 `NEXT_PUBLIC_*` 值与服务器端值一致\n\n**首次登录不成功**\n\n- 检查 `.env` 中的 `INITIAL_PASSWORD`\n- 如果未设置，回退密码为 `123456`\n\n**没有请求日志**\n\n- SQLite 中的 `call_logs` 存储了请求日志表和分析视图的摘要元数据\n- 详细的请求\u002F响应负载会以每个请求一个 JSON 文件的形式写入 `DATA_DIR\u002Fcall_logs\u002F`\n- 如果需要详细的各阶段负载，可在仪表板 → 日志 → 请求日志 中启用管道捕获\n- `导出日志` 会按需读取这些文件，而 `导出全部` 会将 `call_logs\u002F` 目录与 `storage.sqlite` 一起导出\n- 如果还希望将应用控制台日志记录到 `logs\u002Fapplication\u002Fapp.log`，请设置 `APP_LOG_TO_FILE=true`\n- 根据需要调整 `APP_LOG_MAX_FILE_SIZE`、`APP_LOG_RETENTION_DAYS`、`APP_LOG_MAX_FILES` 和 `CALL_LOG_MAX_ENTRIES`\n\n**连接测试显示 OpenAI 兼容提供商为“无效”**\n\n- 许多提供商并未公开 `\u002Fmodels` 端点\n- OmniRoute v1.0.6+ 包含通过聊天完成的回退验证\n- 确保基础 URL 包含 `\u002Fv1` 后缀\n\n### 🔐 远程服务器上的 OAuth\n\n\u003Ca name=\"oauth-on-a-remote-server\">\u003C\u002Fa>\n\u003Ca name=\"oauth-em-servidor-remoto\">\u003C\u002Fa>\n\n> **⚠️ 对在 VPS、Docker 或任何远程服务器上运行 OmniRoute 的用户非常重要**\n\n#### 为什么 Antigravity \u002F Gemini CLI 的 OAuth 在远程服务器上会失败？\n\n**Antigravity** 和 **Gemini CLI** 提供商使用 **Google OAuth 2.0**。Google 要求 OAuth 流程中的 `redirect_uri` 必须与应用在 Google Cloud 控制台中预先注册的 URI 完全匹配。\n\nOmniRoute 中捆绑的 OAuth 凭证仅针对 `localhost` 注册。当您在远程服务器上访问 OmniRoute 时（例如 `https:\u002F\u002Fomniroute.myserver.com`），Google 会以以下错误拒绝认证：\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### 解决方案：配置您自己的 OAuth 凭证\n\n您需要在 Google Cloud 控制台中创建一个适用于您服务器 URI 的 **OAuth 2.0 客户端 ID**。\n\n#### 操作步骤\n\n**1. 打开 Google Cloud 控制台**\n\n访问：[https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials](https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials)\n\n**2. 创建新的 OAuth 2.0 客户端 ID**\n\n- 点击 **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- 应用程序类型：**\"Web application\"**\n- 名称：任意名称（例如 `OmniRoute Remote`）\n\n**3. 添加已授权的重定向 URI**\n\n在 **\"Authorized redirect URIs\"** 字段中，添加：\n\n```\nhttps:\u002F\u002Fyour-server.com\u002Fcallback\n```\n\n> 将 `your-server.com` 替换为您的服务器域名或 IP 地址（如有必要，请包含端口，例如 `http:\u002F\u002F45.33.32.156:20128\u002Fcallback`）。\n\n**4. 保存并复制凭证**\n\n创建完成后，Google 会显示 **客户端 ID** 和 **客户端密钥**。\n\n**5. 设置环境变量**\n\n在您的 `.env` 文件（或 Docker 环境变量）中：\n\n```bash\n# 对于 Antigravity：\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# 对于 Gemini CLI：\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. 重启 OmniRoute**\n\n```bash\n# 使用 npm：\nnpm run dev\n\n# 使用 Docker：\ndocker restart omniroute\n```\n\n**7. 再次尝试连接**\n\n仪表盘 → 提供商 → Antigravity（或 Gemini CLI）→ OAuth\n\n现在 Google 将正确重定向到 `https:\u002F\u002Fyour-server.com\u002Fcallback`。\n\n---\n\n#### 临时解决方案（无需自定义凭证）\n\n如果您目前不想设置自己的凭证，仍然可以使用 **手动 URL 流程**：\n\n1. OmniRoute 会打开 Google 授权 URL。\n2. 授权完成后，Google 会尝试重定向到 `localhost`（这在远程服务器上会失败）。\n3. **从浏览器地址栏复制完整 URL**（即使页面未加载）。\n4. 将该 URL 粘贴到 OmniRoute 连接模态框中显示的字段。\n5. 点击 **\"Connect\"**。\n\n> 这种方法可行，因为 URL 中的授权码是有效的，无论重定向页面是否成功加载。\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🇧🇷 葡萄牙语版本\u003C\u002Fb>\u003C\u002Fsummary>\n\n#### 为什么 Antigravity \u002F Gemini CLI 的 OAuth 在远程服务器上会失败？\n\n提供商 **Antigravity** 和 **Gemini CLI** 使用 **Google OAuth 2.0** 进行身份验证。Google 要求 OAuth 流程中使用的 `redirect_uri` 必须 **完全匹配** 应用程序在 Google Cloud 控制台中预先注册的 URI 之一。\n\nOmniRoute 中内置的 OAuth 凭证仅针对 `localhost` 注册。当您在远程服务器上访问 OmniRoute 时（例如 `https:\u002F\u002Fomniroute.meuservidor.com`），Google 会以以下错误拒绝身份验证：\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### 解决方案：配置您自己的 OAuth 凭证\n\n您需要在 Google Cloud 控制台中创建一个适用于您服务器 URI 的 **OAuth 2.0 客户端 ID**。\n\n#### 操作步骤\n\n**1. 访问 Google Cloud 控制台**\n\n打开：[https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials](https:\u002F\u002Fconsole.cloud.google.com\u002Fapis\u002Fcredentials)\n\n**2. 创建新的 OAuth 2.0 客户端 ID**\n\n- 点击 **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n- 应用程序类型：**\"Web application\"**\n- 名称：您可以选择任意名称（例如 `OmniRoute Remote`）\n\n**3. 添加已授权的重定向 URI**\n\n在 **\"Authorized redirect URIs\"** 字段中，添加：\n\n```\nhttps:\u002F\u002Fseu-servidor.com\u002Fcallback\n```\n\n> 将 `seu-servidor.com` 替换为您服务器的域名或 IP 地址（如有必要，请包含端口，例如 `http:\u002F\u002F45.33.32.156:20128\u002Fcallback`）。\n\n**4. 保存并复制凭证**\n\n创建完成后，Google 会显示 **客户端 ID** 和 **客户端密钥**。\n\n**5. 配置环境变量**\n\n在您的 `.env` 文件（或 Docker 环境变量）中：\n\n```bash\n# 对于 Antigravity：\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# 对于 Gemini CLI：\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. 重启 OmniRoute**\n\n```bash\n# 如果使用 npm：\nnpm run dev\n\n# 如果使用 Docker：\ndocker restart omniroute\n```\n\n**7. 再次尝试连接**\n\n仪表盘 → 提供商 → Antigravity（或 Gemini CLI）→ OAuth\n\n现在 Google 将正确重定向到 `https:\u002F\u002Fseu-servidor.com\u002Fcallback`，身份验证将成功。\n\n---\n\n#### 临时解决方法（无需配置自定义凭证）\n\n如果您暂时不想创建自己的凭证，仍然可以使用 **手动 URL 流程**：\n\n1. OmniRoute 会打开 Google 的授权 URL。\n2. 授权完成后，Google 会尝试重定向到 `localhost`（这在远程服务器上会失败）。\n3. **从浏览器地址栏复制完整的 URL**（即使页面没有加载）。\n4. 将该 URL 粘贴到 OmniRoute 连接模态框中显示的字段。\n5. 点击 **\"Connect\"**。\n\n> 此方法之所以有效，是因为 URL 中的授权码是有效的，无论重定向页面是否成功加载。\n\n\u003C\u002Fdetails>\n\n---\n\n\u003C\u002Fdetails>\n\n## 🛠️ 技术栈\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>点击展开技术栈详情\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **运行时**: Node.js 18–22 LTS (⚠️ Node.js 24+ **不支持** — `better-sqlite3` 的原生二进制文件不兼容)\n- **语言**: TypeScript 5.9 — `src\u002F` 和 `open-sse\u002F` 全部采用 **100% TypeScript**（自 v2.0 起，核心模块中无 `any` 类型）\n- **框架**: Next.js 16 + React 19 + Tailwind CSS 4\n- **数据库**: better-sqlite3 (SQLite) + LowDB (JSON 旧版) — 用于存储领域状态、代理日志、MCP 审计记录、路由决策、内存及技能数据\n- **Schema 验证**: Zod（用于 MCP 工具的输入输出验证及 API 协议定义）\n- **协议**: MCP（通过标准输入输出\u002FHTTP）+ A2A v0.3（基于 JSON-RPC 2.0 和 SSE）\n- **流式传输**: 服务器发送事件 (SSE)\n- **认证**: OAuth 2.0 (PKCE) + JWT + API 密钥 + MCP 作用域授权\n- **测试**: Node.js 测试运行器 + Vitest（包含单元测试、集成测试和端到端测试在内的 900 多个测试用例）\n- **CI\u002FCD**: GitHub Actions（发布时自动进行 npm 发布及 Docker Hub 更新）\n- **网站**: [omniroute.online](https:\u002F\u002Fomniroute.online)\n- **NPM 包**: [npmjs.com\u002Fpackage\u002Fomniroute](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fomniroute)\n- **Docker 镜像**: [hub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fdiegosouzapw\u002Fomniroute)\n- **系统韧性**: 熔断器、指数退避、防雪崩机制、TLS 欺骗防护、自动组合自我修复功能\n\n\u003C\u002Fdetails>\n\n---\n\n## 📖 文档\n\n| 文档 | 描述 |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [用户指南](docs\u002FUSER_GUIDE.md) | 提供者、组合、CLI 集成、部署 |\n| [API 参考文档](docs\u002FAPI_REFERENCE.md) | 所有接口及其示例 |\n| [MCP 服务器](open-sse\u002Fmcp-server\u002FREADME.md) | 25 个 MCP 工具、IDE 配置、Python\u002FTS\u002FGo 客户端 |\n| [A2A 服务器](src\u002Flib\u002Fa2a\u002FREADME.md) | JSON-RPC 2.0 协议、技能、流式传输、任务管理 |\n| [自动组合引擎](docs\u002Fauto-combo.md) | 6 因素评分、模式包、自我修复 |\n| [上下文传递](docs\u002Ffeatures\u002Fcontext-relay.md) | 会话交接策略，用于账号轮换 |\n| [故障排除](docs\u002FTROUBLESHOOTING.md) | 常见问题及解决方案 |\n| [架构设计](docs\u002FARCHITECTURE.md) | 系统架构及内部实现 |\n| [代码库文档](docs\u002FCODEBASE_DOCUMENTATION.md) | 针对初学者的代码库导览 |\n| [卸载指南](docs\u002FUNINSTALL.md) | 适用于所有安装方式的干净卸载方法 |\n| [环境配置](docs\u002FENVIRONMENT.md) | 完整的 `.env` 变量说明及参考 |\n| [贡献指南](CONTRIBUTING.md) | 开发环境搭建及贡献规范 |\n| [OpenAPI 规范](docs\u002Fopenapi.yaml) | OpenAPI 3.0 规范 |\n| [安全策略](SECURITY.md) | 漏洞报告与安全实践 |\n| [虚拟机部署](docs\u002FVM_DEPLOYMENT_GUIDE.md) | 完整指南：虚拟机 + nginx + Cloudflare 设置 |\n| [功能展示](docs\u002FFEATURES.md) | 带截图的可视化仪表盘导览 |\n| [发布检查清单](docs\u002FRELEASE_CHECKLIST.md) | 发布前验证步骤 |\n\n---\n\n## 🗺️ 路线图\n\nOmniRoute 在多个开发阶段中共规划了 **218+ 项功能**。以下是主要方向：\n\n| 类别 | 计划功能 | 亮点 |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| 🧠 **路由与智能** | 25+ | 最低延迟路由、基于标签的路由、配额预检、感知配额的 P2C、基于步骤的组合路由 |\n| 🔒 **安全与合规** | 20+ | SSRF 加固、凭据隐藏、按接口限流、管理密钥作用域划分 |\n| 📊 **可观测性** | 15+ | OpenTelemetry 集成、实时配额监控、组合目标健康状况、按模型成本跟踪 |\n| 🔄 **提供商集成** | 20+ | 动态模型注册中心、提供商冷却机制、多账号 Codex、Copilot 配额解析 |\n| ⚡ **性能** | 15+ | 双层缓存、提示词缓存、响应缓存、流式连接保持、批量 API |\n| 🌐 **生态体系** | 10+ | WebSocket API、配置热加载、分布式配置存储、商业模式 |\n\n### 🔜 即将推出\n\n- 🔗 **OpenCode 集成** — 原生支持 OpenCode AI 编程 IDE 的提供商\n- 🔗 **TRAE 集成** — 完全支持 TRAE AI 开发框架\n- 📦 **批量 API** — 异步批量处理请求\n- 🎯 **基于标签的路由** — 根据自定义标签和元数据路由请求\n- 💰 **最低成本策略** — 自动选择最便宜的可用提供商\n\n> 📝 完整的功能规格可在 [`docs\u002Fnew-features\u002F`](docs\u002Fnew-features\u002F) 中找到（共 217 条详细规格）\n\n---\n\n## 👥 贡献者\n\n[![贡献者](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_readme_76e4b6504592.png)](https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fgraphs\u002Fcontributors)\n\n### 如何贡献\n\n1. 分支仓库\n2. 创建功能分支 (`git checkout -b feature\u002Famazing-feature`)\n3. 提交更改 (`git commit -m '添加超赞功能'`)\n4. 推送到分支 (`git push origin feature\u002Famazing-feature`)\n5. 打开拉取请求\n\n详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n### 发布新版本\n\n```bash\n# 创建发布 — npm 发布会自动完成\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## 📊 星标历史\n\n## 不同时期的星标数量\n\n## [![不同时期的星标数量](https:\u002F\u002Fstarchart.cc\u002Fdiegosouzapw\u002FOmniRoute.svg?variant=adaptive)](https:\u002F\u002Fstarchart.cc\u002Fdiegosouzapw\u002FOmniRoute)\n\n## 🙏 致谢\n\n特别感谢 **[9router](https:\u002F\u002Fgithub.com\u002Fdecolua\u002F9router)**，由 **[decolua](https:\u002F\u002Fgithub.com\u002Fdecolua)** 开发——这是启发本项目分叉的原始项目。OmniRoute 在这一卓越基础上进一步扩展了功能，增加了多模态 API，并完全使用 TypeScript 重写。\n\n同时，也特别感谢 **[CLIProxyAPI](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI)**——最初的 Go 实现，为本次 JavaScript 移植提供了灵感。\n\n---\n\n## 📄 许可证\n\nMIT 许可证 - 详情请参阅 [LICENSE](LICENSE)。\n\n---\n\n\u003Cdiv align=\"center\">\n \u003Csub>专为全天候编码的开发者打造\u003C\u002Fsub>\n \u003Cbr\u002F>\n \u003Csub>\u003Ca href=\"https:\u002F\u002Fomniroute.online\">omniroute.online\u003C\u002Fa>\u003C\u002Fsub>\n\u003C\u002Fdiv>\n\u003C!-- 已启用 GitHub Discussions，用于社区问答 -->","# OmniRoute 快速上手指南\n\nOmniRoute 是一个免费的 AI 网关，支持智能路由到 100+ 个免费或低成本的 AI 模型，具备自动故障转移功能。它提供统一的 API 端点，兼容 Chat Completions、Embeddings、图像生成等多种能力，并支持 MCP Server 和 A2A 协议。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n* **操作系统**: Linux, macOS, 或 Windows\n* **运行时环境**: \n * **Node.js**: 版本 18.0 或更高（推荐最新 LTS 版本）\n * **npm**: 随 Node.js 自带\n * **或者 Docker**: 已安装 Docker Engine 和 Docker Compose\n* **前置依赖**: 无需额外数据库，OmniRoute 内置数据存储。\n\n> 💡 **国内开发者提示**: 如果访问 npm 源速度较慢，建议临时切换至国内镜像源（如淘宝镜像）：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n## 安装步骤\n\n您可以选择通过 **npm** 或 **Docker** 进行安装。\n\n### 方式一：使用 npm 安装（推荐用于本地开发）\n\n1. 全局安装 OmniRoute：\n ```bash\n npm install -g omniroute\n ```\n\n2. 验证安装：\n ```bash\n omniroute --version\n ```\n\n### 方式二：使用 Docker 安装（推荐用于生产环境）\n\n1. 拉取最新镜像：\n ```bash\n docker pull diegosouzapw\u002Fomniroute:latest\n ```\n\n2. 启动容器（映射端口 20128 并持久化数据）：\n ```bash\n docker run -d \\\n --name omniroute \\\n -p 20128:20128 \\\n -v omniroute_data:\u002Fapp\u002Fdata \\\n diegosouzapw\u002Fomniroute:latest\n ```\n\n## 基本使用\n\n安装完成后，OmniRoute 将作为一个本地代理服务器运行，默认监听端口 `20128`。\n\n### 1. 启动服务\n\n* **npm 用户**:\n ```bash\n omniroute start\n ```\n 或者直接运行（取决于版本）：\n ```bash\n omniroute\n ```\n\n* **Docker 用户**:\n 如果在上述步骤中已运行 `docker run`，服务应已启动。检查状态：\n ```bash\n docker ps | grep omniroute\n ```\n\n### 2. 配置 AI 提供商\n\nOmniRoute 提供了一个可视化的管理面板。\n\n* 打开浏览器访问：`http:\u002F\u002Flocalhost:20128`\n* 在 **Providers** 页面添加您的 AI API Key（支持 OpenAI, Anthropic, Google Gemini 等 100+ 提供商）。\n* 在 **Combos** 页面配置路由策略（例如：设置主备模型，当免费额度用尽时自动切换到付费接口）。\n\n### 3. 连接您的 AI 工具\n\n将您的 coding agent（如 Claude Code, Cursor, Cline, OpenClaw 等）的 API Base URL 指向 OmniRoute 的本地端点。\n\n* **API Base URL**: `http:\u002F\u002Flocalhost:20128\u002Fv1`\n* **API Key**: 任意字符串（因为鉴权在网关层处理，或者使用您在面板设置的统一 Key）\n\n**示例：在命令行工具中使用**\n\n假设您正在使用一个兼容 OpenAI 格式的 CLI 工具，只需修改其配置：\n\n```bash\n# 设置环境变量指向 OmniRoute\nexport OPENAI_BASE_URL=\"http:\u002F\u002Flocalhost:20128\u002Fv1\"\nexport OPENAI_API_KEY=\"your-omniroute-key\"\n\n# 运行您的 AI 工具\nnpx some-ai-coding-tool\n```\n\n**示例：curl 测试连通性**\n\n```bash\ncurl http:\u002F\u002Flocalhost:20128\u002Fv1\u002Fchat\u002Fcompletions \\\n -H \"Content-Type: application\u002Fjson\" \\\n -H \"Authorization: Bearer any-key\" \\\n -d '{\n \"model\": \"gpt-4o\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello OmniRoute!\"}]\n }'\n```\n\n现在，您的所有请求都将通过 OmniRoute 进行智能路由，自动利用免费额度或在不同提供商间无缝切换。","一家初创公司的后端团队正在开发一款面向全球用户的智能客服系统，需要同时调用多家大模型服务商以平衡成本与响应速度。\n\n### 没有 OmniRoute 时\n- **代码耦合严重**：开发人员必须在业务代码中硬编码不同供应商（如 OpenAI、Anthropic、本地模型）的 API 地址和鉴权逻辑，导致切换模型时需大规模重构代码。\n- **服务稳定性差**：当某家免费或低成本模型提供商出现超时或宕机时，整个客服系统会直接报错中断，缺乏自动重试或故障转移机制。\n- **成本不可控**：无法统一设置速率限制或缓存策略，容易因突发流量导致高价模型调用激增，造成预算超支。\n- **监控盲区**：缺乏统一的观测面板，难以实时追踪各模型的延迟、成功率及具体消耗，排查问题如同“盲人摸象”。\n\n### 使用 OmniRoute 后\n- **架构解耦灵活**：团队只需对接唯一的 OpenAI 兼容端点，通过配置文件即可动态调整路由策略，无缝切换至免费或低成本的备用模型，无需修改一行业务代码。\n- **高可用保障**：OmniRoute 内置的智能故障转移机制在主模型失败时自动降级到备用节点，并执行自动重试，确保客服对话 7x24 小时不中断。\n- **精细化成本控制**：利用内置的策略引擎设置全局速率限制和响应缓存，优先路由请求至低价模型，显著降低单次推理成本。\n- **全链路可观测**：通过统一的仪表盘实时监控所有供应商的性能指标与用量分布，快速定位瓶颈并优化资源分配。\n\nOmniRoute 将复杂的多模型调度转化为简单的单一接口调用，让团队在大幅降低运营成本的同时，获得了企业级的系统稳定性。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdiegosouzapw_OmniRoute_d127ef98.png","diegosouzapw","Diego Rodrigues de Sa e Souza","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fdiegosouzapw_ce61ba51.jpg",null,"CDWA Solutions","São Paulo - Brasil","www.cdwasolutions.com.br","https:\u002F\u002Fgithub.com\u002Fdiegosouzapw",[83,87,91,95,99,103],{"name":84,"color":85,"percentage":86},"TypeScript","#3178c6",96.7,{"name":88,"color":89,"percentage":90},"JavaScript","#f1e05a",2.7,{"name":92,"color":93,"percentage":94},"Python","#3572A5",0.3,{"name":96,"color":97,"percentage":98},"Shell","#89e051",0.2,{"name":100,"color":101,"percentage":102},"CSS","#663399",0.1,{"name":104,"color":105,"percentage":106},"Dockerfile","#384d54",0,3070,470,"2026-04-18T04:33:07","MIT","Linux, macOS, Windows","未说明",{"notes":114,"python":112,"dependencies":115},"该工具是一个基于 TypeScript 的 AI 网关代理，主要作为 API 路由服务运行，而非本地运行大型模型，因此对 GPU 和大内存无特殊需求。支持通过 npm、Docker 或 Electron 桌面应用安装。运行时需要配置各 AI 提供商的 API Key。默认端口为 20128。",[116,117,118,119],"Node.js (版本未说明)","npm","Docker (可选)","PM2 (可选)",[35,15,121,122,14,45],"音频","视频","2026-03-27T02:49:30.150509","2026-04-18T17:03:34.298474",[126,131,136,141,146,150],{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},40423,"为什么在 OmniRoute 仪表盘中验证 Qoder PAT 时总是显示\"API key validation failed\"（API 密钥验证失败）？","此问题通常由以下原因导致：\n1. **CLI 未正确识别**：确保已全局安装 qodercli (`npm install -g @qoder-ai\u002Fqodercli`)，并且 OmniRoute 能找到该二进制文件。在 Windows 上可能需要配置 `CLI_EXTRA_PATHS` 环境变量指向 node_modules 的 bin 目录。\n2. **版本问题**：该问题在 v3.5.6 中进行了综合修复（改进了错误消息和 PATH 搜索逻辑）。如果您使用的是旧版本或 Docker 镜像，请升级到最新版本（建议 v3.6.7+）。\n3. **PAT 格式与来源**：确保 PAT 是从 `https:\u002F\u002Fqoder.com\u002Faccount\u002Fintegrations` 生成的，格式通常以 `pt-` 开头。\n4. **Docker 环境**：如果在 Docker 中运行，需确保容器内也安装了 qodercli，并正确导入了 `QODER_PERSONAL_ACCESS_TOKEN` 和 `QODER_CLI_WORKSPACE` 环境变量。\n如果问题依旧，请检查后端日志中 `\u002Fapi\u002Fproviders\u002Fvalidate` 的具体返回错误，有时是 Qoder API 返回了 500 错误而非本地验证问题。","https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues\u002F966",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},40424,"连接 Gemini CLI 时遇到 \"[403] Cloud Code Private API has not been used in project\" 错误怎么办？","这是一个 Google Cloud Platform (GCP) 的限制，并非 OmniRoute 的 Bug。您需要手动在 GCP 项目中启用相关 API。解决步骤如下：\n1. 登录 [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com)。\n2. 选择您正在使用的活动项目。\n3. 在搜索栏中搜索 **\"Cloud Code API\"** (cloudcode-pa)。\n4. 点击 **\"Enable\" (启用)** 按钮。\n5. 等待几分钟让更改生效，然后重试在 OmniRoute 中连接提供者。\n注意：如果刚刚启用，可能需要短暂等待才能传播到系统。","https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues\u002F972",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},40425,"更新 OmniRoute 后，OpenClaw 集成无法发送消息到 Telegram（静默失败），如何解决？","这是一个在旧版本中引入的回归问题，表现为日志无报错但消息不发送。解决方案是升级 OmniRoute 到 **v3.1.4** 或更高版本（如 v3.1.5）。\n多个用户确认升级到 v3.1.4+ 后问题已解决，且相比更旧的 v2.9.4 版本，新版本还能降低 Token 使用量。如果您当前处于故障版本，请勿回退到 v2.9.4，而是直接升级到最新的稳定版。","https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues\u002F617",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},40426,"OmniRoute 提示 \"Error: Claude code not installed\"，即使我已经通过 npm 安装了该怎么办？","此问题是由于 OmniRoute 在特定环境下无法正确检测到已安装的 Claude Code 二进制文件导致的。该问题已通过 **PR #753** 修复。\n请确保您将 OmniRoute 升级到包含此修复的版本（即 PR #753 合并后的下一个发布版本，通常为 v3.3.2 或更高，具体视发布周期而定）。如果升级后仍然报错，请检查您的系统 PATH 环境变量是否包含了 npm 的全局安装路径，或者尝试重启 OmniRoute 服务以重新加载环境变量。","https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fissues\u002F604",{"id":147,"question_zh":148,"answer_zh":149,"source_url":130},40427,"在 Docker 环境中部署 OmniRoute 时，如何正确配置 Qoder 的个人访问令牌 (PAT)？","在 Docker\u002FDocker Compose 环境中配置 Qoder PAT 需要确保以下几点：\n1. **容器内安装 CLI**：必须在容器内部安装 qodercli (`npm install -g @qoder-ai\u002Fqodercli`)，而不仅仅是宿主机。\n2. **环境变量传递**：在 docker-compose.yml 或 run 命令中导出以下变量：\n - `QODER_PERSONAL_ACCESS_TOKEN`: 您的 PAT 令牌。\n - `QODER_CLI_WORKSPACE`: 设置为容器内的工作目录（例如 `\u002Fapp`）。\n3. **状态验证**：进入容器内部运行 `qodercli status` 确认登录成功。\n如果仪表盘仍报错，请检查网络请求详情，确认是否是 Qoder 服务端返回了 500 错误，这可能与容器网络或令牌权限有关。",{"id":151,"question_zh":152,"answer_zh":153,"source_url":135},40428,"遇到 Google Token 刷新失败 (401 invalid_client) 错误该如何处理？","该错误 `invalid_client` 通常表示提供的 Client Secret 无效或不匹配。请检查以下步骤：\n1. 确认您在 Google Cloud Console 中创建的 OAuth 凭据（Client ID 和 Client Secret）是正确的，并且没有复制多余的空格。\n2. 确保在 OmniRoute 的环境变量或配置文件中填写的 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET` 与 GCP 控制台完全一致。\n3. 如果是 Docker 部署，确保这些环境变量已成功注入到容器环境中。\n4. 某些情况下，需要在 GCP 控制台的\"OAuth 同意屏幕\"中发布应用或将测试用户添加到位，否则也会引发认证错误。",[155,160,165,170,175,180,185,190,195,200,205,210,215,220,225,230,235,240,245,250],{"id":156,"version":157,"summary_zh":158,"released_at":159},323817,"v3.6.6","### ✨ 新功能\n\n- **feat(storage):** 增加数据库备份清理控制、UI 管理以及可自定义保留期限的环境变量 (#1304)\n- **feat(providers):** 新增 Freepik Pikaso 图像生成提供商，支持基于 Cookie 或订阅的认证模式 (#1277)\n- **feat(providers): 添加 Perplexity Web (Session) 提供商** — 通过会话 Cookie 路由至 Perplexity 内部 SSE API，无需额外 API 费用即可原生代理访问 GPT-5.4、Claude Opus、Gemini 3.1 Pro 和 Nemotron，具体可通过偏好设置映射实现 (#1289)\n- **feat(api): 同步令牌与 V1 WebSocket 桥接** — 专用的同步令牌存储、签发、撤销及捆绑包下载路由，依托稳定的配置捆绑版本控制并支持 ETag。公开 `\u002Fv1\u002Fws` WebSocket 升级路由及自定义 Next.js 服务器桥接（`scripts\u002Fv1-ws-bridge.mjs`），以便将兼容 OpenAI 的 WebSocket 流量通过网关代理转发。合规审计范围扩展至结构化元数据、分页、请求上下文、认证\u002F提供商凭据事件以及 SSRF 阻断验证日志记录。新增迁移文件：`024_create_sync_tokens.sql`。新增模块：`syncTokens.ts`、`src\u002Flib\u002Fsync\u002Fbundle.ts`、`src\u002Flib\u002Fsync\u002Ftokens.ts`、`src\u002Flib\u002Fws\u002Fhandshake.ts`、`src\u002Flib\u002FapiBridgeServer.ts`、`src\u002Flib\u002Fcompliance\u002FproviderAudit.ts`。\n- **feat(models): GLM 思考预设与混合 token 计数** — GLM 思考 (`glmt`) 被注册为一等公民级别的提供商预设，共享 GLM 模型元数据、定价、按连接的用量同步、仪表板支持，并提供 `maxTokens: 65536 \u002F thinkingBudgetTokens: 24576` 的请求默认值及 900 秒的延长超时。当上游 Claude 兼容服务支持时，优先使用提供商端的 `\u002Fmessages\u002Fcount_tokens` 端点；若模型缺失、凭据不足或上游故障，则优雅降级为估算模式。启动时对默认模型别名进行种子初始化（`src\u002Flib\u002FmodelAliasSeed.ts`），以统一跨代理的常见模型方言，避免规范的斜杠式模型 ID 被错误路由。新增文件：`open-sse\u002Fconfig\u002FglmProvider.ts`。\n- **feat(core): 加强出站提供商调用与冷却重试机制** — 提供受保护的出站 fetch 辅助函数（`src\u002Fshared\u002Fnetwork\u002FsafeOutboundFetch.ts`、`src\u002Fshared\u002Fnetwork\u002FoutboundUrlGuard.ts`），可阻止私有\u002F本地 URL，并支持可配置的重试逻辑、超时标准化及路由级状态传播，用于提供商验证和模型发现。具备冷却感知的聊天重试逻辑（`src\u002Fsse\u002Fservices\u002FcooldownAwareRetry.ts`），支持可配置的 `requestRetry` 和 `maxRetryIntervalSec` 设置，并能根据模型作用域返回冷却响应。改进了从响应头和错误体中学习限流信息的能力，使短暂的上游锁定能够自动恢复。运行时环境验证（`src\u002Flib\u002Fenv\u002FruntimeEnv.ts`）会在启动时检查环境变量。Pollinations 现在需要 API 密钥。通过 `open-sse\u002Fconfig\u002FantigravityUpstream.ts` 和 `open-sse\u002Fconfig\u002FcodexClient.ts` 统一对抗重力及 Codex 的头部处理方式。Gemini 工具名称已在翻译后的响应中恢复；同时注入了合成的 Claude 文本块。","2026-04-16T08:44:19",{"id":161,"version":162,"summary_zh":163,"released_at":164},323818,"v3.6.5","### ✨ 新功能\n\n- **反重力 AI 信用额度回退机制：** 当免费层级配额用尽时，自动通过注入 `GOOGLE_ONE_AI` 信用额度进行重试。每个账户的信用余额（5 小时 TTL）会从 SSE 的 `remainingCredits` 中缓存，并在提供商使用情况仪表板中以数字徽章形式展示 (#1190 — 感谢 @sFaxsy)。\n- **Claude Code 原生对等性：** 完整的头部\u002F主体签名对等性，与 Claude Code 2.1.87 OAuth 客户端一致——使用 CCH xxHash64 对主体进行签名，并采用单例 WASM 初始化 Promise 来解决竞态条件问题；支持动态的每请求指纹；实现 TitleCase ↔ 小写工具名称的双向映射（共 14 种工具）；强制执行 API 约束（思考时 `temperature=1`，最多 4 个 `cache_control` 块，在最后一条用户消息上自动注入临时状态）；以及可选的 ZWJ 混淆功能。该功能已接入 `BaseExecutor`，用于所有 `anthropic-compatible-cc-*` 提供商的自动 CCH 签名，并接入 `chatCore` 以实现同步的对等性流程步骤 (#1188 — 感谢 @RaviTharuma)。\n- **按连接设置 Codex 默认值：** Codex 快速服务层级和推理力度设置现改为按连接配置，而非单一的全局开关。现有连接将在启动时通过幂等的补填迁移自动完成升级 (#1176 — 感谢 @rdself)。\n- **Cursor 使用情况仪表板：** 新增 `getCursorUsage()` 接口，可从 Cursor 的 `\u002Fapi\u002Fusage`、`\u002Fapi\u002Fauth\u002Fme` 和 `\u002Fapi\u002Fsubscription` 端点获取配额信息。显示标准请求、按需用量以及各套餐的限制（Free\u002FPro\u002FBusiness\u002FTeam）。客户端版本升级至 `3.1.0`，并添加了 `x-cursor-user-agent` 头以实现对等性。\n- **数据库健康检查系统：** 通过 `runDbHealthCheck()` 实现 SQLite 数据库完整性的自动化定期监控——可检测孤立的配额\u002F域名记录、损坏的组合引用、过时的快照以及无效的 JSON 状态。每 6 小时运行一次（可通过 `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` 配置），具备自动修复及修复前备份功能。作为 **MCP 工具 #18** (`omniroute_db_health_check`) 公开，配有 Zod 架构和 `autoRepair` 选项。健康页面新增仪表板面板，包含状态卡片、问题数量、已修复数量以及一键修复按钮。\n- **OpenAI Responses API 存储选项：** 新增按连接设置的 `openaiStoreEnabled` 标志，用于控制在 Codex Responses API 请求中是否保留 `store` 字段或将其强制设为 `false`。启用后，`previous_response_id`、`prompt_cache_key`、`session_id` 和 `conversation_id` 字段将贯穿 Chat Completions → Responses 的转换过程，从而在支持的提供商上实现多轮对话上下文缓存。\n- **邮件隐私切换开关（组合页面）：** 在组合页面页眉中新增全局邮件可见性切换开关 (`EmailPrivacyToggle`)，配备响应式布局、提示工具引导以及通过 `pickDisplayValue()` 实现的按连接标签遮掩功能。所有组合构建器选项、提供商连接列表和配额屏幕现均会尊重来自 `emailPrivacyStore` 的全局隐私状态。\n- **skills.sh 集成：** 新增 `skills.sh` 作为外部技能提供商。用户现在可以搜索、浏览并安装 age","2026-04-14T01:10:28",{"id":166,"version":167,"summary_zh":168,"released_at":169},323819,"v3.6.4","### ✨ 新功能\n\n- **组合构建器 v2（向导式 UI）：** 全面重新设计了组合创建\u002F编辑界面，采用多步骤向导模式，分为基础信息 → 步骤 → 策略 → 审核四个阶段。构建器通过新的 `GET \u002Fapi\u002Fcombos\u002Fbuilder\u002Foptions` 接口获取提供商、模型和连接元数据，支持精准的提供商\u002F模型\u002F账户选择，并具备重复项检测及自动推荐下一个连接的功能。重型 UI 组件（`ModelSelectModal`、`ProxyConfigModal`、`ModelRoutingSection`）现通过 `next\u002Fdynamic` 按需加载，以提升页面首次渲染速度。\n \n- **组合步骤架构（Schema v2）：** 引入结构化的步骤模型（`ComboModelStep`、`ComboRefStep`），取代原有的扁平化字符串\u002F对象组合条目。每个步骤明确包含 `id`、`kind`、`providerId`、`connectionId`、`weight` 和 `label` 字段，支持固定账户路由、跨组合引用以及每步指标统计。所有组合的 CRUD 操作均通过新的 `src\u002Flib\u002Fcombos\u002Fsteps.ts` 模块进行标准化处理。Zod Schema 已更新为包含 `comboModelStepInputSchema` 和 `comboRefStepInputSchema` 的联合类型。\n\n- **复合层级系统：** 增加了基于 `config.compositeTiers` 的分层模型路由——每个层级将一个命名阶段映射到特定的组合步骤，并可配置可选的回退链路。内置全面的验证逻辑（`src\u002Flib\u002Fcombos\u002FcompositeTiers.ts`），确保步骤存在、防止循环回退，并验证默认层级引用的有效性。Zod Schema 强制约束在全局默认设置中禁止使用复合层级（仅允许具体组合）。\n\n- **模型能力注册表：** 创建了 `src\u002Flib\u002FmodelCapabilities.ts`，提供 `getResolvedModelCapabilities()` 方法——一个统一的能力解析器，可将静态规格、提供商注册表数据以及实时同步的能力信息合并为单一的 `ResolvedModelCapabilities` 对象，涵盖工具调用、推理、视觉、上下文窗口、思考预算、模态以及模型生命周期元数据等信息。\n\n- **可观测性模块：** 将健康状态与遥测数据负载的构建提取至 `src\u002Flib\u002Fmonitoring\u002Fobservability.ts`，提供 `buildHealthPayload()`、`buildTelemetryPayload()` 和 `buildSessionsSummary()` 构建函数。健康端点现除原有系统指标外，还返回会话活动、配额监控状态及按提供商细分的数据。\n\n- **会话与配额监控仪表盘：** 在健康仪表盘中新增了实时会话活动与配额监控面板，展示活跃会话数、粘性绑定会话、按 API Key 的细分数据以及顶级会话详情；同时集成配额监控的告警、耗尽及错误状态，并支持按提供商的下钻查看。\n\n- **组合健康目标级分析：** 组合健康 API 现可通过新的 `resolveNestedComboTargets()` 函数解析目标级指标，提供执行密钥维度下的步骤成功率、延迟及历史用量细分，从而实现按账户、按连接的健康状况可视化。\n\n- **自动组合 → 组合统一：** 将独立的 `\u002Fdashboard\u002Fauto-combo` 页面合并至主 `\u002Fdashboard\u002Fcombos` 页面。Au","2026-04-12T23:10:46",{"id":171,"version":172,"summary_zh":173,"released_at":174},323820,"v3.6.3","### ✨ 新功能\n\n- **OpenAI 兼容的宽松验证：** 现在可以自然地提交并保存任何 `openai-compatible-*` 提供商（例如 Pollinations、本地化路由）的空 API 密钥，直接在 UI 中完成，而不再阻止保存操作 (#1152)\n- **Cloudflare 配置：** 更新了 Cloudflare AI 的提供商模式和 UI 集成，以正式公开并安全支持后端的 `accountId` 字段，且无需覆盖 (#1150)\n\n### 🐛 修复的 Bug\n\n- **Vertex JSON 验证崩溃：** 通过创建一个原生的身份验证解析器，在向端点发起请求之前正确处理 Google 身份服务账号的 JSON 流程，从而防止 `\u002Fvalidate` 端点内部出现 `头部中包含无效字符` 的崩溃问题 (#1153)\n- **多余负载拒绝：** 通过强制移除 Cursor\u002FCline IDE 引擎在调用严格的 OpenAI\u002FAnthropic 路由时附加的非标准 `prompt_cache_retention` 属性，全局避免了上游 `400 Bad Request` 执行崩溃的问题 (#1154)\n- **推理内容丢失：** 通过明确调整 `Empty Content (502)` 断路器，使其将 `reasoning_content` 状态视为有效，从而防止像 DeepSeek 这样的高级回退模型中常见的纯推理数据包在传输过程中被中断 (#1155)\n- **桌面 Windows 版本构建崩溃：** 修复了 `better_sqlite3.node 不是有效的 Win32 应用程序` 错误，该错误导致 OmniRoute Desktop 在 Windows 上无法启动。具体做法是正确移除 Next.js 独立版本中 ABI 不匹配的 sqlite 缓存，并在打包构建步骤中回退到交叉编译的 Electron 替代方案 (#1163)\n- **登录界面视觉安全性：** 移除了在缺少 `OMNIROUTE_API_KEY_BASE64` 标志的 Docker 实例中，人工显示在登录模态下方的原始后备哈希转储信息 (#1148)\n\n### 🔧 维护与依赖项更新\n\n- **Dependabot 更新：** 安全地将 GitHub Actions 的 `docker\u002Fbuild-push-action` 升级至 v7，将 `actions\u002Fdownload-artifact` 升级至 v8\n- **Electron 更新：** 将桌面封装核心升级至 Electron `41.2.0`，并将 `electron-builder` 升级至 `26.8.1`，同时引入了重要的 V8\u002FChromium 安全补丁\n- **NPM 包组：** 更新了 `production` 和 `development` NPM 包组，以安全地处理轻微的审计警告，并保持工具链的现代化\n- **CI\u002FCD 可靠性：** 通过在 dependabot 操作中适当绕过，修复了自动化拉取请求中持续存在的 `Snyk` 令牌缺失失败问题\n\n## 变更内容\n* chore(deps): 将 docker\u002Fbuild-push-action 从 6 升级至 7，由 @dependabot[bot] 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1156 中完成\n* chore(deps): 将 actions\u002Fdownload-artifact 从 4 升级至 8，由 @dependabot[bot] 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1157 中完成\n* deps: 将 electron 从 40.8.5 升级至 41.2.0，由 @dependabot[bot] 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1158 中完成\n* deps: 生产组进行了 3 次更新，由 @dependabot[bot] 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1161 中完成\n* deps: 开发组进行了 7 次更新，由 @dependabot[bot]","2026-04-11T21:56:12",{"id":176,"version":177,"summary_zh":178,"released_at":179},323821,"v3.6.2","### ✨ 新功能\n\n- **新增 33 家 API Key 提供商**：大幅扩展提供商列表，新增 DeepInfra、Vercel AI Gateway、Lambda AI、SambaNova、nScale、OVHcloud AI、Baseten、PublicAI、Moonshot AI、Meta Llama API、v0 (Vercel)、Morph、Featherless AI、FriendliAI、LlamaGate、Galadriel、Weights & Biases Inference、Volcengine、AI21 Labs、Venice.ai、Codestral、Upstage、Maritalk、Xiaomi MiMo、Inference.net、NanoGPT、Predibase、Bytez、Heroku AI、Databricks、Snowflake Cortex 以及 GigaChat (Sber)。OmniRoute 现已支持 **100 多家提供商**（4 家免费 + 8 家 OAuth + 91 家 API Key + 自定义兼容）。\n- **全局邮箱隐私切换**：在所有仪表板页面（提供商、使用限制、Playground）上新增了一个持久的“眼睛”图标切换按钮，用于显示或隐藏遮掩后的邮箱地址。切换状态会存储在 localStorage 中，并通过 Zustand 状态管理库在全球范围内同步。\n- **文档更新**：针对 v3.6.2 版本更新了 README、ARCHITECTURE、FEATURES、AGENTS.md 和 API_REFERENCE 文件，包括准确的提供商数量（100+）、新的执行器列表以及系统 API 文档。\n- **卸载指南**：创建了全面的 `docs\u002FUNINSTALL.md` 文档，涵盖所有部署方式（npm、Docker、Electron、源码）的干净卸载流程。\n\n### 🐛 错误修复\n\n- **PDF 附件**：解锁了深层字符串对象解析（`geminiHelper`），确保 Gemini 翻译能够成功传递来自 OpenAI 兼容流的复杂 PDF 负载，而不会将其静默丢弃 (#993)。\n- **SkillsMP 引擎**：修正了 API 路由器内部的对象提取路径映射，以解决 Docker\u002F独立 Node 部署环境下 UI 市场的渲染问题 (#988)。","2026-04-11T18:18:36",{"id":181,"version":182,"summary_zh":183,"released_at":184},323822,"v3.6.1","### ✨ 新功能\n\n- **OAuth 环境修复动作**：在 OAuth 提供商仪表板中新增了“修复环境”按钮，可检测并从 `.env.example` 文件中恢复缺失的 OAuth 客户端 ID — 同时提供带时间戳的备份和仅追加的安全机制。包含完整的 33 种语言国际化支持及经过 sanitization 的 API 响应 (#1116，由 @yart 实现）\n\n### 🐛 问题修复\n\n- **i18n：缺少提供商键值**：在所有 32 个本地化文件中添加了缺失的 `filterModels`、`modelsActive`、`showModel` 和 `hideModel` 键值，修复了提供商 UI 中出现的运行时 `MISSING_MESSAGE` 错误。同时清理了 `en.json` 文件中的重复键值 (#1111，由 @rilham97 实现）\n- **GPT-5.4 路由配置**：在 Codex 和 GitHub Copilot 提供商中，为 `gpt-5.4` 和 `gpt-5.4-mini` 模型添加了缺失的 `targetFormat: \"openai-responses\"` 配置项，从而修复了 `[400]: 模型无法通过 \u002Fchat\u002Fcompletions 接口访问` 的错误 (#1114，由 @ask33r 实现）\n\n---\n\n## 变更内容\n* chore(release)：v3.6.1 — OAuth 环境修复 + i18n 修复，由 @diegosouzapw 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1117 中完成\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.6.0...v3.6.1","2026-04-10T15:24:51",{"id":186,"version":187,"summary_zh":188,"released_at":189},323823,"v3.6.0","### ✨ 新功能与分析\n\n- **组合烟雾测试：** 将默认的令牌预算提高到 2048，以防止在预检过程中思维模型被截断，并完全随机化算术探测提示，从而绕过上游代理的确定性缓存（#1105）\n\n### 🐛 错误修复与合规性改进\n\n- **数据库膨胀\u002F行数限制：** 在后端数据库合规清理工具中新增了 `CALL_LOGS_TABLE_MAX_ROWS` 和 `PROXY_LOGS_TABLE_MAX_ROWS` 配置项（默认值：100,000），以防止 SQLite 数据库无限制增长。这些限制会在 TTL 周期内自动生效（#1104，修复 #1101）\n- **HTML 错误处理：** 路由器现在能够正确识别由上游提供商（如 Azure\u002FCopilot）发送的意外 HTML 响应（例如 `\u003C!DOCTYPE html>`），而不再抛出晦涩难懂的 `Unexpected token '\u003C'` JSON 解析错误，而是返回清晰的 502 Bad Gateway 错误（#1104，修复 #1066）\n- **Android\u002FTermux 中的 SQLite 原生支持：** `better-sqlite3` 现在能够在 ARM64 架构的本地 Termux 环境中使用交叉编译标志从源码正确构建，而不会因缺少预编译二进制文件而导致失败（#1107）\n\n---\n\n## 变更内容\n* 版本 v3.6.0 由 @diegosouzapw 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1109 中发布\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.9...v3.6.0","2026-04-10T13:02:32",{"id":191,"version":192,"summary_zh":193,"released_at":194},323824,"v3.5.9","### ✨ 新功能\n\n- **组合订单持久化**：在仪表板中通过拖拽组合卡片的句柄来重新排序；顺序会通过新的 `sort_order` 列和 `POST \u002Fapi\u002Fcombos\u002Freorder` 端点保存到 SQLite 数据库中。包含数据库迁移文件 `020_combo_sort_order.sql` 以及 JSON 导入数据的保留功能 (#1095)\n- **侧边栏分组重新排序**：将系统部分中的“日志”移动到“健康”之前，将主要部分中的“限制与配额”移动到“缓存”之后，以提供更符合逻辑的导航流程 (#1095)\n\n### 🐛 问题修复\n\n- **流失败信息透传**：上游 `response.failed` 事件（例如 Codex 的速率限制错误）现在会被正确地作为非 200 错误透传出来，而不再被静默吞没为一个空的 200 OK 流。速率限制失败将返回 HTTP 429 状态码 (#1098，关闭 #1093)\n- **上游模型保留**：响应到 OpenAI 的流转换器现在会保留实际的上游模型（例如 `gpt-5.4`），而不是硬编码回退到 `gpt-4` (#1098，关闭 #1094)\n- **Docker EXDEV 修复**：当 Docker buildx 抛出 `EXDEV`（跨设备链接）错误时，`build-next-isolated.mjs` 现在会从 `fs.rename()` 回退到 `cp\u002Frm` 操作，从而解除 Docker 镜像发布流程的阻塞 (#1097)\n- **macOS CLI 路径解析**：`cliRuntime.ts` 现在使用 `fs.realpath()` 解析符号链接的父路径，以处理 macOS 中 `\u002Fvar` → `\u002Fprivate\u002Fvar` 的链式结构，防止出现虚假的 `symlink_escape` 拒绝错误 (#1097)\n- **请求日志令牌布局**：将令牌标签拆分为独立的输入组（总输入、缓存读取、缓存写入）和输出组（总输出、推理），以提高可读性；并将“时间”标签重命名为“完成时间” (#1096)\n\n---\n\n## 变更内容\n* 修复（流）：由 @yart 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1098 中实现，用于透传响应失败并保留上游模型\n* 修复（Docker）：由 @rdself 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1097 中实现，用于处理隔离构建中的 EXDEV 错误\n* 修复请求日志详细信息中的令牌布局，由 @rdself 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1096 中完成\n* 添加组合订单持久化功能，并重新排序侧边栏项目，由 @rdself 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1095 中实现\n* 杂项（发布）：v3.5.9 — 组合订单、流失败处理、Docker 构建修复，由 @diegosouzapw 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1102 中完成\n\n## 新贡献者\n* @yart 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1098 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.8...v3.5.9","2026-04-10T01:32:52",{"id":196,"version":197,"summary_zh":198,"released_at":199},323825,"v3.5.8","### ✨ 新功能与分析\n\n- **分析布局重新设计：** 将扁平化的指标替换为响应式 `CompactStatGrid`，按区块对数据进行视觉分组 (#1089)\n\n### 🐛 问题修复\n\n- **构建核心：** 通过 Prepbulish 脚本强制执行 Turbopack 清理，以防止 Next.js 16 应用程序路由在运行时发生冲突。\n- **供应商隔离：** 引入基于自适应 TTL 的指数退避机制的模型\u002F供应商熔断器，用于处理重复出现的上游错误 (#1090)\n- **OAuth 持久化：** 安全保护已认证的活跃账户，避免因临时性的令牌刷新失败而导致路由自动注销 (#1085)\n\n### 🔒 安全与维护\n\n- **Dependabot：** 将 axios 从 1.14.0 升级至 1.15.0，以解决 SSRF 相关警告 (#1088)\n\n---\n\n## 变更内容\n* 版本 v3.5.8 由 @diegosouzapw 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1092 中发布\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.7...v3.5.8","2026-04-09T22:40:47",{"id":201,"version":202,"summary_zh":203,"released_at":204},323826,"v3.5.7","## [3.5.7] — 2026-04-09\n\n### 🐛 Bug 修复与安全\n\n- **Turbopack 独立 chunk：** 修复了 `scripts\u002Fprepublish.mjs` 中的一个严重 bug，该 bug 导致 `.next\u002Fstandalone` 跟踪中缺失的 Turbopack chunk 在通过 NPM 或 Docker 进行生产部署时引发 `500 ChunkLoadError`（例如 `_not-found` 页面崩溃）。现在会显式复制独立 chunk，并正确移除其中的 Turbopack 哈希值。\n\n\n## 变更内容\n* v3.5.7 修复版：Turbopack 独立 chunk，由 @diegosouzapw 在 https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1091 中实现。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.6...v3.5.7","2026-04-09T20:33:48",{"id":206,"version":207,"summary_zh":208,"released_at":209},323827,"v3.5.6","OmniRoute v3.5.6 Release\n\n## What's Changed\n* chore(release): v3.5.6 — email masking, model toggle, OpenRouter registries & bug fixes by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1080\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.5...v3.5.6","2026-04-09T19:01:02",{"id":211,"version":212,"summary_zh":213,"released_at":214},323828,"v3.5.5","\n### ✨ New Features\n\n- **Node.js 24 Compatibility Warning:** Added a proactive version incompatibility warning on the login page to guide users to the stable Node.js 22 LTS, preventing native sqlite binding crashes.\n- **Context Relay Combo Strategy:** Added the new `context-relay` combo strategy with priority-style routing, structured handoff summary generation once quota usage reaches the warning threshold, and handoff injection after the next real account switch.\n- **Global Context Relay Defaults:** Added global Settings defaults plus combo-level configuration for `handoffThreshold`, `handoffModel`, and `handoffProviders`, so new or unconfigured combos can inherit the feature consistently.\n\n### 🐛 Bug Fixes\n\n- **Proxy Connection Healthchecks:** Applied proxy resolution per connection in the sweeping loop (`tokenHealthCheck.ts`) and global provider validation sweeps, resolving Node 22 bypass and improving proxy stability (#1051, #1056, #1061).\n- **Security Vulnerability Remediation:** Resolved multiple CodeQL scanning alerts including SSRF in model sync, insecure randomness in web crypto (`generateSessionId`), and incomplete URL sanitization.\n- **Context Relay Typing & Synchronization:** Reverted out-of-scope test breakages and resolved `handoffProvider` and response `input` extraction payload typing.\n- **Legacy OpenAI-Compatible Responses Routing:** Fixed legacy\u002Fimported OpenAI-compatible providers (for example `openai-compatible-sp-openai`) incorrectly routing Chat Completions traffic to `\u002Fchat\u002Fcompletions` when the real provider node was configured as `apiType: \"responses\"`. OmniRoute now treats `providerSpecificData.apiType` as authoritative across routing, executors, and translator tools, avoiding false empty-content failures during combo\u002Fprovider smoke tests (#1069).\n- **Gemini PDF Attachment Integration:** Fixed payload generation and format for parsing `inline_data` and generic base64 sources for deep Gemini PDF routing (#993, #1021).\n- **Vercel AI SDK Fallbacks:** Mapped `max_output_tokens` to `max_tokens` for strict OpenAI-compatible providers, resolving errors from standard AI agents and frameworks (#994).\n- **External Auth & UI Reliability:** Handled null `state` failures in Cline OAuth exchange (#1016), added 3rd-party 400 error patterns to combo fallback (#1024), and resolved desktop sidebar layout and popover overflows (#1039, #1001).\n- **Context Relay In-Flight Deduplication:** Prevented duplicate handoff generation for the same session\u002Fcombo while an earlier summary request is still in flight.\n- **Context Relay Provider Gating:** Aligned runtime behavior with configuration so explicit `handoffProviders` exclusions, including an empty array, now disable handoff generation as expected.\n\n### 🛠️ Maintenance & Dependabot\n\n- **Updated Sub-dependencies:** Bumped `hono` to `4.12.12` and `@hono\u002Fnode-server` to `1.19.13` to patch critical security gaps (#1063, #1064, #1067, #1068).\n\n### 📚 Documentation\n\n- **Documentation Synchronization:** Updated system documentation (README, Architecture, Features, Tools, Troubleshooting) and synced `i18n` configurations to match the v3.5.5 context relay patterns and proxy troubleshooting steps.\n- **Context Relay Delivery Notes:** Documented the current architecture, runtime flow, and Codex-focused scope in the feature docs, changelog, and agent guidance.\n\n---\n\n## What's Changed\n* Fix API provider error by @sevcator in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1061\n* deps: bump @hono\u002Fnode-server from 1.19.12 to 1.19.13 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1063\n* deps: bump hono from 4.12.9 to 4.12.12 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1064\n* deps: bump hono from 4.12.9 to 4.12.12 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1068\n* deps: bump @hono\u002Fnode-server from 1.19.12 to 1.19.13 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1067\n* Release\u002Fv3.5.5 by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1059\n\n## New Contributors\n* @sevcator made their first contribution in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1061\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.4...v3.5.5","2026-04-08T21:27:45",{"id":216,"version":217,"summary_zh":218,"released_at":219},323829,"v3.5.4","\n### ✨ New Features\n\n- **Detailed Token Tracking:** Added granular token breakdown columns (cache read, cache write, reasoning) to call logs with proper null vs zero distinction. Includes DB migration 018 and 5-label UI display per provider capability (#1017 — thanks @rdself).\n- **Legacy JSON Config Import\u002FExport:** Restored JSON-based settings export and import for migration from legacy 9router configurations. Security-hardened with Zero-Trust redaction of passwords and `requireLogin` fields, and automatic pre-import database backups (#1012 — thanks @luandiasrj).\n- **Non-Stream Aliases:** Added API support for explicit non-streaming aliases (`non_stream`, `disable_stream`, `disable_streaming`, `streaming=false`), normalized at the boundary before provider translation (#1036 — thanks @wlfonseca).\n- **Russian Dashboard Localization:** Comprehensive Russian translation for the dashboard UI, including fixes for 2 Ukrainian locale keys (#1003 — thanks @mercs2910).\n\n### 🐛 Bug Fixes\n\n- **Anthropic Streaming Input Undercount:** Fixed a critical bug where Anthropic streaming `prompt_tokens` only reported non-cached tokens (e.g., `in=3` when actual total was 113,616). Cache tokens are now summed into prompt_tokens during streaming (#1017).\n- **Built-in Responses API Tool Types:** Preserved built-in Responses API tools (`web_search`, `file_search`, `computer`, `code_interpreter`, `image_generation`) from being silently stripped by the empty-name tool filter — these tools carry no `.name` field (#1014 — thanks @rdself).\n- **Cursor\u002FCodex Responses Compatibility:** Fixed empty output in Cursor when using Codex models by hoisting system input items to `instructions`, sanitizing invalid tool names, and detecting Responses-format payloads on chat\u002Fcompletions endpoint (#1002 — thanks @mercs2910).\n- **OAuth Token Expiry Display:** Fixed OAuth connections showing \"expired\" badge even with valid tokens by reading `tokenExpiresAt` (updated on refresh) instead of `expiresAt` (original grant timestamp) (#1032 — thanks @tombii).\n- **Codex Fast-Tier Copy:** Corrected dashboard settings copy from `service_tier=fast` to `service_tier=priority`, matching the actual Codex wire format (#1045 — thanks @kfiramar).\n- **macOS Desktop App Startup:** Stabilized packaged macOS app launch by excluding desktop artifacts from the standalone bundle and improving launch path detection (#1004 — thanks @mercs2910).\n- **macOS Sidebar Layout:** Fixed macOS traffic light overlap, sidebar spacing, and button overflow in the Electron desktop app (#1001 — thanks @mercs2910).\n\n### ⚡ Performance\n\n- **Analytics Page Load:** Dramatically reduced analytics page load times (30s→1-2s for 50K entries) via date-filtered DB queries, parallel `Promise.all()` cost calculations, and merged 6 COUNT queries into a single CASE WHEN aggregate (#1038 — thanks @oyi77).\n\n### 🔒 Security & Dependencies\n\n- **Node Base Image:** Upgraded Docker base from `22-bookworm-slim` to `22.22.2-trixie-slim` (#1011 — Snyk).\n- **Production Dependencies:** Bumped 5 production dependencies (#1044 — Dependabot).\n- **Vite:** Bumped from 8.0.3 to 8.0.5 (#1031 — Dependabot).\n- **Development Dependencies:** Bumped 4 development dependencies (#1030 — Dependabot).\n\n### 🧪 Tests\n\n- **Token Accounting Tests:** Added 18 new unit tests covering detailed token breakdown, null vs zero semantics, per-provider token extraction, and Anthropic streaming input fix (#1017).\n- **Built-in Tool Tests:** Added 3 new test cases for built-in Responses API tool type preservation (#1014).\n- **ChatCore Sanitization:** Updated sanitization tests to accommodate Responses format detection (PR #1002) and built-in tool preservation (PR #1014).\n\n### 🛠️ Maintenance\n\n- **PR Workflow:** Updated `\u002Freview-prs` workflow to merge PRs into the release branch (`release\u002FvX.Y.Z`) instead of directly into `main`, ensuring proper pre-release staging.\n\n### Coverage\n\n- **2537 tests, 2532 passing** — Statement coverage: 91.95%, Branch coverage: 78.79%, Function coverage: 93.19%\n\n## What's Changed\n* [Snyk] Security upgrade node from 22-bookworm-slim to 22.22.2-trixie-slim by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1011\n* deps: bump the production group across 1 directory with 5 updates by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1044\n* deps: bump vite from 8.0.3 to 8.0.5 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1031\n* deps: bump the development group with 4 updates by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1030\n* fix: preserve built-in Responses API tool types in empty-name filter by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1014\n* feat: detailed token tracking + fix Anthropic input undercount by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1017\n* fix(ui): use tokenExpiresAt for OAuth token expiry display by @tombii in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1032\n* feat(api): aceitar aliases explícitos pa","2026-04-07T22:42:18",{"id":221,"version":222,"summary_zh":223,"released_at":224},323830,"v3.5.3","OmniRoute v3.5.3 Release\n\n## What's Changed\n* chore(release): v3.5.3 — Core Resilience, i18n Sync & Preflight Enhancements by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F1033\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.2...v3.5.3","2026-04-07T15:57:36",{"id":226,"version":227,"summary_zh":228,"released_at":229},323831,"v3.5.2","OmniRoute v3.5.2 Release\n\n## What's Changed\n* chore(release): v3.5.2 — Qoder DashScope Native Integration & Stability by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F999\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.1...v3.5.2","2026-04-05T05:54:55",{"id":231,"version":232,"summary_zh":233,"released_at":234},323832,"v3.5.1","OmniRoute v3.5.1 Release\n\n## What's Changed\n* Fix providers filter persistence and settings translations by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F970\n* fix(providers): resolve Gemini validation 4xx errors with header-based auth by @oyi77 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F977\n* Allow custom User-Agent on third-party providers by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F975\n* chore(release): v3.5.1 — Qwen OAuth Fixes by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F984\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.5.0...v3.5.1","2026-04-04T13:46:28",{"id":236,"version":237,"summary_zh":238,"released_at":239},323833,"v3.5.0","OmniRoute v3.5.0 Release\n\n## What's Changed\n* fix: keep cc-compatible cache ttl ordering valid by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F948\n* Clarify provider grouping and add a configured-only filter by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F950\n* feat(mcp): register omniroute_web_search tool by @Tasogarre in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F951\n* fix settings persistence and clean up cache analytics UI by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F952\n* feat(proxy): add proxy support for OAuth, token refresh, and model sync by @growab in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F953\n* feat+fix: memory 500, SkillsMP marketplace, DB cleanup, LKGP toggle & upstream 400 fixes by @oyi77 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F955\n* build(deps): bump docker\u002Fsetup-qemu-action from 3 to 4 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F961\n* build(deps): bump actions\u002Fcheckout from 4 to 6 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F963\n* build(deps): bump actions\u002Fdownload-artifact from 4 to 8 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F962\n* build(deps): bump docker\u002Fsetup-buildx-action from 3 to 4 by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F965\n* Addressing PR comments by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F964\n* chore(release): v3.5.0 — Core Settings, UI Splitting, Native SDK Caching & CodeQL Fixes by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F956\n* fix(auth): normalize codex alias credential lookup by @xiaoge1688 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F958\n* feat(usageTracking): make usage token buffer configurable by @mikhailsal in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F959\n* fix(cli): parse where output on Windows to prefer .cmd\u002F.exe wrappers by @razllivan in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F969\n\n## New Contributors\n* @Tasogarre made their first contribution in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F951\n* @growab made their first contribution in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F953\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.4.9...v3.5.0","2026-04-03T22:32:45",{"id":241,"version":242,"summary_zh":243,"released_at":244},323834,"v3.4.9","OmniRoute v3.4.9 Release\n\n## What's Changed\n* fix(gemini): preserve thought signatures across antigravity tool calls by @xiaoge1688 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F944\n* fix: restore GitHub Copilot combo requests by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F943\n* Fix cc-compatible cache markers by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F942\n* refactor(auth): improve NVIDIA alias lookup + add LKGP error logging by @oyi77 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F941\n* Restore Claude OAuth localhost callback handling by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F939\n* chore(release): v3.4.9 by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F947\n\n## New Contributors\n* @xiaoge1688 made their first contribution in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F944\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.4.8...v3.4.9","2026-04-03T06:56:39",{"id":246,"version":247,"summary_zh":248,"released_at":249},323835,"v3.4.8","OmniRoute v3.4.8 Release\n\n## What's Changed\n* chore(release): v3.4.8 — security and vulnerability patches by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F940\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.4.7...v3.4.8","2026-04-03T04:48:30",{"id":251,"version":252,"summary_zh":253,"released_at":254},323836,"v3.4.7","OmniRoute v3.4.7 Release\n\n## What's Changed\n* fix(gemini): API field casing, safety finish reasons, pagination timeout by @christopher-s in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F933\n* feat(routing): implement Last Known Good Provider (LKGP) strategy (#919) by @oyi77 in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F932\n* chore(release): v3.4.7 — OmniRoute Stability Release by @diegosouzapw in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F938\n* fix Claude OAuth, CC-compatible cache\u002Fmodel issues, and GitHub executor errors by @rdself in https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fpull\u002F937\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fdiegosouzapw\u002FOmniRoute\u002Fcompare\u002Fv3.4.6...v3.4.7","2026-04-03T01:50:40"]