OmniRoute 是一款免费开源的本地 AI 网关与通用大语言模型（LLM）代理工具。它可以将您分散的所有免费和付费 AI 模型账号（原生支持涵盖 OpenAI、Anthropic、Gemini、DeepSeek 等 60 多家服务商）统一聚合在一起，并在本地环境（如 localhost:20128）生成一个完全兼容 OpenAI 接口标准的 API 端点。任何支持 API 调用的工具，如 Cursor IDE、Claude Code 还是各种命令行 AI 编程助手，都可以直接接入该端点。
OmniRoute 的核心优势在于“智能路由与组合策略”。当用户在调用大模型时，如果某一个账号触发了速率限制、网络报错或额度耗尽，OmniRoute 能够以毫秒级的速度无缝自动切换（回退）到下一个可用的备用账号，确保开发者的 AI 辅助工具永远不会中断。此外，它还内置了负载均衡、语义级别的请求缓存、跨厂商多格式协议相互转换（如将 Claude 专有格式转换为 OpenAI 格式）、高可用断路器以及实时运行状态监控看板。通过 OmniRoute，开发者可以避免浪费未跑满的订阅额度，打破单一模型服务商的生态孤岛，实现成本最优化和稳定不间断的 AI 编程体验。
Function List
- 多平台模型聚合与统一接口：原生支持接入超过 60 家大模型服务商（包含 11 家永久免费提供商），并将其统一转换为单个完全兼容 OpenAI 协议的 API 接口，极大地简化了各类下游开发工具和本地客户端的配置。
- 内置丰富的智能路由策略（Combos）：内置 13 种 API 请求分发与负载均衡策略，包括填满优先（Fill First）、轮询（Round Robin）、最少使用（Least Used）、成本最优（Cost Optimized）、随机等，实现高效请求调度。
- 自动回退与高可用断路器（Circuit Breakers）：具备多节点自动回退链与智能断路器。当检测到某服务商出现故障、延迟过高或触发限流时，网关会在 1 秒内自动隔离故障节点并切换至备用模型，实现高可用无感切换。
- 跨平台多格式协议无缝翻译：底层内置强大的协议转换器，支持 OpenAI、Claude、Gemini 和 Responses API 接口格式之间的双向透明翻译，让仅支持特定后端（如仅支持 Anthropic）的工具能够跨平台调用任何其他模型。
- 语义缓存与成本优化（Semantic Cache）：自动缓存历史返回结果并进行语义级别的去重匹配，针对相同或高相似度的请求直接返回本地缓存数据，从而大幅降低 API 调用成本并消除网络响应延迟。
- 全功能可视化仪表盘：提供直观的本地 Web 控制台，方便用户可视化管理供应商账号、组合策略配置，并实时监控接口健康度、延迟统计、Token 消耗记录及限速状态。
- 全能提示词与模型测试游乐场：内置 4 种调试模式（游乐场、对话测试器、测试台、实时监视器），方便开发者在正式接入前对各模型路由链路的连通性和回答质量进行直观评估。
- 集成 MCP 服务器与 A2A 协议：内置支持模型上下文协议（MCP，集成 25 个系统级工具）和 Agent-to-Agent (A2A) 协议，赋予接入此网关的 AI 智能体直接操作本地系统和多层复杂任务执行的能力。
Using Help
OmniRoute 全面安装、配置与使用指南
OmniRoute 的设计初衷是让开发者“一次配置，终身无忧”。只要你在本地运行了 OmniRoute，后续无论你使用多少种 AI 编程工具，都只需对接 OmniRoute 即可。以下是详细的操作及配置流程：
一、 安装与启动方式
OmniRoute 支持跨平台部署，最简单的运行方式是通过 Node.js 或 Docker。
方式 1：通过 NPM 快速启动（官方推荐）
如果你本地已经安装了 Node.js 环境，无需繁琐的配置，直接打开终端执行以下一键启动命令：
npx omniroute@latest
启动成功后，OmniRoute 会自动在本地建立代理服务。其后台 Web 仪表盘的默认地址为 http://localhost:20128，对外的标准 OpenAI 兼容 API 接口地址为 http://localhost:20128/v1 。
方式 2：使用 Docker 容器化部署
如果你希望环境更加独立干净，推荐使用 Docker 官方镜像部署，支持持久化存储：
docker pull diegosouzapw/omniroute:latest
docker run -d -p 20128:20128 --name omniroute diegosouzapw/omniroute:latest
提示：通过容器部署时，可以通过映射卷（Volume）将容器内的配置数据持久化到宿主机上，确保升级镜像后配置不丢失。
二、 核心功能配置：供应商与组合策略
成功启动并进入仪表盘（http://localhost:20128）后，你需要按照以下逻辑来搭建你的 AI 路由池。
第一步：添加大模型服务商（Providers）
- 导航至左侧菜单栏的 Providers（服务商管理） Module.
- Click on the upper right corner of the Add Provider 按钮，你会看到长达 60+ 家受支持的服务商列表。
- 您可以添加主流的付费账号（如 OpenAI、Anthropic、Gemini、DeepSeek 的官方 API），也可以添加 OmniRoute 支持的 11 家完全免费的服务商（例如 Pollinations 等无须验证的免费节点，对于免费节点你甚至可以将 API Key 留空）。
- 填入对应的 API Key 并保存。系统会立即发起健康连通性测试，通过后状态会显示为绿色的
Healthy。
第二步：配置智能路由组合（Combos）
“Combos（组合）”是 OmniRoute 的灵魂。它允许你把刚才添加的零散服务商打包成一个“虚拟的最强模型”。
- go into Combos 页面，点击新建并为其命名（例如命名为：
My-Coding-Pro）。 - 将第一步中添加的可用账号（如两个免费节点 + 一个付费兜底节点）全部勾选并加入到这个 Combo 池中。
- 设置路由分发策略（Routing Strategy）：
- 成本最优（Cost Optimized）：系统自动优先调用定价为 0 或是单价最低的账号接口。
- 轮询（Round Robin）：将高并发请求平均分配给各个账号，极大程度避免单账号触发 429 限流风控。
- 优先打满（Fill First）：一直消耗池子里排序第一的账号额度，直到耗尽报错，系统再零延迟平滑回退（Fallback）到下一个账号。
- 保存后，这个 Combo 的名字（
My-Coding-Pro）就可以被当做标准模型名称，直接被第三方工具调用。
三、 第三方 AI 工具集成教程
配置好本地网关池后，你需要将手头的生产工具网关代理指向 OmniRoute。
案例 1：在 Cursor IDE 中无缝对接 OmniRoute
Cursor 是一款强大的 AI 编程 IDE，很多用户经常面临官方额度不够用的问题。
- 打开 Cursor IDE，点击右上角齿轮图标进入 Settings (设置) -> Models (模型)。
- locate OpenAI API Key 设置项并展开自定义覆盖设置。
- 将 Base URL（基础地址） 覆盖填写为：
http://localhost:20128/v1 - 将 API Key 随意填写为任意占位符（例如：
sk-omniroute）。因为权限验证已由本地 OmniRoute 代理接管，此处只需绕过客户端验证即可。 - 在输入栏手动输入你刚配置的虚拟组合模型名称（如
My-Coding-Pro）并设为默认。 - Description of effect：后续你在 Cursor 中的所有代码生成请求，都将发往 OmniRoute。如果主节点触发限速，OmniRoute 会在毫秒内自动将请求无缝转发给备选节点并将结果传回给 Cursor，开发者在编写代码时完全感受不到中断与等待！
案例 2：在 Claude Code 或仅支持单厂商格式的工具中使用
某些特定的命令行 AI Agent 工具（例如官方的 Claude Code）在底层默认硬编码要求必须返回 Anthropic 的数据格式。OmniRoute 的跨平台多格式翻译功能此时就能大显身手。
你只需要在系统环境变量中设置拦截：
export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
export ANTHROPIC_API_KEY="sk-omni"
claude # 直接启动 Claude Code 代理
在这个模式下，即便是 Claude 专有格式的请求，OmniRoute 网关也能从底层自动“翻译转换”给对应的后端模型（例如实际转发给 Gemini 或 DeepSeek 处理）。
四、 高可用进阶设置（提升系统稳定性）
- 自动断路器（Circuit Breakers）：在仪表盘的设置中强烈建议保持断路器开启。当网络波动导致某服务商的健康评分骤降低于 0.2 时，网关会将其自动剔除出调度队列 5 分钟并触发指数级退避策略（最高隔离 30 分钟）。确保您的并发请求永远发给健康的节点。
- 开启语义级缓存（Semantic Cache）：如果你经常需要跑同样的单元测试生成或者让 AI 重复校验相同的代码逻辑，开启缓存功能可以实现高达 80% 的本地命中率。针对命中缓存的调用，不仅实现 0 Token 费用损耗，还能将原本需要数秒的 AI 推理生成时间压缩到几毫秒内。
application scenario
- AI 编程 IDE 的无缝高可用后端
在使用 Cursor、Cline 或 GitHub Copilot 等重度依赖 AI 接口的编程工具时，通过 OmniRoute 建立多模型并发回退机制。当遇到单个平台的额度用尽或接口崩溃时，瞬间实现备用节点自动切换，保障编写代码工作流永不中断。 - 零成本整合多平台免费 AI 接口资源
对于个人开发者或独立极客，利用网关自带的 Cost Optimized 策略整合 11 个无需付费的节点提供商。将其聚合为一个可用性极高的统一服务入口，从而实现完全免费的长效 AI 对话与代码生成。 - 团队级 API 额度池化与跨账号资源共享
在小微开发团队中，不同成员可能各自购买了独立的订阅。将团队中所有成员零散未消耗尽的 Token 与 API 密钥输入到一台共用局域网的 OmniRoute 服务器中，统一分配调度，彻底避免计算资源的错配和浪费。 - 单平台工具的跨模型转译支持
对于只能调用单一后端平台的工具（如只能调用 Anthropic 接口的特定脚本），将其接口转发至本代理工具。通过底层透明拦截并将请求翻译转换为通用格式，打破特定厂商封锁，使得该工具实际能调取全网任意最新的大模型服务。
QA
- 什么是 OmniRoute？为什么需要使用它？
OmniRoute 是一个本地 AI 网关代理工具。市面上的各种大语言模型都有严格的限速墙（Rate Limit）或月度使用限额，导致开发者在使用 AI 工具时频繁遇到“额度耗尽”被迫中断的问题。OmniRoute 通过聚合各种免费或付费大模型账号形成一个代理池。当某一个账号受限时，它可以自动无缝切换到备用账号，保证你的使用过程不被中断。 - OmniRoute 真的能帮我节省 API 调用成本吗？
可以。首先，平台支持聚合多达 11 家完全免费的大模型节点提供商，您可以使用“成本优先”策略默认白嫖免费接口。其次，它具备本地语义级别的缓存功能，多次重复提问的内容将直接读取本地缓存，无需请求云端，从源头上减少 Token 的计费消耗。 - 它是纯离线使用的吗？是否需要上传我的个人代码或数据？
OmniRoute 是完全开源且本地运行的代理网关。您的 API 凭证只保存在本地计算机上，数据仅由您直接发送给配置对应的 AI 模型服务商（如 OpenAI 的服务器），OmniRoute 自身不会在云端存储、上传或监控您的任何交互记录，保障了最高级别的安全性和隐私。 - 它支持哪些常见的第三方 AI 工具？
理论上支持任何允许修改 API 地址（Base URL）并兼容 OpenAI 格式的工具。目前测试完美兼容：Cursor IDE、Claude Code、OpenAI Codex、Cline、Kilo Code、OpenClaw、GitHub Copilot 等近 15 种主流编程智能体与工具。
