# 🚀 OmniRoute — 免费 AI 网关 🌐 **语言:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇹🇼 [zh-TW](../zh-TW/README.md) ---

# 🚀 OmniRoute — 免费 AI 网关 ### 编码，永无止境。通过一个端点，让所有 AI 工具直连 **236 家服务商** — **50+ 家免费**。 **将 Claude Code、Codex、Cursor、Cline、Copilot 和 Antigravity 接入免费的 Claude / GPT / Gemini。自动容灾，无感切换。**
**RTK + Caveman 压缩引擎，Token 节省 15–95%。从此告别用量限制。**
**约 1.6B 可统计免费 Token / 月** — 计入注册奖励后，首月最高可达 **~2.1B** — 聚合各家免费层配额，外加一众永久免费、不限量的服务商；再叠加上述压缩引擎，每一枚 Token 都物超所值。([统计方法 →](../../reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))
[![231 AI Providers](https://img.shields.io/badge/231-AI_Providers-6C5CE7?style=for-the-badge)](#-231-ai-providers--50-free) [![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-231-ai-providers--50-free) [![1.6B Free Tokens/mo](https://img.shields.io/badge/1.6B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](../../reference/FREE_TIERS.md) [![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically) [![18 Strategies](https://img.shields.io/badge/18-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship) [![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
### 💬 加入社区 [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/EkzRkpzKYt) [![Telegram](https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/omnirouteOficial) [![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) [![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI) **疑难解答、服务商攻略、路线图与支持 → [Discord](https://discord.gg/EkzRkpzKYt) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 全球](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 巴西](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)**

[![npm](https://img.shields.io/npm/v/omniroute?logo=npm&style=flat-square)](https://www.npmjs.com/package/omniroute) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE) [![Node](https://img.shields.io/badge/node-%E2%89%A522.0.0-brightgreen?style=flat-square)](../../package.json) [![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)

[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) ![NPM Monthly](https://img.shields.io/npm/dm/omniroute?label=npm/month&color=cb3837&logo=npm) [![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) ![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED) ![Electron Downloads](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)

[**🚀 快速开始**](#-quick-start) • [**🎯 Combo**](#-combos--the-flagship) • [**🌐 服务商**](#-231-ai-providers--50-free) • [**🔌 CLI 与 MCP**](#-full-cli--a2a--mcp) • [**🗜️ 压缩**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 官网**](https://omniroute.online) [💥 我们的承诺](#-the-promise) • [🤔 为什么选择 OmniRoute](#-why-omniroute) • [🏆 核心优势](#-what-sets-omniroute-apart) • [🤖 兼容的编程工具](#-compatible-clis--coding-agents) • [🖥️ 运行平台](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 隐私优先](#-private--local-first) • [🎬 实机演示](#-omniroute-in-action) • [📚 探索更多](#-explore-more) • [📧 支持](#-support--community)

🌐 支持 41+ 种语言

🇺🇸	🇧🇷	🇪🇸	🇫🇷	🇮🇹	🇷🇺	🇨🇳	🇹🇼	🇩🇪	🇯🇵	🇰🇷
🇹🇭	🇻🇳	🇮🇩	🇲🇾	🇵🇭	🇸🇦	🇮🇱	🇦🇿	🇺🇦	🇵🇱	🇨🇿
🇳🇱	🇧🇬	🇩🇰	🇫🇮	🇳🇴	🇸🇪	🇭🇺	🇷🇴	🇸🇰	🇵🇹

# 💰 约 1.6B 免费 Token / 月

> 手动凑各家免费额度有多痛苦 — 数十套 SDK、数十个速率限制，根本搞不清到底还剩多少。OmniRoute 将 **40+ 服务商池 / 500+ 模型**的**可核实**免费层聚合为一个真实的统一数字，并在控制台实时展示 (`/dashboard/free-tiers`)。 > > - **约 1.6B 免费 Token / 月**（稳定值） — 注册奖励加持下，首月最高约 **2.1B**。 > - **去重统计，诚实透明** — 每个共享免费池只计**一次**，标题数字不被速率上限注水。若以全天候速率上限累算会得出 ~10B 的虚假数据，我们从不发布此类数字。 > - **外加不可计数的部分** — 永久免费、无 Token 上限的服务商（SiliconFlow、Z.AI GLM-Flash、Kilo、OpenCode Zen…）以及 **$10 的 OpenRouter 充值**可解锁 **+24M/月**，二者独立列示，绝不混入标题数字。 > - **逐模型明细**、当月**已用 / 剩余**实时显示，以及每家服务商的透明**条款标注**。 ![Free-Tier Budget card (preview mockup)](../../screenshots/free-tier-budget-card.svg) > 示例预览 — 待 `/dashboard/free-tiers` 页面验证后替换为真实截图。完整统计方法（池去重、额度层级、服务商条款）：**[docs/reference/FREE_TIERS.md](../../reference/FREE_TIERS.md)**。

# 💥 我们的承诺

> 一个端点。**236 家服务商。** 编码不止步 — 让 OmniRoute 帮你选出最便宜且可用的那个。

🚫 永不触达限制 _{横跨 236 家服务商的毫秒级自动切换。配额耗尽？下一家即刻接管 — 零停机。}	💸 Token 节省高达 95% _{RTK + Caveman 级联压缩可削减 15–95% 的可压缩 Token（工具密集型会话平均约 89%）。}	🆓 零元起步 _{50+ 家服务商提供免费层，其中 11 家永久免费（Kiro、Qoder、Pollinations、LongCat…）。无需绑卡。}
🔌 所有工具一网打尽 _{16+ 款编程助手 — Claude Code、Codex、Cursor、Cline、Copilot、Antigravity — 一套配置全搞定。}	🧩 一个端点通吃 _{OpenAI ↔ Claude ↔ Gemini ↔ Responses API 无缝翻译。任意工具指向 /v1 即开即用。}	🛡️ 生产级品质 _{熔断器、TLS 指纹伪装、MCP（87 工具）、A2A、记忆系统、安全护栏、评估框架。14,965 项测试。}

# 🤔 为什么选择 OmniRoute？

> 告别在十个控制台之间疲于奔命、处理失效的 API 密钥和天降账单的日子。 | ❌ 日常痛点 | ✅ OmniRoute 如何解决 | |---|---| | 📉 每月订阅配额用不完就浪费 | **压榨订阅价值** — 追踪配额，在重置前用尽每一枚 Token | | 🛑 写到一半被限速打断 | **四层自动切换** — 订阅 → API Key → 廉价 → 免费，毫秒级接续 | | 🔥 工具输出（`git diff`、`grep`、日志）狂烧 Token | **RTK + Caveman 压缩** — 每次请求可省 15–95% 可压缩 Token | | 💸 昂贵的 API（每服务商 $20–50/月） | **成本优先路由** — 自动导向性价比最高的可用模型 | | 🧰 每款 AI 工具各有一套繁琐配置 | **一个端点、一套配置、一个控制台** | | 🌍 所在国家/地区封锁 AI | **三级代理** + TLS 指纹伪装 — 无论身在何方，AI 任你用 |

``` ┌──────────────────────────────────────────────────────────┐ │ 你的 IDE / CLI (Claude Code, Cursor, Cline…) │ └─────────────────────────┬──────────────────────────────────┘ │ http://localhost:20128/v1 ▼ ┌──────────────────────────────────────────────────────────┐ │ OmniRoute — 智能路由中枢 │ │ RTK + Caveman 压缩 · 17 种路由策略 │ │ 熔断器 · TLS 指纹伪装 · MCP · A2A · 安全护栏 │ └─────────────────────────┬──────────────────────────────────┘ ┌─────────────┬────┴────────┬─────────────┐ ▼ 第一梯队 ▼ 第二梯队 ▼ 第三梯队 ▼ 第四梯队订阅 API Key 廉价免费 Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder, Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations 配额耗尽？ ───▶ 预算触顶？ ─▶ 预算触顶？ ─▶ 永久在线 ```

# 🎯 Combo — 招牌功能

> **Combo** 是 OmniRoute **自动**路由的模型接力链路。配额耗尽、服务商宕机或成本飙升 — Combo 自动滑向下一个模型，无声无息。**正是它让 OmniRoute 坚不可摧。** 🛡️ ### ⚡ 零配置 — 只需设为 `auto` 无需预先配置 Combo。将模型 ID 设为 `auto`（或其变体），OmniRoute 会基于你已连接的服务商实时评分，自动构建虚拟 Combo： | 模型 ID | 优化目标 | |---|---| | `auto` | 🎯 均衡默认（LKGP — 沿用上次表现最好的服务商） | | `auto/coding` | 🧑‍💻 代码质量优先 | | `auto/fast` | ⚡ 最低延迟优先 | | `auto/cheap` | 💰 单位 Token 成本最低优先 | | `auto/offline` | 🔋 配额 / 限速余量最充裕优先 | | `auto/smart` | 🔭 质量优先 + 10% 探索度以发现更优模型 | ## ### 🔀 或亲手定制 — 17 种路由策略 | 目标 | 对应策略 / 组合 | |---|---| | 🥇 榨干订阅额度再用付费 | `priority` / `fill-first` | | ⚖️ 跨账号均衡负载 | `round-robin` · `weighted` · `p2c` · `least-used` | | 💸 永远选最便宜的可行模型 | `cost-optimized` · `auto/cheap` | | 🧠 模型间接力传递长上下文 | `context-relay` · `context-optimized` | | 🎲 随机 / 隐私路由 | `random` · `strict-random` | | 🧬 多模型并行 + 裁判裁决 | `fusion` | | 📊 按剩余配额余量路由 | `reset-window` · `headroom` | | 🤖 智能自动 | `auto`（9 维度评分）· `lkgp` · `reset-aware` | _{Auto-Combo 引擎基于 **9 个维度**（健康度、配额、成本、延迟、成功率、新鲜度…）逐候选打分 — 详见 [`docs/routing/AUTO-COMBO.md`](../../routing/AUTO-COMBO.md)。} ## ### 🧱 内置三层容灾 | 层级 | 作用范围 | 机制 | |---|---|---| | 🔌 **熔断器** | 整家服务商 | 停止向上游持续失败的服务商发送请求；自动探测恢复 | | 💤 **连接冷却** | 单个账号 / 密钥 | 跳过快触达速率上限的密钥，其余密钥继续服务 | | 🎯 **模型隔离** | 服务商 + 模型 | 仅隔离单一配额耗尽的模型，不影响该服务商的其他连接 | ``` Combo: "always-on" 策略: priority 1. cc/claude-opus-4-7 ← 订阅（先用满） 2. cx/gpt-5.5 ← 第二订阅 3. glm/glm-5.1 ← 廉价备选 ($0.5/1M) 4. kr/claude-sonnet-4.5 ← 免费、无限（永不断线）结论: 四层容灾 = 零停机 ``` _{📖 [Auto-Combo 引擎](../../routing/AUTO-COMBO.md) · [容灾指南](../../architecture/RESILIENCE_GUIDE.md)}

# 🏆 OmniRoute 何以脱颖而出

| 功能 | OmniRoute | 其他路由方案 | |---|---|---| | 🌐 服务商数量 | **231** | 20–100 | | 🆓 免费服务商 | **50+ （其中 11 家永久免费）** | 1–5 | | 🔀 路由策略 | **17 种**（优先级、加权、成本优先、上下文中继、融合…） | 1–3 | | 🗜️ Token 压缩 | **RTK + Caveman 级联（15–95%）** | 无 / 20–40% | | 🧰 内置 MCP 服务器 | **87 个工具、3 种传输、30 个权限域** | 少见 | | 🤝 A2A 代理协议 | **6 项技能、JSON-RPC 2.0** | 无 | | 🧠 记忆系统（FTS5 + 向量） | **原生支持** | 少见 | | 🛡️ 安全护栏（PII、注入、视觉） | **原生支持** | 少见 | | ☁️ 云代理 | **Codex、Devin、Jules** | 无 | | 🥷 TLS 指纹伪装 | **JA3/JA4 基于 wreq-js** | 无 | | 🖥️ 多平台 | **Web · 桌面 · Termux · PWA** | 仅 Web | | 🌍 国际化 | **42 种语言** | 0–4 | _{📊 与 LiteLLM、OpenRouter、Portkey 的详细对比 → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](../../comparison/OMNIROUTE_VS_ALTERNATIVES.md)}

# ✨ 近期更新

> **v3.8.20 → v3.8.41** 重点更新。完整日志见 [`CHANGELOG.md`](../../CHANGELOG.md)。 - **⚖️ Quota-Share 路由** — 专用 Combo 策略，按可用配额跨账号分配负载：Deficit-Round-Robin 调度、每连接 `max_concurrent` 配合冷却等待队列、多时间窗口用量桶（5 小时 / 7 天 / 每模型）、每 (密钥, 模型) 用量上限、会话粘性保障 Prompt 缓存完整性，以及基于上游 Token 用量头的主动饱和检测。→ [容灾指南](../../architecture/RESILIENCE_GUIDE.md) - **🤖 一键 CLI/Agent 配置** — 专用 `setup-*` 命令为各编程工具一键配置 OmniRoute 路由（Claude Code、Codex、Cline、Continue、Cursor、Roo Code、Kilo Code、Crush、Goose、Qwen Code、Aider、OpenCode）；`omniroute launch` / `omniroute launch-codex` 为零配置启动器。→ [CLI 集成](../../guides/CLI-INTEGRATIONS.md) - **🛰️ 远程模式** — 通过授权范围 Token 从任意机器操控远程 OmniRoute（`omniroute connect` / `omniroute contexts` / `omniroute tokens`）；另附 `omniroute login antigravity` 辅助命令，在你的本机运行 Google "native/desktop" OAuth 后将凭证 blob 粘贴至远程/VPS 安装实例（因远程环境无法接收 loopback 回调）。→ [远程模式](../../guides/REMOTE-MODE.md) - **🧭 更智能的自动路由** — OpenRouter 风格的 `auto/:` Combo（如 `auto/coding:fast`、`auto/reasoning:pro`）、**Fusion** 策略（并行分发至多模型面板后由裁判合成最优结果）、**任务感知路由**（按任务类型匹配最佳连接）、每请求 `X-Route-Model` 覆盖、实时 Arena-ELO + models.dev 模型智能评分、每步骤账号白名单、服务商通配符策略步骤、嵌套Combo引用执行、粘性加权选择以及 `web_search` 感知路由。→ [Auto-Combo](../../routing/AUTO-COMBO.md) - **🗜️ 可插拔压缩体系** — **9 大可组合引擎**的异步流水线，含 Compression Studios、LLMLingua-2 ONNX 引擎和启发式/SLM 双层 **Ultra**、RTK、委托式 Anthropic 上下文编辑、**输出风格**（输出轴调控：简洁文章 / 少代码 / 简洁文言）、**自适应上下文预算旋钮**（仅推进到刚好适应上下文窗口的程度）、每请求 `x-omniroute-compression` 控制、可选离线评估套件、控制台一键 **Headroom** 代理生命周期管理（支持 Docker 边车）、合成**压缩演练场**（Play 通道 + A/B 对比，附 USD 上限保真度判定）、可选**每步保真度门控**（在有损引擎降低 Prompt 质量前将其拦截）、**Best-of-N 候选编码器**（GCF vs TOON — 取更短者，Studio 中附 A/B 字节/Token 对照表）、**CCR 范围/grep/统计检索**（直接拉取储存块的精确字节/行切片或摘要而无需全量展开），以及统一面板含命名配置文件 + 活动配置文件选择器。→ [压缩](../../compression/COMPRESSION_ENGINES.md) - **🕵️ 透明 MITM 解密（TPROXY）** — 捕获并翻译忽略代理环境变量的 CLI 流量，含每 SNI 证书颁发机构和信任存储安装器。→ [MITM/TPROXY](../../security/MITM-TPROXY-DECRYPT.md) - **💸 全方位成本遥测** — 每个端点上的 `X-OmniRoute-*` 成本/用量响应头（含媒体端点）、非 Token 成本引擎、缓存命中 `X-OmniRoute-Cost-Saved` 响应头，以及每密钥美元消费配额。→ [API 参考](../../reference/API_REFERENCE.md) - **🧠 完全可控的记忆系统** — 可选 int8 向量量化（Qdrant + sqlite-vec）、默认关闭记忆、每请求 `x-omniroute-no-memory` 响应头。→ [记忆系统](../../frameworks/MEMORY.md) - **🛡️ 安全** — 所有 LLM 路由的提示注入防护（后台有红队测试套件），外加免费的 DuckDuckGo 兜底网页搜索。→ [安全护栏](../../security/GUARDRAILS.md) - **🤝 更多服务商与代理** — Cursor Cloud Agent（第四云代理）、CodeBuddy CN（`copilot.tencent.com`）、Google Flow 视频生成服务商、新网关 **DGrid** 和 **Pioneer AI**（Fastino Labs）、入站 **xAI Grok** 翻译器加 **Grok Build (xAI)**（含 OAuth 导入 Token 流程）、GitHub Copilot 服务商的 GPT-4 / GPT-4o-mini、多模型 **Factory Droid**、**ZenMux Free**（会话 Cookie 免费层）、**阿里云 DashScope** 文生视频（`wan2.7-t2v`）、刷新至 236 家服务商的目录（OrcaRouter、Wafer AI、OpenAdapter、dit.ai、TokenRouter…）、Vertex AI 媒体生成（语音/转录/音乐/视频），以及一键从 CLIProxyAPI 导入账号（`~/.cli-proxy-api/`）。→ [服务商](../../reference/PROVIDER_REFERENCE.md) - **⚡ 本地性能与基础设施** — 一键本地 Redis 启动器（`omniroute redis up`，含控制台 Redis 面板）、一键 **Cloudflare Workers** 和 **Deno Deploy** 中继部署器（接入代理池），以及可选 Bifrost Go 边车将最热中继路径卸载至 Go 侧（`BIFROST_BASE_URL`，超时自动回退 TypeScript 路径）— 现支持中继后端选择器（`OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto`），`/v1/relay` 端点保持对外稳定接口的同时内部自动择取最快后端。→ [环境配置](../../reference/ENVIRONMENT.md)

# 🤖 兼容的 CLI 与编程助手

> 一个配置 — `http://localhost:20128/v1` — 所有 AI IDE 或 CLI 都能跑在免费与低成本模型上。

Claude Code	Codex CLI	Cursor	Copilot	Continue
OpenCode	Kilo Code	Droid	OpenClaw	Kiro	Command

＋同样兼容 · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · 任意兼容 OpenAI 格式的工具

_{📖 16+ 款工具的逐项配置指南 → [`docs/reference/CLI-TOOLS.md`](../../reference/CLI-TOOLS.md) · 🧩 OpenCode 插件 → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)}

# 🌐 231 家 AI 服务商 — 50+ 家免费

> 开源路由方案中最完整的服务商目录：**236 家服务商**、**50+ 家含免费层**、**11 家永久免费**。

### 🆓 永久免费 — 零元，无需绑卡

_{GPT-5、Claude、Gemini $100 免费额度}	_{Kimi-K2、DeepSeek-R1 无限免费}	_{GPT-5、Claude、Llama 4 无需密钥}	_{LongCat-2.0 一次性 10M Token (需 KYC) 🔑}
_{50+ 模型 10K 神经元/天}	_{129 个模型 ~40 RPM 免费}	_{Qwen3 235B 1M Token/天}

📖 完整机器可读目录 → [`docs/reference/PROVIDER_REFERENCE.md`](../../reference/PROVIDER_REFERENCE.md)

# 🖥️ OmniRoute 运行平台 — 无处不在

> 同一套应用，你的机器，你的规则。从全局 `npm install` 到**你的手机**（通过 Termux），无所不跑。 | 平台 | 安装方式 | 亮点 | |---|---|---| | 📦 **npm（全局）** | `npm install -g omniroute` | 一行命令，任意 OS | | 🐳 **Docker** | `docker run … diegosouzapw/omniroute` | 多架构 **AMD64 + ARM64** | | 🖥️ **桌面（Electron）** | `npm run electron:build` | 原生窗口 + 系统托盘 — **Windows / macOS / Linux** | | 💪 **ARM** | 原生 `arm64` | 树莓派、ARM 服务器、Apple Silicon | | 📱 **Android（Termux）** | `pkg install nodejs && npx -y omniroute` | **在手机上** 7×24 运行，无需 Root | | 📲 **PWA** | "添加到主屏幕" | 全屏、离线、可从浏览器安装 | | 🧩 **OpenCode 插件** | `@omniroute/opencode-provider` | 原生 OpenCode 集成 | | 🛠️ **源码构建** | `npm install && npm run dev` | 动手改造，贡献代码 | _{📖 [Docker 指南](../../guides/DOCKER_GUIDE.md) · [桌面端](../../electron/README.md) · [Termux](../../guides/TERMUX_GUIDE.md) · [PWA](../../guides/PWA_GUIDE.md) · [OpenCode](../../frameworks/OPENCODE.md)}

# 🔒 隐私优先，数据本地

> 你的密钥、你的机器、你的数据。OmniRoute 是**本地代理** — 绝不会向外回传。 - 🏠 **100% 运行在本地硬件上** — npm、Docker、桌面端或你的手机。请求链路中不存在任何 OmniRoute 云端节点。 - 🔐 **凭据静态加密** — API 密钥与 OAuth 令牌以 **AES-256-GCM** 封存。 - 🚫 **默认零遥测** — 你的提示只发送给你选定的服务商，别无他处。 - 🛡️ **网关加固** — API 密钥权限域、IP 过滤、速率限制、提示注入防护、仅限 loopback 的进程路由。 - 📜 **MIT 协议、完全开源** — 逐行可审计，永久可自托管。 _{📖 [授权管理](../../architecture/AUTHZ_GUIDE.md) · [安全护栏](../../security/GUARDRAILS.md) · [合规体系](../../security/COMPLIANCE.md)}

# 🔌 完整 CLI + A2A 与 MCP

> OmniRoute 不只是一台服务器 — 它是拥有 **60+ 命令**的**全功能命令行驾驶舱**，外加开放的代理协议，让 AI 代理**自主**操控 OmniRoute。 ### ⌨️ 真正的 CLI（不止 `start`） ```bash omniroute # 启动网关 + 控制台（端口 20128） omniroute chat # 交互式 TUI 聊天客户端（斜杠命令：/model /combo /skill /memory） omniroute setup # 引导式首次设置向导 omniroute doctor # 诊断服务商、端口、原生依赖 ``` ### 🛰️ 远程模式 — CLI 在本地，OmniRoute 在远端的 VPS OmniRoute 跑在服务器上？用**同一套 CLI** 从笔记本远程操控。登录一次，绑定授权范围 Token；后续所有命令自动指向远端。 ```bash omniroute connect 192.168.0.15 # 密码 → 范围 Token，保存为上下文 omniroute models list # ← 在远端服务器上执行 omniroute configure codex # ← 选择远端模型，写入本地 Codex 配置文件 omniroute tokens create --name ci --scope read # 为其他机器签发更窄范围的 Token omniroute contexts use default # ← 切回本机服务器 ``` Token 权限域为 `read` / `write` / `admin`；涉及进程启动的路由仅限 loopback 执行。 _{📖 [远程模式](../../guides/REMOTE-MODE.md)}

`providers` · `oauth` · `keys` · `combo` · `nodes` · `models` · `cache` · `compression` · `cost` · `usage` · `quota` · `health` · `resilience` · `telemetry` · `logs` · `audit` · `mcp` · `a2a` · `cloud` · `memory` · `skills` · `eval` · `tunnel` · `backup` · `sync` · `webhooks` · `policy` · `pricing` · `translator` · `simulate` …

### 🤝 接入 AI 代理 — 让代理自主操控 OmniRoute 通过 **MCP** 或 **A2A** 协议暴露 OmniRoute，任何智能代理都能获得网关的完整控制权 — 路由、服务商、Combo、缓存、压缩、记忆 — 全自主运行。 | 协议 | 端点 | 用途 | |---|---|---| | 🧰 **MCP（stdio）** | `omniroute --mcp` | 接入 Claude Desktop、Cursor 等各种 MCP 客户端 | | 🌊 **MCP（HTTP）** | `http://localhost:20128/api/mcp/stream` | 远程 MCP — **87 个工具**、30 个权限域、完整审计追踪 | | 📡 **MCP（SSE）** | `http://localhost:20128/api/mcp/sse` | 流式 MCP 传输 | | 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | 代理间通信，**JSON-RPC 2.0** + SSE，6 项技能 | ```bash # 通过 MCP 将 OmniRoute 完整工具集赋予 Claude Code： claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream ``` _{📖 [MCP 服务器](../../frameworks/MCP-SERVER.md) · [A2A 服务器](../../frameworks/A2A-SERVER.md) · [代理协议](../../frameworks/AGENT_PROTOCOLS_GUIDE.md)}

# 🗜️ 自动节省 15–95% Token

> **Token 够用就好，何必铺张浪费？** 每个请求**透明地**通过 OmniRoute 压缩流水线 — 客户端无需任何改动。现已升级为 **9 大可组合引擎**的级联体系，按 Combo 自由排列组合 — 凝聚了 [RTK](https://github.com/rtk-ai/rtk)、[Caveman](https://github.com/JuliusBrussee/caveman)（⭐ 51K+）、[LLMLingua-2](https://github.com/microsoft/LLMLingua) 和 [Troglodita](https://github.com/leninejunior/troglodita)（PT-BR）的技术精华。 ### 🧱 九引擎级联体系引擎按流水线顺序执行；每个引擎均可独立启停，按 Combo 粒度配置： | # | 引擎 | 作用 | |---|---|---| | 1 | **Session-Dedup** | 剔除跨轮次重复的内容（基于内容寻址，跨轮次比对） | | 2 | **CCR** | 将大文本块归档到检索标记后，按需拉取 | | 3 | **RTK** | 智能工具输出过滤、去重与截断（理解命令语义） | | 4 | **Headroom** | 同构 JSON 数组的无损表格式压缩（~30%+） | | 5 | **Caveman** | 基于规则的叙述性文本压缩（输出端约 65–75%） | | 6 | **LLMLingua-2** | 基于 MobileBERT ONNX 的 ML 语义剪枝 — 代码安全、异步 | | 7 | **Lite** | 空白符 + 图片 URL 精简（低延迟基线） | | 8 | **Aggressive** | 摘要浓缩 + 老旧轮次渐进式老化 | | 9 | **Ultra** | 启发式 Token 剪枝 + 可选小模型（SLM）层 | 代码块、URL 和结构化数据**永远逐字节原样保留**。**一键预设**快速组合引擎： | 模式 | 节省比例 | 最佳场景 | |---|---|---| | 🪶 **Lite** | ~15% | 常驻开启的安全默认 | | 🪨 **标准（Caveman）** | ~30% | 日常编码 | | ⚡ **Aggressive** | ~50% | 长时间工具密集型会话 | | 🔥 **Ultra** | ~75% | 最大化节省 | | 🧰 **RTK** | 60–90% | Shell/测试/构建/Git 输出 | | 🔗 **级联（RTK → Caveman）** | **78–95%** | 混合提示 + 工具日志 | **真实案例 — 标准模式：** > **压缩前（69 Token）：** _"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."_ > > **压缩后（19 Token）：** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_ > > **同样的回答。节省 72% Token。精度毫无损失。** ✅ **PT-BR 案例 — [Troglodita](https://github.com/leninejunior/troglodita) 模式：** > **压缩前（42 Token）：** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_ > > **压缩后（12 Token）：** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_ > > **同样的回答。约 70% 更少 Token。技术精度完好无损。** ✅
### 📖 工作原理 — 流水线、架构与节省量计算 ``` Client (10,000 tok) ──▶ OmniRoute Compression (9 engines) ──▶ Provider (~1,080 tok, 节省高达 95%) ``` 默认级联组合为 `RTK → Caveman`。当二者作用于同一工具/上下文负载时，节省效果叠加： ```txt 组合节省率 = 1 − (1 − RTK) × (1 − Caveman_input) 平均值 = 1 − (1 − 0.80) × (1 − 0.46) = 89.2% 区间 = 78.4 – 94.6% ``` 代码块、URL、JSON 和结构化数据**始终受到**保护引擎的保全。 ### 🎚️ 引擎之外 — 输出风格、自适应旋钮与逐请求控制上述 9 大引擎负责压缩**输入**端。还有三个额外层面，分别控制**如何压**、**何时压**以及输出端的**效果**： - **🪄 输出风格** _（输出轴调控）_ — 注入确定性强、缓存友好的响应结构指令；可组合使用，每项提供 `lite` / `full` / `ultra` 三个强度档。添加风格只需一行注册代码： - **简明文章** — 剔除填充词/冠词/暧昧语；技术实质精确传达。 - **少即是多** — "经验丰富的高级开发" YAGNI 风格：最小化可用改动，不主动添加脚手架。 - **文言简雅** — 仿文言文的极致简洁风格（区域锁定至 `zh`）。 - **🎯 自适应上下文预算** _（调节旋钮）_ — 取代简单的开/关阈值，改为渐次递进：从最轻量、最无损的引擎开始，仅推进到刚好**适配目标模型上下文窗口**的程度。策略：`reserve-output`（默认，模型感知）· `percentage` · `absolute`。模式：`floor`（确保适配）· `replace-autotrigger`（你的显式选择优先）· `off`（传统阈值模式）。 - **🎛️ 压缩决策的优先链路** _（从高到低）_ — 逐请求 `x-omniroute-compression` 头 › Combo 覆写 › 活动命名配置 › 自适应/自动触发 › 面板默认 › 关闭。最终采用的压缩方案会通过 `X-OmniRoute-Compression: ; source=` 响应头回显。可依阈值自动触发、旋钮自适应调节、固定命名配置文件、逐请求一次性压缩，或为每条Combo 专属分配流水线 — 工作负载千差万别，总有一种适配。可选离线**评估套件**（`npm run eval:compression`）在固定语料集上量化评分，助你在推广变更前验证保真度与节省效果。 📖 [`COMPRESSION_GUIDE.md`](../../compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](../../compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](../../compression/COMPRESSION_ENGINES.md)

# ⚡ 快速开始

**1) 安装并运行** ```bash npm install -g omniroute omniroute ``` 控制台：`http://localhost:20128` · API：`http://localhost:20128/v1` **2) 连接免费服务商（无需注册）** 控制台 → **Providers** → 连接 **Kiro AI**（免费 Claude，约 50 积分/月/账号）或 **OpenCode Free**（无需认证）→ 完成。 **3) 配置你的编程工具** ```txt Base URL: http://localhost:20128/v1 API Key: [从控制台 → Endpoints 复制] Model: auto （零配置智能路由 — 也可指定任意服务商/模型） ``` **4) 验证链路** ```bash curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY" ``` 你应该能看到已连接模型的列表。🎉 至此大功告成 — 开始编码，OmniRoute 自动路由、自动容灾。如果你的客户端无法发送自定义请求头，OmniRoute 也提供 Token 化兼容别名： ```txt OpenAI 模型目录： http://localhost:20128/vscode/YOUR_KEY/ OpenAI 模型列表： http://localhost:20128/vscode/YOUR_KEY/models OpenAI 聊天： http://localhost:20128/vscode/YOUR_KEY/chat/completions OpenAI 响应： http://localhost:20128/vscode/YOUR_KEY/responses Ollama 聊天： http://localhost:20128/vscode/YOUR_KEY/api/chat Ollama 标签： http://localhost:20128/vscode/YOUR_KEY/api/tags ``` 仅限无法附带 `Authorization: Bearer ...` 头的客户端使用。标准请求头认证始终是推荐方式。
## 📦 更多安装方式 — Docker、源码、pnpm、Arch **🐳 Docker** ```bash docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` **🛠️ 源码构建** ```bash cp .env.example .env && npm install PORT=20128 npm run dev ``` **📦 pnpm** ```bash pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute ``` **🐧 Arch Linux（AUR）** ```bash yay -S omniroute-bin && systemctl --user enable --now omniroute.service ``` **🔧 Nix（Flake）** ```bash # 使用 Nix flakes nix develop npm run dev # 或使用 devbox devbox run npm run dev ``` 📖 [Docker 指南](../../guides/DOCKER_GUIDE.md) — Compose 配置、Caddy HTTPS、Cloudflare 隧道。 **🦭 Podman** ```bash # 1. 构建镜像 podman build --target runner-base -t omniroute:base . # 2. 修复无 Root 权限 Podman 的数据目录权限 mkdir -p data && podman unshare chown 1000:1000 ./data # 3. 在 .env 中设置运行时，然后运行（参见 contrib/podman/ 中的 Quadlet） echo "CONTAINER_HOST=podman" >> .env podman compose --profile base up -d ``` 📖 [Podman 指南](../../contrib/podman/README.md) — Quadlet 设置、podman-compose、Quadlet。

# 🎬 实机演示

🇧🇷 Português
_{Guia completo}

🇺🇸 English
_{Complete walkthrough}

🇷🇺 Русский
_{Полное руководство}

> 🎬 **制作了关于 OmniRoute 的视频？** 通过链接创建 [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) 或 [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) — 我们将在本节予以展示。

# 📚 探索更多

💰 费用一览与零元免费栈（11 家服务商）

| 层次 | 举例 | 成本 | |---|---|---| | 💳 **订阅制** | Claude Code Pro / Codex / Copilot | $10–200/月 | | 🔑 **API Key（含免费层）** | NVIDIA NIM、Cerebras、Groq | **免费** | | 💰 **廉价** | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | 几分钱 | | 🆓 **永久免费** | Kiro、Qoder、Qwen、Pollinations、LongCat | **$0** | **零元免费栈 — 合并为一条坚不可摧的 Combo：** | 服务商 | 前缀 | 免费模型 | 配额 | |---|---|---|---| | **Kiro** | `kr/` | Claude Sonnet 4.5、Haiku 4.5、Opus 4.6 | 50 积分/月 | | **Qoder** | `if/` | kimi-k2-thinking、qwen3-coder-plus、deepseek-r1 | ♾️ 无限 | | **Qwen** | `qw/` | qwen3-coder-plus/flash/next | ♾️ 无限 | | **Pollinations** | `pol/` | GPT-5、Claude、Gemini、DeepSeek、Llama 4 | 无需密钥 | | **LongCat** | `lc/` | LongCat-2.0 | 一次性 10M (需 KYC) | | **Cloudflare AI** | `cf/` | 50+ 模型 | 10K 神经元/天 | | **NVIDIA NIM** | `nvidia/` | 129 个模型 | ~40 RPM | | **Cerebras** | `cerebras/` | Qwen3 235B、GPT-OSS 120B | 1M Token/天 | > 💡 控制台上的"费用"是**节省追踪器**，而非账单 — OmniRoute 从不向你收费。显示"$290 总费用"意味着你使用免费模型**省下了 $290**。 📖 完整免费服务商目录 → [`docs/reference/FREE_TIERS.md`](../../reference/FREE_TIERS.md) — 25+ 家服务商、配额、Base URL。

🎯 实用场景 — 即拿即用的 Combo 配方

**永久零元：** ``` 1. kr/claude-sonnet-4.5 (Kiro — ~50 积分/月/账号) 2. if/kimi-k2-thinking (Qoder — 无限) 3. pol/gpt-5 (Pollinations — 无需密钥) 4. lc/LongCat-2.0 (一次性 10M 备用，需 KYC) 压缩方案: aggressive (~50%) → 免费额度翻倍 · 成本: $0/月 ``` **7×24 无中断：** 串联 2 个订阅 → 廉价 → 免费，五层容灾。 **地理封锁区：** 免费服务商 + 全局/按服务商代理 → 从任何国家访问 AI。 **最大化节省：** 订阅 + 廉价备用 + `ultra` 压缩（~75%）→ 重度用户每月节省约 $150–300。

🌍 绕过地理封锁 — 三级代理 + 隐身

🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 身处受限地区？OmniRoute 的**三级代理体系**（全局 / 按服务商 / 按连接）代理 API 请求、OAuth 流程、连通性测试、Token 刷新和模型同步。 - **协议：** HTTP/HTTPS、SOCKS5、需认证代理 - **🆓 1proxy 市场** — 数百个免费验证代理、质量评分、自动轮换 - **反检测** — TLS 指纹伪装（`wreq-js`）、CLI 指纹匹配、代理 IP 保持 📖 [`docs/ops/PROXY_GUIDE.md`](../../ops/PROXY_GUIDE.md)

✨ 完整功能清单 — 30+ 核心能力（记忆、评估、可观测性）

**路由：** 15 种策略 · 任务感知智能路由 · 思考预算控制 · 通配符路由 · 系统提示注入。 **兼容性：** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · 自动 OAuth 刷新（PKCE，8 家服务商）· 多账号轮询 · Batch + Files API · 实时 OpenAPI 3.0。 **协议：** MCP（87 工具、3 种传输、30 个权限域）· A2A（JSON-RPC 2.0、SSE、6 项技能）· ACP · 云代理（Codex、Devin、Jules）。 **插件：** 自定义插件市场（系统配置的注册 URL，带 SSRF 防护拉取）· 安装/启用/禁用 · Notion + Obsidian 知识库集成（WebDAV 文件服务器、仓库搜索、笔记 CRUD）。 **嵌入式服务：** 一键安装与生命周期管理本地边车服务（CLIProxy、NineRouter）。 **质量与运维：** 内置 **Evals** 评估框架（黄金标准集：精确匹配/包含/正则/自定义）· 安全护栏（PII 脱敏、注入防护、视觉桥接）· 健康监控面板 · p50/p95/p99 遥测 · Webhooks · 合规审计。 **AI Agent 技能：** 即插即用的 Markdown 技能清单 — 将任意代理指向 `skills/*/SKILL.md` 清单。43 项可用技能。 📖 [MCP 服务器](../../open-sse/mcp-server/README.md) · [A2A 服务器](../../src/lib/a2a/README.md) · [容灾指南](../../architecture/RESILIENCE_GUIDE.md) · [功能画廊](../../guides/FEATURES.md)

📖 环境变量、设置与常见问题

| 环境变量 | 默认值 | 用途 | |---|---|---| | `PORT` | `20128` | API + 控制台端口 | | `REQUIRE_API_KEY` | `false` | 是否要求所有请求携带 API Key | | `DATA_DIR` | `~/.omniroute` | 数据库与配置存储路径 | **OmniRoute 会向我收费吗？** 不会 — 它是运行在你本机的免费开源软件。你只直接向付费服务商付款。OmniRoute 不含任何计费系统。 **免费服务商真的无限使用吗？** 绝大多数是 — Qoder、Pollinations、LongCat 和 Cloudflare 免费且无单账号额度上限。Kiro 也是免费，但每月每账号约 50 积分封顶。在 Combo 中叠加多家免费服务商，自动容灾确保零元持续可用。 **压缩会影响输出质量吗？** 不会 — 它仅压缩**输入**端；代码、URL、JSON 永远保留不损。 **AI 服务被封锁的地区能用吗？** 能 — 三级代理 + 1proxy 市场可覆盖全部 236 家服务商。 📖 [用户指南](../../guides/USER_GUIDE.md) · [API 参考](../../reference/API_REFERENCE.md) · [环境配置](../../reference/ENVIRONMENT.md)

🐛 故障排除

| 问题 | 快速解决方案 | |---|---| | "Language model did not provide messages" | 服务商配额耗尽 → 使用 Combo 自动切换 | | 速率限制（429） | 设置容灾链路：`cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` | | OAuth Token 过期 | 自动刷新；若卡住，在 Providers 页面删除后重新认证 | | `unsupported_country_region_territory` | 在设置 → 代理中配置代理 | | Docker SQLite 锁定 | 使用 `--stop-timeout 40` 确保干净的 WAL 检查点 | | Node 运行时错误 | 使用 Node `>=22.0.0 <23` 或 `>=24.0.0 <27` | 🐛 **报告 Bug？** 运行 `npm run system-info` 并附上生成的 `system-info.txt`。📖 [`docs/guides/TROUBLESHOOTING.md`](../../guides/TROUBLESHOOTING.md)

📸 控制台截图

| 页面 | 截图 | 页面 | 截图 | |---|---|---|---| | Providers | ![Providers](../../screenshots/01-providers.png) | Combos | ![Combos](../../screenshots/02-combos.png) | | Analytics | ![Analytics](../../screenshots/03-analytics.png) | Health | ![Health](../../screenshots/04-health.png) | | Translator | ![Translator](../../screenshots/05-translator.png) | Settings | ![Settings](../../screenshots/06-settings.png) | | CLI Tools | ![CLI Tools](../../screenshots/07-cli-tools.png) | Usage Logs | ![Usage](../../screenshots/08-usage.png) |

# 📧 支持与社区 > 💬 **与社区交流** — Discord、Telegram 和 WhatsApp（🌍 / 🇧🇷）链接详见 [本 README 顶部](#-加入社区)。 - 🌍 **官网**：[omniroute.online](https://omniroute.online) - 🐙 **GitHub**：[github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - 🐛 **Issues**：[报告 Bug](https://github.com/diegosouzapw/OmniRoute/issues)（请附上 `npm run system-info` 的输出结果） - 🤝 **贡献**：参见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 或选取 `good first issue`

---

## 🛠️ 技术栈

- **运行时**：Node.js 22.x 或 24.x LTS（推荐 24 LTS）— `>=22.0.0 <23 || >=24.0.0 <27` - **语言**：TypeScript 6.0 — 跨 `src/` 和 `open-sse/` **100% TypeScript**（核心模块自 v2.0 起零 `any`） - **框架**：Next.js 16 + React 19 + Tailwind CSS 4 - **数据库**：better-sqlite3 (SQLite) + LowDB（JSON 兼容）— 域状态、代理日志、MCP 审计、路由决策、记忆、技能 - **模式校验**：Zod（MCP 工具 I/O 校验、API 合约） - **协议**：MCP（stdio/HTTP）+ A2A v0.3（JSON-RPC 2.0 + SSE） - **流式传输**：服务器推送事件（SSE）+ WebSocket 桥接（`/v1/ws`） - **认证**：OAuth 2.0（PKCE）+ JWT + API Key + MCP 权限域授权 - **测试**：Node.js 原生测试运行器 + Vitest（**14,965 个测试用例**，覆盖 517 个文件 — 单元、集成、E2E、安全、生态） - **平台**：桌面端（Electron）、Android（Termux）、PWA（任意浏览器） - **CI/CD**：GitHub Actions（Release 时自动发布至 npm + Docker Hub） - **官网**：[omniroute.online](https://omniroute.online) - **npm 包**：[npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) - **Docker**：[hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) - **容灾**：熔断器、指数退避、防惊群效应、TLS 伪装、Auto-Combo 自愈

## 📖 文档

### 📘 入门指南 | 文档 | 说明 | |---|---| | [用户指南](../../guides/USER_GUIDE.md) | 服务商、Combo、CLI 集成、部署 | | [设置指南](../../guides/SETUP_GUIDE.md) | 全安装方法、CLI 工具配置、协议设置、超时调优 | | [CLI 工具指南](../../reference/CLI-TOOLS.md) | Claude Code、Codex、Cursor、Cline、OpenClaw、Kilo、Copilot 逐工具配置 | | [远程模式](../../guides/REMOTE-MODE.md) | 通过授权范围 Token 从笔记本 CLI 操控远端 OmniRoute（VPS） | | [Claude Code 配置](../../guides/CLAUDE-CODE-CONFIGURATION.md) | 使用 `launch` + 按模型配置文件将 Claude Code 指向 OmniRoute（本地/远程） | | [快速开始](../../README.md#-quick-start) | 三步搞定：安装 → 连接 → 配置 | ### 🔧 运维与部署 | 文档 | 说明 | |---|---| | [Docker 指南](../../guides/DOCKER_GUIDE.md) | Docker 运行、Compose 配置、Caddy HTTPS、隧道、镜像标签 | | [Podman 指南](../../contrib/podman/README.md) | Quadlet systemd 集成、podman-compose、SELinux | | [虚拟机部署](../../ops/VM_DEPLOYMENT_GUIDE.md) | 完整指南：VM + nginx + Cloudflare 配置 | | [Fly.io 部署](../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) | 部署至 Fly.io，含持久化存储 | | [Termux 指南](../../guides/TERMUX_GUIDE.md) | 通过 Termux 在 Android 上运行 OmniRoute | | [PWA 指南](../../guides/PWA_GUIDE.md) | 渐进式 Web 应用安装、缓存、架构 | | [卸载指南](../../guides/UNINSTALL.md) | 所有安装方式的干净移除 | | [环境配置](../../reference/ENVIRONMENT.md) | 完整 `.env` 变量与参考 | ### 🧠 功能与架构 | 文档 | 说明 | |---|---| | [架构](../../architecture/ARCHITECTURE.md) | 系统架构、数据流与内部机制 | | [压缩指南](../../compression/COMPRESSION_GUIDE.md) | 七级选项流水线：off / lite / standard / aggressive / ultra / RTK / stacked | | [RTK 压缩](../../compression/RTK_COMPRESSION.md) | 命令输出压缩、过滤器、信任、验证、原始输出恢复 | | [压缩引擎](../../compression/COMPRESSION_ENGINES.md) | Caveman、RTK、级联流水线、控制台/API/MCP 操作界面 | | [压缩规则格式](../../compression/COMPRESSION_RULES_FORMAT.md) | Caveman 和 RTK 过滤器的 JSON 规则包 Schema | | [压缩语言包](../../compression/COMPRESSION_LANGUAGE_PACKS.md) | 语言检测与 Caveman 规则包编写 | | [容灾指南](../../architecture/RESILIENCE_GUIDE.md) | 熔断器、冷却、队列、防惊群效应、TLS 伪装 | | [Auto-Combo 引擎](../../routing/AUTO-COMBO.md) | 九维度评分、模式包、自愈 | | [代理指南](../../ops/PROXY_GUIDE.md) | 三级代理体系、1proxy 市场、注册 CRUD | | [免费服务商](../../reference/FREE_TIERS.md) | 25+ 家免费 API 服务商统一目录 | | [功能画廊](../../guides/FEATURES.md) | 带截图的控制台视觉导览 | | [代码库文档](../../architecture/CODEBASE_DOCUMENTATION.md) | 新手友好的代码库导览 | ### 🤖 协议与 API | 文档 | 说明 | |---|---| | [API 参考](../../reference/API_REFERENCE.md) | 全端点含示例 | | [OpenAPI 规范](../../openapi.yaml) | OpenAPI 3.0 规格 | | [MCP 服务器](../../open-sse/mcp-server/README.md) | 87 个 MCP 工具、IDE 配置、Python/TS/Go 客户端 | | [MCP 服务器指南](../../frameworks/MCP-SERVER.md) | MCP 安装、传输与工具参考 | | [A2A 服务器](../../src/lib/a2a/README.md) | JSON-RPC 2.0 协议、技能、流式传输、任务管理 | | [A2A 服务器指南](../../frameworks/A2A-SERVER.md) | A2A Agent Card、任务、技能与流式传输 | ### 📋 项目与质量 | 文档 | 说明 | |---|---| | [贡献指南](../../CONTRIBUTING.md) | 开发环境设置与规范 | | [更新日志](../../CHANGELOG.md) | 完整按版本发布历史 | | [安全策略](../../SECURITY.md) | 漏洞报告与安全实践 | | [i18n 指南](../../guides/I18N.md) | 40+ 语言支持、翻译流程、RTL | | [发布检查清单](../../ops/RELEASE_CHECKLIST.md) | 发布前验证步骤 | | [测试覆盖计划](../../ops/COVERAGE_PLAN.md) | 测试覆盖策略与 14,965 测试套件 |

# ⭐ 核心贡献者 > OmniRoute 由充满热情的开源社区共同塑造。以下同仁做出了卓越贡献，直接影响着项目的质量、稳定性与影响力。**衷心感谢。**

oyi77
_{🥇 190 次提交 · +72K 行}
_{分析引擎、SQL 聚合、
代理市场、测试覆盖}

Chris Staley
_{🥈 72 次提交 · +5.7K 行}
_{SSE 流加固、Responses API、
Gemini 分页、回归修复}

zenobit
_{🥉 62 次提交 · +24K 行}
_{CI/CD 流水线、33 种语言 i18n、
Void Linux 包、跨平台修复}

R.D. & Randi
_{🏅 107 次提交 · +28K 行}
_{Endpoints 页面、隧道集成、
Docker 工作流、A2A 状态、压缩 UI}

benzntech
_{🏅 20 次提交 · +7.5K 行}
_{Electron 桌面应用、自动更新、
发布构建工作流、跨平台 CI}

> 🙏 这些贡献者的功能、Bug 修复和基础设施改进，是 OmniRoute 可靠且功能丰富的**核心支柱**。每一个 Pull Request、每一个测试用例、每一个 i18n 翻译文件都意义重大。开源正是由他们这样的人建造的。

---

## 👥 贡献者

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) ### 如何贡献 1. Fork 本仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 提交更改（`git commit -m 'Add amazing feature'`） 4. 推送分支（`git push origin feature/amazing-feature`） 5. 创建 Pull Request 详见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 获取完整开发指南。 ### 发布新版本 ```bash # 创建 Release — npm 发布将自动触发 gh release create v3.8.2 --title "v3.8.2" --generate-notes ```

## 📊 Star 历史

## 🌍 StarMapper

## 🙏 致谢

OmniRoute 是站在巨人肩膀上的作品。它始于 **[9router](https://github.com/decolua/9router)** 的一个 Fork 以及 Go 项目 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** 的 TypeScript 移植 — 自此，以下每个子系统均受惠于先行者的开源成果。每一个项目都在 OmniRoute 中留下了具体印记。这是我们对所有项目的由衷感谢。🙏 > ⭐ 星标数为 2026 年 6 月数据 — 请给这些项目点颗星。 ### 🧬 渊源与网关 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[9router](https://github.com/decolua/9router)** · decolua | 17.9k | 此 Fork 所基于的原型项目 — 此处扩展了多模态 API 并完成了全面 TypeScript 重写。 | | **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 37.8k | 启发本 JavaScript/TypeScript 移植版的 Go 语言实现。 | | **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 50.8k | AI 网关，其公开定价数据集为我们提供成本同步数据，其服务商规范化模型启发了我们的路由体系。 | ### 🗜️ 上下文与 Token 压缩 — 引擎 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 74.5k | "Token 够用就好"爆款项目 — 其原始人风格哲学驱动着我们的标准压缩模式及 30+ 条填充词/凝练规则。 | | **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai | 63.6k | 高性能命令输出压缩 — 启发了我们的 RTK 引擎、JSON 过滤器 DSL、原始输出恢复及 RTK → Caveman 级联流水线。 | | **[headroom](https://github.com/chopratejas/headroom)** · chopratejas | 33.6k | 可逆上下文压缩（SmartCrusher）— 启发了我们的 `headroom` 引擎及 `ccr` 检索标记模式。 | | **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.3k | 提示压缩研究（LLMLingua / LLMLingua-2）— 启发了我们的异步、代码安全、Fail-Open 的 `llmlingua` 引擎。 | | **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 27 | JS/ONNX 移植（MobileBERT / XLM-RoBERTa），用作我们 LLMLingua 引擎的 Worker Thread 后端。 | | **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 15 | PT-BR Token 压缩 — 驱动我们的 pt-BR 语言包：针对巴西葡萄牙语语法调优的赘语消减与填充词移除。 | | **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 51.4k | "经验丰富的高级开发" YAGNI 编码技能 — 启发了我们的**少即是多**输出风格：最小化可用改动引导，减少生成代码量。 | ### 🧩 紧凑格式、Token 研究与代码感知工具 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[TOON](https://github.com/toon-format/toon)** · toon-format | 24.6k | Token 导向对象表示法 — 其列式、表头加行的数据模型塑造了我们的表格式压缩阶段。 | | **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 11 | 模式感知的"LLM 专用 JSON"表示法 — 共同启发了我们带 `[N rows]` 标记的无损同构数组压缩。 | | **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples | 409 | Brotli/SQLite 缓存 + 按会话上下文增量 — 启发了我们的 `session-dedup` 引擎。 | | **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 993 | Bash 输出压缩 + MCP 配置文件 — 启发了我们的压缩安全回退机制及 MCP 工具清单简化。 | | **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 103 | 内容感知、按文件类型输出压缩及故障感知回退 — 验证了我们的按类型分发和最低收益跳过策略。 | | **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh | 1.4k | "发现隐藏 Token" — 其卸载+可恢复句柄模式启发了我们的 CCR 卸载思路。 | | **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 1 | 会话图 + 跨轮次行去重蓝图，启发了我们的 session-dedup 设计。 | | **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas | 2 | Rust 列式 JSON + 内容寻址检索 + 跨消息去重 — 验证了我们 `headroom`/`ccr`/`session-dedup` 引擎设计及"压缩形态位置无关"的缓存稳定不变量。 | | **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs | 80 | MCP 工具 Schema/描述压缩 — 启发了我们的 MCP 工具清单基数缩减。 | | **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 182 | Aider 风格仓库地图排序 — 启发了我们的仓库地图/检索排序探索。 | | **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson | 4 | 基于 MCP 的声明式 Shell 输出缩减 — 验证了我们的声明式 Bash 输出压缩。 | | **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 6.1k | TypeScript 编译器 API 工具包 — 启发了我们基于解析器的注释移除，完整保留字符串、模板和正则字面量。 | ### 🧠 记忆与 RAG | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[Mem0](https://github.com/mem0ai/mem0)** · mem0ai | 58.9k | 通用记忆层 — 其代理即写入/读取边界模型塑造了我们的记忆架构。 | | **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.4k | 具备分层记忆的有状态代理 — 启发了我们的上下文控制与恢复（CCR）分层模型。 | | **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 1.8k | 16 种常见 RAG/LLM 失效模式的 ProblemMap 分类法 — 构成了我们故障排除指南的共享词汇。 | ### 🛰️ 流量检查、MITM 与透明代理 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** · chouzz | 46 | 编码助手 ↔ LLM 流量 MITM 拦截/分析 — 我们的流量检查器移植了其 SSE 合并、对话归一化、主机透传及密钥掩码方案。 | | **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.1k | 透明每进程代理路由 — 启发了我们崩溃安全的 MITM 拆卸、Socket 空闲超时、`/proc` 进程归因及 TPROXY 捕获。 | ### 📚 模型数据、可观测性与 UI | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[models.dev](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 5.1k | AI 模型规格、定价与能力的开放数据库 — 原生同步至我们的模型目录。 | | **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.1k | 驱动我们实时 Compression Studio 及 Combo/Routing Studio 的基于节点的图形库。 | | **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 35.1k | LangGraph Studio 的实时工作流图形可视化启发了我们 Studios 的实时级联视图。 | | **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 29.3k | 其 trace → span → generation 可观测性模型塑造了我们的 Compression Studio 瀑布图。 | | **[Kiali](https://github.com/kiali/kiali)** · Kiali | 3.6k | Istio 服务网格可观测性 — 启发了我们 Routing/Combo Studio 中的熔断器徽章和错误边界可视化。 | | **[lobe-icons](https://github.com/lobehub/lobe-icons)** · LobeHub | 2.1k | AI/LLM 品牌图标，渲染控制台中各服务商标识。 | ### 🛡️ 安全 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** · tldrsec | 708 | 一份精选的安全默认库清单，指导我们的安全技术选型（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。 | ## ❤️ 支持 OmniRoute 是免费开源项目，在公开环境中持续构建与维护。如果它帮你节省了时间或金钱，请考虑以以下方式支持开发： - ⭐ **为本仓库加颗 Star** — 这确确实实能帮我们提升可见度 - 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — 资助持续维护和新服务商接入 - 🐛 **在 [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions) 中反馈 Bug 和分享意见** ## 📄 许可证 MIT 协议 — 详见 [LICENSE](../../LICENSE)。 ---

**[⬆ 返回顶部](#-omniroute)** · 用 ❤️ 为开源 AI 社区构建。 _{OmniRoute v3.8.24 · Node ≥22.0.0 · MIT License · omniroute.online}