> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/diegosouzapw/OmniRoute) · [上游 README](https://github.com/diegosouzapw/OmniRoute/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# 🚀 OmniRoute — 免费 AI 网关 ### 永不停止编码。通过一个端点，将每个 AI 工具连接到 **237 个提供商** — **90+ 个免费**。 **将 Claude Code、Codex、Cursor、Cline、Copilot 和 Antigravity 接入免费的 Claude / GPT / Gemini。自动故障转移。**
**RTK + Caveman 压缩可节省 15–95% 的 token。永不触及上限。**
**每月约 1.6B 有文档记载的免费 token** — 配合注册赠送额度，首月最高可达 **约 2.1B** — 聚合各免费层额度，另有一群永久免费、无上限的提供商长尾，再加上前述压缩让每一份额度都走得更远。（[统计方式 →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate)）

⭐ 如果 OMNIROUTE 帮你省了钱、让工作更轻松，请为仓库点 Star。 [![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)

[![237 AI Providers](https://img.shields.io/badge/237-AI_Providers-6C5CE7?style=for-the-badge)](#-237-ai-providers--90-free) [![90+ Free](https://img.shields.io/badge/90%2B-Free_Tiers-00B894?style=for-the-badge)](#-237-ai-providers--90-free) [![1.6B Free Tokens/mo](https://img.shields.io/badge/1.6B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/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) [![17 Strategies](https://img.shields.io/badge/17-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) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) **提问、提供商技巧、路线图与支持 → [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 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) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) ![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) [**🚀 快速开始**](#-quick-start) • [**🎯 组合方案（Combos）**](#-combos--the-flagship) • [**🌐 提供商**](#-237-ai-providers--90-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ 压缩**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 官网**](https://omniroute.online)) [💥 承诺](#-the-promise) • [🤔 为何选择](#-why-omniroute) • [🏆 独特优势](#-what-sets-omniroute-apart) • [🤖 兼容的 CLI](#-compatible-clis--coding-agents) • [🖥️ 运行环境](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 隐私优先](#-private--local-first) • [🎬 实战演示](#-omniroute-in-action) • [📚 延伸阅读](#-explore-more) • [📧 支持与社区](#-support--community)

🌐 支持 42+ 种语言

# 💰 每月约 1.6B 免费 Token

> 手动堆叠免费层很痛苦 — 数十个 SDK、数十个速率限制，根本不知道自己到底有多少额度。OmniRoute 将 **40+ 个提供商池 / 500+ 个模型**的**有文档记载**的免费层聚合为一个真实数字，并在仪表板（`/dashboard/free-tiers`）上实时展示。 - **每月约 1.6B 免费 token**（稳定）— 配合注册赠送额度，**首月最高可达约 2.1B**。 - **按池去重、真实可信** — 每个共享免费池我们只**计一次**，因此标题数字不会因速率上限而被夸大，不像竞争对手动辄宣称数十亿。（若按每个速率限制 24/7 全算会达到约 10B；我们不发布那种数字。） - **另有无法纳入统计的部分** — 永久免费、无 token 上限的提供商（SiliconFlow、Z.AI GLM-Flash、Kilo、OpenCode Zen…），以及 **$10 OpenRouter 充值**可解锁 **每月 +24M**，二者单独列出，绝不夸大标题数字。 - **按模型明细**、当月**实时已用 / 剩余**额度，以及每个提供商透明的**条款标记**。 ![Free-Tier Budget card (preview mockup)](docs/screenshots/free-tier-budget-card.svg) > 预览线稿 — 待 `/dashboard/free-tiers` 页面验证后会换成真实截图。完整方法说明（池去重、额度档位、服务商条款）：**[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**。

# 💥 承诺

> 一个端点。**237 家服务商。** 永不中断开发 — 让 OmniRoute 自动选到可用且最便宜的那一个。

🚫 永不撞限 _{跨 237 家服务商在毫秒级自动回退。配额用尽？下一家立刻接手 — 零停机。}	💸 最高省 95% token _{RTK + Caveman 叠加压缩可砍掉 15–95% 的可压缩 token（工具密集会话约 89% 均值）。}	🆓 $0 起步 _{90+ 家服务商提供免费档，11 家永久免费（Kiro、Qoder、Pollinations、LongCat…）。无需绑卡。}
🔌 所有工具都能用 _{24+ 编码代理 — Claude Code、Codex、Cursor、Cline、Copilot、Antigravity — 一份配置搞定。}	🧩 一个端点 _{OpenAI ↔ Claude ↔ Gemini ↔ Responses API 互译。任意工具指向 /v1 即可开箱即用。}	🛡️ 生产级 _{熔断器、TLS 隐身、MCP（95 个工具）、A2A、记忆、护栏、评测。21,000+ 测试。}

# 🤔 为什么选 OmniRoute？

> 别再折腾 10 个控制台、失效的 API key 和突如其来的账单。 | ❌ 日常痛点 | ✅ OmniRoute 如何解决 | | ------------------------------------------------------ | ----------------------------------------------------------------------------- | | 📉 订阅配额每月白白过期 | **榨干订阅** — 跟踪配额，在重置前用尽每一个 token | | 🛑 限流让你在编码中途卡住 | **四级自动回退** — Subscription → API → Cheap → Free，毫秒级完成 | | 🔥 工具输出（`git diff`、`grep`、日志）烧掉 token | **RTK + Caveman 压缩** — 每次请求可省 15–95% 可压缩 token | | 💸 昂贵 API（每家服务商 $20–50/月） | **成本优化路由** — 自动路由到可用且最便宜的模型 | | 🧰 每个 AI 工具各有一套配置 | **一个端点、所有工具、一个控制台** | | 🌍 所在国家/地区屏蔽 AI | **三级代理** + TLS 指纹隐身 — 随时随地使用 AI |

``` ┌──────────────────────────────────────────────────────────┐ │ Your IDE / CLI (Claude Code, Cursor, Cline…) │ └─────────────────────────┬──────────────────────────────────┘ │ http://localhost:20128/v1 ▼ ┌──────────────────────────────────────────────────────────┐ │ OmniRoute — Smart Router │ │ RTK + Caveman compression · 17 routing strategies │ │ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │ └─────────────────────────┬──────────────────────────────────┘ ┌─────────────┬────┴────────┬─────────────┐ ▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4 SUBSCRIPTION API KEY CHEAP FREE Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder, Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on ```

# 🎯 Combos — 旗舰能力

> **Combo（组合）** 是 OmniRoute **自动**跨模型路由的链路。配额用尽、服务商故障或成本飙升时，combo 会静默滑向下一个模型。**这正是 OmniRoute 坚不可摧的原因。** 🛡️ ### ⚡ 零配置 — 直接使用 `auto` 无需创建 combo。将模型设为 `auto`（或其变体），OmniRoute 会根据你已连接的服务商实时打分，构建虚拟 combo： | Model ID | 优化目标 | | -------------- | -------------------------------------------------------------- | | `auto` | 🎯 均衡默认（LKGP — 粘滞到你上次的成功服务商） | | `auto/coding` | 🧑‍💻 代码生成优先的质量权重 | | `auto/fast` | ⚡ 最低延迟优先 | | `auto/cheap` | 💰 每 token 最便宜优先 | | `auto/offline` | 🔋 配额 / 限流余量最大优先 | | `auto/smart` | 🔭 质量优先 + 10% 探索，发现更好模型 | ## ### 🔀 或自建 — 17 种路由策略全部 **17** 种策略 — 可在每个 combo 步骤中混搭： | # | Strategy | 作用 | | --- | ------------------- | ---------------------------------------------------------------- | | 1 | `priority` | 按目标顺序列表 — 耗尽一个再进下一个 🥇 | | 2 | `fill-first` | 填满每个目标的配额后再切换 | | 3 | `weighted` | 按各目标权重做加权随机 | | 4 | `round-robin` | 按顺序轮询目标 | | 5 | `p2c` | 二选幂（Power-of-two-choices）随机负载均衡 | | 6 | `least-used` | 选择当前负载最低的目标 | | 7 | `random` | 均匀随机选取（去重） | | 8 | `strict-random` | 随机选取且不去重 🎲 | | 9 | `cost-optimized` | 按实时目录定价最小化每次请求 $ 💸 | | 10 | `headroom` | 选择剩余配额最多的目标 | | 11 | `reset-window` | 优先配额窗口即将重置的目标 | | 12 | `reset-aware` | 按配额重置时间排序 — 短窗口优先 📊 | | 13 | `context-relay` | 在目标间交接上下文，支撑长对话 🧠 | | 14 | `context-optimized` | 按当前上下文大小选择最合适目标 | | 15 | `lkgp` | Last-Known-Good Path — 粘滞到上次成功目标 | | 16 | `auto` | 对每条连接做 9 因子实时打分 🤖 | | 17 | `fusion` | 扇出到一组模型 + 裁判合成一个答案 🧬 | _{Auto-Combo 引擎按 **9 个因子**（健康度、配额、成本、延迟、成功率、新鲜度…）为每个候选打分 — 详见 [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)。} ## ### ⚖️ Quota-Share — 把一份订阅分给团队 ✨ 新功能 > 多个 key 打向**同一上游账号**（一份 Codex Pro 计划、一把 Kimi key、一个 GLM Coding 席位）？某个 key 的突发流量可能烧掉整段 5 小时 / 每小时配额，把其他人锁在门外。**Quota-Share** 把服务商的基于时间的配额在池内各 key 间**公平**分配 — 且是 _work-conserving_（工作守恒）的：空闲成员的份额会被借出，而不是浪费。 | 旋钮 | 控制内容 | | ------------------------ | ------------------------------------------------------------------------------- | | ⚖️ **Allocation weight** | 每个 key 在池中的份额 — 例如 `50 / 30 / 20` | | 📐 **Dimensions** | 跟踪 `%` · 请求 · token · `$`，按 **5h / 7d / per-model** 窗口 | | 🚦 **Policy** | `hard`（超出份额则阻断） · `soft`（降优先级） · `burst`（使用空闲余量） | | 🧱 **Cap** | 每个 key 的绝对上限，与模式无关 | ``` Pool "team-codex" · 1 Codex Pro account · 3 keys · 5-hour window ├─ alice weight 50 ██████████░░░░░░░░░░ ≤ 50% of the shared 5h quota ├─ bob weight 30 ██████░░░░░░░░░░░░░░ ≤ 30% └─ ci-bot weight 20 ████░░░░░░░░░░░░░░░░ ≤ 20% Generous mode (<50% pool used) → idle shares are lent out Strict mode (≥50% pool used) → each key held to its fair share ``` _{在请求离开 OmniRoute 的热路径中**提前**强制执行，支持按 (key, model) 的上限 + 会话粘性（session stickiness）以保障 prompt-cache 完整性（现支持按 combo / 全局关闭开关）。📖 [配额共享引擎 (Quota Sharing Engine)](docs/routing/QUOTA_SHARE.md)} ## ### 🧱 内置韧性（3 层独立机制） | 层级 | 作用范围 | 作用说明 | | -------------------------- | ----------------- | -------------------------------------------------------------------------- | | 🔌 **熔断器 (Circuit breaker)** | 整个提供商 | 停止反复冲击上游已故障的提供商；自动探测以恢复 | | 💤 **连接冷却 (Connection cooldown)** | 单个账号 / key | 跳过已触发限流的 key，同时其他 key 继续服务 | | 🎯 **模型锁定 (Model lockout)** | 提供商 + 模型 | 仅隔离某一个配额受限的模型，而不是整条连接 | ``` Combo: "always-on" Strategy: priority 1. cc/claude-opus-4-7 ← subscription (use it fully) 2. cx/gpt-5.5 ← second subscription 3. glm/glm-5.1 ← cheap backup ($0.5/1M) 4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails) Result: 4 layers of fallback = zero downtime ``` _{📖 [自动组合引擎 (Auto-Combo Engine)](docs/routing/AUTO-COMBO.md) · [韧性指南 (Resilience Guide)](docs/architecture/RESILIENCE_GUIDE.md)}

# 🏆 OmniRoute 的独特之处

| 特性 | OmniRoute | 其他路由器 | | -------------------------------------- | ------------------------------------------------------------------- | ------------- | | 🌐 提供商 | **237** | 20–100 | | 🆓 免费提供商 | **90+（11 个永久免费）** | 1–5 | | 🔀 路由策略 | **17**（priority、weighted、cost-optimized、context-relay、fusion…） | 1–3 | | 🗜️ Token 压缩 | **RTK + Caveman 叠加（15–95%）** | 无 / 20–40% | | 🧰 内置 MCP 服务器 | **95 个工具、3 种传输、30 个作用域** | 少见 | | 🤝 A2A agent 协议 | **6 个 skills、JSON-RPC 2.0** | 无 | | 🧠 记忆（FTS5 + 向量） | **有** | 少见 | | 🛡️ 护栏（PII、注入、视觉） | **有** | 少见 | | ☁️ 云端 agents | **Codex、Cursor、Devin、Jules** | 无 | | 🥷 TLS 指纹隐匿 | **经 wreq-js 的 JA3/JA4** | 无 | | 🖥️ 多平台 | **Web · Desktop · Termux · PWA** | 仅 Web | | 🌍 国际化 (i18n) | **42 种语言区域** | 0–4 | _{📊 与 LiteLLM、OpenRouter 及 Portkey 的详细对比 → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)}

# ✨ 最新动态

> **v3.8.20 → v3.8.45** 的近期亮点。完整历史见 [`CHANGELOG.md`](CHANGELOG.md)。 - **🗜️ 压缩加固** — 默认开启的 **膨胀防护 (inflation guard)**（一旦压缩会让 prompt _变长_，则丢弃叠加结果并发送原文）、完善的德语 / 法语 / 日语 **Caveman 规则包**（dedup + ultra），以及新的 **中文（文言 / wényán）输入包**（含 zh-vs-ja 自动检测），还有针对 Gradle 与 .NET（`dotnet`）构建输出的 **RTK 过滤器**。→ [压缩 (Compression)](docs/compression/COMPRESSION_ENGINES.md) - **💸 诚实的包月成本** — 订阅 / coding-plan 类提供商（ChatGPT Web、grok-web、Minimax / Kimi / GLM / Alibaba Coding plans、Xiaomi MiMo…）在成本分析中现显示为 **$0**，而不再使用偏高的按 token 估算；预算 / 配额 / 路由的估算逻辑保持不变。→ [API 参考 (API Reference)](docs/reference/API_REFERENCE.md) - **⚖️ 配额共享路由 (Quota-Share routing)** — 专用 combo 策略，按_可用配额_在账号间分摊负载：Deficit-Round-Robin 调度、带冷却等待队列的按连接 `max_concurrent`、多窗口用量桶（5h / 7d / 按模型）、按 (key, model) 上限、为保障 prompt-cache 完整性的会话粘性（现支持按 combo / 全局关闭开关），以及基于上游 token 用量响应头的主动饱和处理。→ [韧性指南 (Resilience Guide)](docs/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 集成 (CLI Integrations)](docs/guides/CLI-INTEGRATIONS.md) - **🛰️ 远程模式 (Remote mode)** — 可用作用域访问令牌（`omniroute connect` / `omniroute contexts` / `omniroute tokens`）从任意机器驱动远程 OmniRoute，并提供 `omniroute login antigravity` 助手：在本机完成 Google「native/desktop」OAuth，再将凭证 blob 粘贴到远程/VPS 安装（环回重定向不可达的场景）。→ [远程模式 (Remote Mode)](docs/guides/REMOTE-MODE.md) - **🧭 更智能的自动路由** — OpenRouter 风格的 `auto/:` combos（例如 `auto/coding:fast`、`auto/reasoning:pro`）、**Fusion** 策略（并行扇出到一组模型，再由 judge 合成）、**任务感知路由**（按任务类型选择最合适连接）、按请求的 `X-Route-Model` 覆盖、实时 Arena-ELO + models.dev 模型情报、按步骤的账号白名单、提供商通配符 combo 步骤、嵌套 combo-ref 执行、粘性加权选择、感知 `web_search` 的路由，以及 **按请求的 Auto-Combo 控制**（`X-OmniRoute-Mode` 模式预设覆盖 + `X-OmniRoute-Budget` 硬性 USD 成本上限，作用域为单次请求）。→ [Auto-Combo](docs/routing/AUTO-COMBO.md) - **🗜️ 可插拔压缩** — 由 **10 个可组合引擎**构成的异步管线，含 Compression Studios、LLMLingua-2 ONNX 引擎与启发式/SLM 双层 **Ultra**、RTK、委托式 Anthropic Context Editing、**Output Styles**（输出轴引导：terse-prose / less-code / terse-CJK）、**自适应上下文预算旋钮**（仅在装入上下文窗口所需范围内逐步升级）、按请求的 `x-omniroute-compression` 控制、可选离线评估工具、从仪表盘一键管理 **Headroom** 代理生命周期（支持 Docker sidecar）、合成 **压缩 playground**（Play lanes + 带 USD 上限保真裁决的 A/B Compare）、可选 **按步骤保真门控**（在有损引擎劣化 prompt 前拒绝）、**best-of-N 候选编码器**（GCF vs TOON — 保留更短者，并在 studio 中提供 A/B 字节/token 表）、**CCR ranged/grep/stats 检索**（拉取已存块的精确字节/行切片或摘要，而无需重新展开）、带命名配置与活动配置选择器的统一面板、可选 **按引擎管线熔断器**、可选 **LLM-tier 引擎**（模型 pass，用于更高比率语义压缩）、会折叠被覆盖文件读取的 **read-lifecycle 引擎**、**usage-observed prefix freeze**、分级的 **CCR retrieval-feedback ramp**、`preserveSystemPrompt` 模式枚举，以及 studio 中的 **拖拽重排管线编辑器**。→ [压缩 (Compression)](docs/compression/COMPRESSION_ENGINES.md) - **🕵️ 透明 MITM 解密 (TPROXY)** — 捕获并转换忽略代理环境变量的 CLI 流量，支持按 SNI 的证书颁发机构与信任库安装器。→ [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md) - **💸 无处不在的成本遥测** — 每个端点（含媒体）上的 `X-OmniRoute-*` 成本/用量响应头、非 token 成本引擎、缓存命中 `X-OmniRoute-Cost-Saved` 响应头，以及按 key 的 USD 花费配额。→ [API 参考 (API Reference)](docs/reference/API_REFERENCE.md) - **🧠 由你掌控的记忆** — 可选 int8 向量量化（Qdrant + sqlite-vec）、可选 **类型化记忆衰减**（低价值旧记忆按类型计划淡出）、记忆默认关闭，以及按请求的 `x-omniroute-no-memory` 响应头。→ [记忆 (Memory)](docs/frameworks/MEMORY.md) - **🛡️ 安全** — 覆盖每条 LLM 路由的提示注入防护（由红队套件支撑），以及作为最后手段的免费 DuckDuckGo 网页搜索。→ [护栏 (Guardrails)](docs/security/GUARDRAILS.md) - **🖼️ 新端点** — `/v1/ocr`（Mistral OCR）与 `/v1/audio/translations`（Whisper 风格音频翻译）补全媒体 API 面。→ [API 参考 (API Reference)](docs/reference/API_REFERENCE.md) - **🌍 部署与运维** — 反向代理 `basePath` 部署（`OMNIROUTE_BASE_PATH`，例如在 `/omniroute/` 下提供 OmniRoute）、首次访问时按浏览器语言自动检测、按 API key 的设备/连接跟踪（IP+UA 指纹，脱敏，仅内存）、面向用户命名空间容器的无 root MITM 证书信任（`OMNIROUTE_NO_SUDO`），以及 Free Provider Rankings 页面上的服务端“仅已配置 / 仅可用”过滤器。→ [环境变量 (Environment)](docs/reference/ENVIRONMENT.md) - **🤝 更多提供商与 agents** — Cursor Cloud Agent（第 4 个云端 agent）、CodeBuddy CN（`copilot.tencent.com`）、Google Flow 视频生成提供商、新网关 **DGrid** 与 **Pioneer AI**（Fastino Labs）、入站 **xAI Grok** 转换器以及带 OAuth 导入令牌流程的 **Grok Build (xAI)**、GitHub Copilot 提供商上的 GPT-4 / GPT-4o-mini、多模型 **Factory Droid**、**ZenMux Free**（session-cookie 免费档）、**Alibaba DashScope** 文生视频（`wan2.7-t2v`）、刷新后的 237 提供商目录（OrcaRouter、Wafer AI、OpenAdapter、dit.ai、TokenRouter…）、Vertex AI 媒体生成（语音/转写/音乐/视频）、一等公民 **Ollama** 本地提供商卡片、**SenseNova** 免费 Token Plan（chat + 文生图）、从 CLIProxyAPI 一键导入账号（`~/.cli-proxy-api/`）、端到端接入 **Claude Sonnet 5**、新一波提供商（**Kenari**、**SumoPod**、**X5Lab**、**Charm Hyper**、**Nube.sh**、**b.ai**、**Qiniu**、**ModelScope**、**Augment/Auggie CLI**、**ClinePass**、NVIDIA NIM 图像生成）、从原始 ChatGPT access token 导入 Codex 账号、**Requesty** 网关（BYOK，约 200 次免费请求/天）、作为 cookie-session 提供商的 **Yuanbao (web)**（DeepSeek V3/R1 + Hunyuan）、**Zed** 托管 LLM 聚合器（OAuth）、Claude Web 提供商上的 **Claude 5 Sonnet**、Kiro 的 **adaptive-thinking reasoning** 以 `reasoning_content` 暴露，以及 **Cloudflare Workers AI 的批量 API-key 添加**。→ [提供商 (Providers)](docs/reference/PROVIDER_REFERENCE.md) - **⚡ 本地性能与基础设施** — 一键本地 Redis 启动器（`omniroute redis up`，以及仪表盘 Redis 面板）、接入代理池的一键 **Cloudflare Workers** 与 **Deno Deploy** relay 部署器、relay 后端选择器（`OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto`），使 `/v1/relay` 保持稳定对外表面、内部选择最快后端，**Bifrost**（Go AI 网关）与 **Mux**（agent 编排守护进程）提升为与 9Router/CLIProxyAPI 并列的一等嵌入式/受管服务，以及在免费代理提供商框架中新增付费第四源 **Webshare**。→ [嵌入式服务 (Embedded Services)](docs/frameworks/EMBEDDED-SERVICES.md)

# 🤖 兼容 CLI 与编程智能体（Coding Agents） > 一份配置 — `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 兼容工具

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

# 🌐 237 家 AI 提供商 — 90+ 免费

> 开源路由器中最完整的目录：**237 家提供商**、**90+ 提供免费套餐**、**11 家永久免费**。

### 🏢 各家主流实验室 — 通过一个端点

_OpenAI	_Anthropic	_Gemini	_{xAI Grok}	_DeepSeek	_Mistral
_Qwen	_{Meta Llama}	_Groq	_NVIDIA	_MiniMax	_Cohere
_Perplexity	_HuggingFace	_Together	_Fireworks	_Cloudflare	_Baidu

_{…以及另外 220+ 家 — 每个图标均从仪表板的提供商目录实时解析。📖 [提供商参考](docs/reference/PROVIDER_REFERENCE.md)}
### 🆓 永久免费 — $0，无需绑卡

AgentRouter _{GPT-5, Claude, Gemini $100 免费额度}	Qoder AI _{Kimi-K2, DeepSeek-R1 Unlimited FREE}	Pollinations _{GPT-5, Claude, Llama 4 无需 API Key}	LongCat _{LongCat-2.0 一次性 10M tokens（KYC）🔑}
Cloudflare AI _{50+ models 10K neurons/day}	NVIDIA NIM _{129 models ~40 RPM free}	Cerebras _{Qwen3 235B 1M tokens/day}

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

# 🖥️ OmniRoute 可在任何地方运行

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

# 🔒 私有且本地优先

> 你的密钥，你的机器，你的数据。OmniRoute 是一款 **本地代理（local proxy）** —— 从不回传数据。 - 🏠 **100% 在你的硬件上运行** —— npm、Docker、桌面端或你的手机。请求路径中没有 OmniRoute 云端。 - 🔐 **凭据静态加密** —— API 密钥与 OAuth 令牌使用 **AES-256-GCM** 密封存储。 - 🚫 **默认零遥测** —— 你的提示词仅发往 _你_ 选择的提供商，别无他处。 - 🛡️ **加固网关** —— API 密钥作用域、IP 过滤、速率限制、提示词注入防护、仅限回环地址的进程路由。 - 📜 **MIT 许可且完全开源** —— 审计每一行代码，永久自托管。 _{📖 [授权](docs/architecture/AUTHZ_GUIDE.md) · [防护栏](docs/security/GUARDRAILS.md) · [合规](docs/security/COMPLIANCE.md)}

# 🔌 完整 CLI + A2A 与 MCP

> OmniRoute 不仅是服务器 —— 它还是带 **80+ 条命令** 的 **完整命令行驾驶舱（cockpit）**，并开放智能体协议，让 AI 智能体能够 **自主驱动** OmniRoute。 ### ⌨️ 真正的 CLI（不只是 `start`） ```bash omniroute # serve gateway + dashboard (port 20128) omniroute chat # interactive TUI chat client (slash: /model /combo /skill /memory) omniroute setup # guided first-run wizard omniroute doctor # diagnose providers, ports, native deps ``` ### 🛰️ 远程模式 —— 在此运行 CLI，OmniRoute 在 VPS 上 OmniRoute 在服务器上？用 **同一套 CLI** 从笔记本远程操控。使用作用域访问令牌登录一次；此后每条命令都指向远程实例。 ```bash omniroute connect 192.168.0.15 # password → scoped token, saved as a context omniroute models list # ← runs against the REMOTE server omniroute configure codex # ← picks a remote model, writes a local Codex profile omniroute tokens create --name ci --scope read # mint narrower tokens for other machines omniroute contexts use default # ← switch back to the local server ``` 令牌按作用域划分：`read` / `write` / `admin`；会派生进程的路由仅限回环地址。 _{📖 [远程模式](docs/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` …

### 🤝 连接智能体 —— 由它自主控制 OmniRoute 通过 **MCP** 或 **A2A** 暴露 OmniRoute，任何有能力的智能体都能自主掌控整个网关 —— 路由、提供商、组合、缓存、压缩、记忆。 | 协议 | 端点 | 适用场景 | | ------------------ | ----------------------------------------------- | ------------------------------------------------------ | | 🧰 **MCP (stdio)** | `omniroute --mcp` | 接入 Claude Desktop、Cursor 及任意 MCP 客户端 | | 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | 远程 MCP —— **95 个工具**、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 # Give Claude Code the full OmniRoute toolset over MCP: claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream ``` _{📖 [MCP 服务器](docs/frameworks/MCP-SERVER.md) · [A2A 服务器](docs/frameworks/A2A-SERVER.md) · [智能体协议](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)}

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

> **何必多用 Token，少用就能搞定？** 每个请求都会 **透明地** 经过 OmniRoute 的压缩流水线 —— 无需修改客户端。它现已发展为 **10 个可组合引擎** 的栈，按顺序运行，并可根据路由组合灵活混搭 —— 借鉴了 [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 78K+)、[LLMLingua-2](https://github.com/microsoft/LLMLingua), 和 [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR) 的思路。 ### 🧱 10 引擎栈引擎按流水线顺序运行；每个引擎均可独立开关，并按组合单独配置： | # | 引擎 | 作用 | | --- | ----------------- | ------------------------------------------------------------------- | | 1 | **Session-Dedup** | 剔除跨轮次重复内容（按内容寻址，跨轮次） | | 2 | **CCR** | 将大块内容归档至检索标记之后，按需获取 | | 3 | **RTK** | 智能工具结果过滤、去重与截断（感知命令） | | 4 | **Headroom** | 对同质 JSON 数组进行无损表格式压缩（约 30%+） | | 5 | **Relevance** | 针对最近一次用户查询进行抽取式句子评分 | | 6 | **Caveman** | 基于规则的散文压缩（输出约 65–75%） | | 7 | **LLMLingua-2** | 通过 MobileBERT ONNX 进行 ML 语义剪枝 —— 代码安全、异步 | | 8 | **Lite** | 空白符与图片 URL 裁剪（低延迟基线） | | 9 | **Aggressive** | 摘要化 + 旧轮次渐进式老化 | | 10 | **Ultra** | 启发式 Token 剪枝，可选小模型（SLM）层级 | 代码块、URL 与结构化数据 **始终按字节级精确保留**。**一键预设** 可组合这些引擎： | 模式 | 节省幅度 | 最适合 | | ------------------------------ | ---------- | --------------------------- | | 🪶 **Lite** | ~15% | 始终开启的安全默认 | | 🪨 **Standard (Caveman)** | ~30% | 日常编码 | | ⚡ **Aggressive** | ~50% | 长时、工具密集型会话 | | 🔥 **Ultra** | ~75% | 最大节省 | | 🧰 **RTK** | 60–90% | Shell/测试/构建/Git 输出 | | 🔗 **Stacked (RTK → Caveman)** | **78–95%** | 混合提示词 + 工具日志 | **真实示例 — 标准模式（Standard mode）：** > **压缩前（69 tokens）：** _"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 tokens）：** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_ > > **答案相同。Token 减少 72%。零精度损失。** ✅ **PT-BR 示例 — [Troglodita](https://github.com/leninejunior/troglodita) 模式：** > **Antes (42 tokens):** _"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."_ > > **Depois (12 tokens):** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_ > > **Mesma resposta. ~70% menos tokens. Precisão técnica intacta.** ✅
### 📖 工作原理 — 流水线、架构与节省计算 ``` Client (10,000 tok) ──▶ OmniRoute Compression (10 engines) ──▶ Provider (~1,080 tok, up to 95% saved) ``` 默认堆叠组合会运行 `RTK → Caveman`。当两者作用于同一工具/上下文载荷时，节省效果会叠加： ```txt combined = 1 − (1 − RTK) × (1 − Caveman_input) average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2% range = 78.4 – 94.6% ``` 代码块、URL、JSON 与结构化数据**始终**由保留引擎（preservation engine）保护。 ### 🎚️ 超越引擎 — 输出风格、自适应拨盘与按请求控制上述 10 个引擎压缩的是**输入**。另外三层决定**如何**、**何时**以及**输出什么**： - **🪄 输出风格（Output Styles）** _(输出轴引导)_ — 注入确定性、可缓存的响应塑形指令；可组合，各自强度为 `lite` / `full` / `ultra`。添加一种风格只需一行注册表项： - **简洁散文（Terse prose）** — 去掉废话/冠词/含糊其辞；技术实质保持精确。 - **更少代码（Less code）** — “懒惰资深开发者” YAGNI：最小可用改动，不搭未请求的脚手架。 - **简洁文言（Terse CJK / 文言）** — 文言文极简风格（按区域限制为 `zh`）。 - **🎯 自适应上下文预算（Adaptive context-budget）** _(拨盘)_ — 不再用单一开/关 token 阈值，而是按需逐级启用最便宜、损失最小的引擎，直至**适配模型的上下文窗口**。策略：`reserve-output`（默认，模型感知）· `percentage` · `absolute`。模式：`floor`（保证适配）· `replace-autotrigger`（你的显式选择优先）· `off`（旧版阈值）。 - **🎛️ 压缩决策位置** _(优先级，高 → 低)_ — 按请求 `x-omniroute-compression` 请求头 › 路由组合覆盖 › 当前命名配置 › 自适应/自动触发 › 面板默认 › 关闭。应用方案会在 `X-OmniRoute-Compression: ; source=` 响应头中回显。按 token 阈值自动触发、拨动自适应拨盘、固定命名配置、设置一次性按请求选项，或为路由组合分配流水线 — 任选适合工作负载的方式。可选的离线**评估工具（eval harness）**（`npm run eval:compression`）会在你推广变更前，对固定语料库评估保真度与节省效果。 📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/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: [copy from Dashboard → Endpoints] Model: auto (zero-config smart routing — or any provider/model) ``` **4) 验证是否生效** ```bash curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY" ``` 你应能看到已连接的模型列表。🎉 就这样 — 开始编码，OmniRoute 会为你自动路由与回退。若客户端无法发送自定义请求头，OmniRoute 也提供带 token 的兼容别名： ```txt OpenAI catalog: http://localhost:20128/vscode/YOUR_KEY/ OpenAI models: http://localhost:20128/vscode/YOUR_KEY/models OpenAI chat: http://localhost:20128/vscode/YOUR_KEY/chat/completions OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses Ollama chat: http://localhost:20128/vscode/YOUR_KEY/api/chat Ollama tags: 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 # Using Nix flakes nix develop npm run dev # Or using devbox devbox run npm run dev ``` 📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) — Compose 配置、Caddy HTTPS、Cloudflare 隧道。 **🦭 Podman** ```bash # 1. Build the image podman build --target runner-base -t omniroute:base . # 2. Fix data directory permissions for rootless Podman mkdir -p data && podman unshare chown 1000:1000 ./data # 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet) echo "CONTAINER_HOST=podman" >> .env podman compose --profile base up -d ``` 📖 [Podman Guide](contrib/podman/README.md) — Quadlet 设置、podman-compose、Quadlet。 **⚡ 更快/更精简的安装（跳过原生构建）** 原生 SQLite 引擎（`better-sqlite3`）是**可选**依赖，因此全局安装不会因从源码编译而阻塞：当你的平台/Node 有匹配项时使用预编译二进制，否则透明回退到纯 JS 引擎（Node 22+ 为 `node:sqlite`，否则为捆绑的 `sql.js` WASM）— 无需构建工具。若要完全跳过安装后原生预热（CI、无头环境或慢机器）： ```bash OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 also skips it ``` 最快安装请优先使用 **pnpm**（内容寻址存储 + 硬链接 — 见上文）。若要无仪表板的无头运行时，请使用 Docker `base` 配置（上文）或 [Termux guide](docs/guides/TERMUX_GUIDE.md)。CLI 与 Web 仪表板由同一进程在同一端口提供，因此目前没有单独的仅 CLI 包。

# 🎬 OmniRoute 实战

🇧🇷 Português
_{Guia completo}

🇺🇸 English
_{Complete walkthrough}

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

> 🎬 **制作了 OmniRoute 相关视频？** 提交 [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) 或 [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) 并附上链接 — 我们会在此展示。

# 📚 探索更多

💰 定价一览与 $0 免费技术栈（11 家提供商）

| 层级 | 示例 | 费用 | | --------------------------- | ---------------------------------------- | ---------- | | 💳 **订阅** | Claude Code Pro / Codex / Copilot | $10–200/mo | | 🔑 **API Key（免费层级）** | NVIDIA NIM, Cerebras, Groq | **FREE** | | 💰 **低价** | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | pennies | | 🆓 **永久免费** | Kiro, Qoder, Qwen, Pollinations, LongCat | **$0** | **$0 免费技术栈 — 组合成牢不可破的一体化方案：** | 提供商 | 前缀 | 免费模型 | 配额 | | ----------------- | ----------- | ----------------------------------------------- | ------------------ | | **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 credits/mo | | **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 | ♾️ Unlimited | | **Qwen** | `qw/` | qwen3-coder-plus/flash/next | ♾️ Unlimited | | **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | No key needed | | **LongCat** | `lc/` | LongCat-2.0 | 10M one-time (KYC) | | **Cloudflare AI** | `cf/` | 50+ models | 10K neurons/day | | **NVIDIA NIM** | `nvidia/` | 129 models | ~40 RPM | | **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B | 1M tok/day | > 💡 仪表板中的「cost」是**节省追踪器**，而非账单 — OmniRoute 从不向你收费。使用免费模型时显示的「$290 total cost」意味着**节省了 $290**。 📖 完整免费目录 → [`docs/reference/FREE_TIERS.md`](docs/reference/FREE_TIERS.md) — 25+ 家提供商、配额、base URL。

🎯 使用场景 — 现成组合方案手册

**永久 $0：** ``` 1. kr/claude-sonnet-4.5 (Kiro — ~50 credits/mo per acct) 2. if/kimi-k2-thinking (Qoder — unlimited) 3. pol/gpt-5 (Pollinations — no key) 4. lc/LongCat-2.0 (10M one-time backup, KYC) Compression: aggressive (~50%) → double your free quota · Cost: $0/mo ``` **7×24 不间断：** 串联 2 个订阅 → 低价 → 免费，形成 5 层回退。 **受限地区：** 免费提供商 + 全局/按提供商代理 → 从任何国家访问 AI。 **最大节省：** 订阅 + 低价备份 + `ultra` 压缩（约 75%）→ 重度用户每月可节省约 $150–300。

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

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

✨ 完整功能列表 — 30+ 项能力（memory、evals、observability）

**路由：** 17 种策略 · 任务感知智能路由 · thinking budget 控制 · 通配符路由 · system prompt 注入。 **兼容性：** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · 自动 OAuth 刷新（PKCE，8 家提供商）· 多账号轮询 · Batch + Files API · 实时 OpenAPI 3.0。 **协议：** MCP（95 个工具，3 种传输，30 个 scope）· A2A（JSON-RPC 2.0、SSE、6 项 skill）· ACP · 云端 agent（Codex、Cursor、Devin、Jules）。 **插件：** 自定义插件市场（系统配置的 registry URL，带 SSRF 防护的 fetch）· 安装 / 启用 / 禁用 · Notion + Obsidian 知识库集成（WebDAV 文件服务器、vault 搜索、笔记 CRUD）。 **嵌入式服务：** 一键安装与本地 sidecar 服务（CLIProxy、NineRouter）的生命周期管理。 **质量与运维：** 内置 **Evals**（golden-set：exact/contains/regex/custom）· guardrails（PII、注入、vision）· 健康仪表板 · p50/p95/p99 遥测 · webhooks · 合规审计。 **AI Agent Skills：** 即插即用的 Markdown manifest — 将任意 agent 指向 `skills/*/SKILL.md` manifest。43 项 skill 可用。 📖 [MCP Server](open-sse/mcp-server/README.md) · [A2A Server](src/lib/a2a/README.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) · [Features Gallery](docs/guides/FEATURES.md)

📖 安装、环境变量与常见问题

| 环境变量 | 默认值 | 用途 | | ----------------- | -------------- | -------------------------------- | | `PORT` | `20128` | API 与仪表板端口 | | `REQUIRE_API_KEY` | `false` | 要求所有请求携带 API key | | `DATA_DIR` | `~/.omniroute` | 数据库与配置存储 | **OmniRoute 会向我收费吗？** 不会 — 它是运行在你本机上的免费开源软件。你只需直接向付费提供商付款。OmniRoute 没有计费系统。 **免费提供商真的无限吗？** 大体如此 — Qoder、Pollinations、LongCat 和 Cloudflare 免费且无单账号 credit 上限。Kiro 也免费，但每个账号约 50 credits/月上限。在组合中堆叠多个免费提供商，自动回退可让你以 $0 持续服务。 **压缩会降低质量吗？** 不会 — 它仅压缩**输入**；代码、URL、JSON 始终受保护。 **在 AI 受限地区能用吗？** 可以 — 三级代理 + 1proxy 市场可覆盖全部 237 家提供商。 📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md)

🐛 故障排查

| 问题 | 快速修复 | | ----------------------------------------- | ------------------------------------------------------------- | | "Language model did not provide messages" | 提供商配额耗尽 → 使用组合回退 | | Rate limiting (429) | 添加回退：`cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` | | OAuth token expired | 自动刷新；若卡住，在 Providers 中删除并重新认证 | | `unsupported_country_region_territory` | 在 Settings → Proxy 中配置代理 | | Docker SQLite locks | 使用 `--stop-timeout 40` 进行干净的 WAL checkpoint | | Node runtime errors | 使用 Node `>=22.0.0 <23` 或 `>=24.0.0 <27` | 🐛 **报告 bug？** 运行 `npm run system-info` 并附上 `system-info.txt`。📖 [`docs/guides/TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md)

📸 仪表板截图

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

# 📧 支持与社区 > 💬 **与社区交流** — Discord、Telegram 和 WhatsApp（🌍 / 🇧🇷）链接见 [本 README 顶部](#-join-the-community)。 - 🌍 **网站**: [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`

---

## 🛠️ 技术栈

- **Runtime（运行时）**: Node.js 22.x 或 24.x LTS（推荐 24 LTS）— `>=22.0.0 <23 || >=24.0.0 <27` - **Language（语言）**: TypeScript 6.0 — 在 `src/` 与 `open-sse/` 中实现 **100% TypeScript**（自 v2.0 起，核心模块中 `any` 为零） - **Framework（框架）**: Next.js 16 + React 19 + Tailwind CSS 4 - **Database（数据库）**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — 领域状态、代理日志、MCP 审计、路由决策、记忆、技能 - **Schemas（模式）**: Zod（MCP 工具 I/O 校验、API 契约） - **Protocols（协议）**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) - **Streaming（流式传输）**: Server-Sent Events (SSE) + WebSocket bridge（`/v1/ws`） - **Auth（认证）**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization - **Testing（测试）**: Node.js test runner + Vitest（跨 2,586 个文件共 **21,000+ 测试用例** — 单元、集成、E2E、安全、生态） - **Platforms（平台）**: Desktop (Electron)、Android (Termux)、PWA（任意浏览器） - **CI/CD**: GitHub Actions（发布时自动 npm publish + Docker Hub） - **Website（网站）**: [omniroute.online](https://omniroute.online) - **Package（包）**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) - **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) - **Resilience（韧性）**: Circuit breaker、指数退避、防惊群（anti-thundering herd）、TLS spoofing、auto-combo 自愈

## 📖 文档

### 📘 入门指南 | Document | Description | | -------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [User Guide](docs/guides/USER_GUIDE.md) | 提供商、组合（combo）、CLI 集成、部署 | | [Setup Guide](docs/guides/SETUP_GUIDE.md) | 完整安装方式、CLI 工具配置、协议设置、超时调优 | | [CLI Tools Guide](docs/reference/CLI-TOOLS.md) | Claude Code、Codex、Cursor、Cline、OpenClaw、Kilo、Copilot 各工具配置 | | [Remote Mode](docs/guides/REMOTE-MODE.md) | 通过作用域访问令牌，从笔记本 CLI 远程驱动 OmniRoute（VPS） | | [Claude Code Config](docs/guides/CLAUDE-CODE-CONFIGURATION.md) | 将 Claude Code 指向 OmniRoute（本地/远程），配合 `launch` 及按模型配置 | | [Quick Start](README.md#-quick-start) | 3 步：安装 → 连接 → 配置 | ### 🔧 运维与部署 | Document | Description | | -------------------------------------------------------- | -------------------------------------------------------------- | | [Docker Guide](docs/guides/DOCKER_GUIDE.md) | Docker run、Compose profiles、Caddy HTTPS、tunnels、镜像标签 | | [Podman Guide](contrib/podman/README.md) | Quadlet systemd 集成、podman-compose、SELinux | | [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | 完整指南：VM + nginx + Cloudflare 配置 | | [Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | 部署到 Fly.io 并配置持久化存储 | | [Termux Guide](docs/guides/TERMUX_GUIDE.md) | 通过 Termux 在 Android 上运行 OmniRoute | | [PWA Guide](docs/guides/PWA_GUIDE.md) | 渐进式 Web 应用安装、缓存、架构 | | [Uninstall Guide](docs/guides/UNINSTALL.md) | 各安装方式的彻底卸载 | | [Environment Config](docs/reference/ENVIRONMENT.md) | 完整的 `.env` 变量与参考说明 | ### 🧠 功能与架构 | Document | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | [Architecture](docs/architecture/ARCHITECTURE.md) | 系统架构、数据流与内部实现 | | [Compression Guide](docs/compression/COMPRESSION_GUIDE.md) | 7 档流水线：off / lite / standard / aggressive / ultra / RTK / stacked | | [RTK Compression](docs/compression/RTK_COMPRESSION.md) | 命令输出压缩、过滤器、信任、校验、原始输出恢复 | | [Compression Engines](docs/compression/COMPRESSION_ENGINES.md) | Caveman、RTK、stacked 流水线，以及 dashboard/API/MCP 界面 | | [Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md) | Caveman 与 RTK 过滤器的 JSON 规则包模式 | | [Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md) | 语言检测与 Caveman 规则包编写 | | [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) | 熔断器、冷却、队列、防惊群、TLS spoofing | | [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 9 因子评分、模式包、自愈 | | [Proxy Guide](docs/ops/PROXY_GUIDE.md) | 三级代理系统、1proxy 市场、registry CRUD | | [Free Tiers](docs/reference/FREE_TIERS.md) | 25+ 免费 API 提供商汇总目录 | | [Features Gallery](docs/guides/FEATURES.md) | 带截图的可视化仪表盘导览 | | [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | 面向新手的代码库导读 | ### 🤖 协议与 API | Document | Description | | ------------------------------------------------- | --------------------------------------------------- | | [API Reference](docs/reference/API_REFERENCE.md) | 全部端点及示例 | | [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 规范 | | [MCP Server](open-sse/mcp-server/README.md) | 95 个 MCP 工具、IDE 配置、Python/TS/Go 客户端 | | [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP 安装、传输方式与工具参考 | | [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 协议、技能、流式传输、任务管理 | | [A2A Server Guide](docs/frameworks/A2A-SERVER.md) | A2A agent card、任务、技能与流式传输 | ### 📋 项目与质量 | Document | Description | | -------------------------------------------------- | ----------------------------------------------- | | [Contributing](CONTRIBUTING.md) | 开发环境与贡献指南 | | [Changelog](CHANGELOG.md) | 各版本完整发布历史 | | [Security Policy](SECURITY.md) | 漏洞报告与安全实践 | | [i18n Guide](docs/guides/I18N.md) | 40+ 语言支持、翻译工作流、RTL | | [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | 发布前验证步骤 | | [Coverage Plan](docs/ops/COVERAGE_PLAN.md) | 测试覆盖策略与 21,000+ 测试套件 |

# ⭐ 顶级贡献者 > OmniRoute 由充满热情的开源社区共同塑造。这些成员做出了卓越贡献，直接影响了项目的质量、稳定性和影响力。**感谢他们。**

oyi77
_{🥇 189 commits • +155K lines}
_{分析引擎、SQL 聚合、
代理市场、测试覆盖率}

Chris Staley
_{🥈 70 commits • +5.7K lines}
_{SSE 流加固、Responses API、
Gemini 分页、测试回归修复}

zenobit
_{🥉 62 commits • +24K lines}
_{CI/CD 流水线、33 种语言 i18n、
Void Linux 包、平台修复}

R.D. & Randi
_{🏅 108 commits • +30K lines}
_{Endpoints 页面、隧道集成、
Docker 工作流、A2A 状态、压缩 UI}

benzntech
_{🏅 22 commits • +7.5K lines}
_{Electron 桌面应用、自动更新、
发布构建工作流、跨平台 CI}

herjarsa
_{🏅 21 commits • +6K lines}
_{零延迟组合、vision-bridge 自动路由、
catalog 上下文长度、弹性 429 提示}

> 🙏 这些贡献者的功能、缺陷修复和基础设施改进，是 OmniRoute 可靠且功能丰富的重要组成部分。每一次 Pull Request、每一个测试用例、每一份 i18n 翻译文件都至关重要。开源是由像他们这样的人共同构建的。

---

## 👥 280+ 贡献者

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=200&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 # Create a release — npm publish happens automatically 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 的一个具体组成部分。谨以此向它们致以谢意。🙏 > ⭐ Star 数截至 2026 年 6 月 — 请为这些项目点 Star。 ### 🧬 渊源与网关 | 项目 | ⭐ | 对 OmniRoute 的启发 | | ------------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------- | | **[9router](https://github.com/decolua/9router)** · decolua | 19.0k | 本 fork 所基于的原始项目——在此扩展了多模态 API，并完成了完整的 TypeScript 重写。 | | **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 38.8k | 启发本次 JavaScript / TypeScript 移植的 Go 实现。 | | **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 52.1k | 其公开定价数据集为我们的成本追踪同步提供数据，其提供商标准化模型也为我们的路由设计提供了参考。 | ### 🗜️ 上下文与 Token 压缩 — 引擎 | 项目 | ⭐ | 对 OmniRoute 的启发 | | ----------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 78.2k | 病毒式传播的「why use many token when few token do trick」项目——其 caveman-speak 理念驱动了我们的标准压缩模式及 30+ 条填充/凝练规则。 | | **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai | 67.3k | 高性能命令输出压缩——启发了我们的 RTK 引擎、JSON 过滤 DSL、原始输出恢复，以及 RTK → Caveman 堆叠流水线。 | | **[headroom](https://github.com/headroomlabs-ai/headroom)** · headroomlabs-ai | 54.5k | 可逆上下文压缩（SmartCrusher）——启发了我们的 `headroom` 引擎及 `ccr` 检索标记模式。 | | **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.4k | 提示压缩研究（LLMLingua / LLMLingua-2）——启发了我们异步、代码安全、fail-open 的 `llmlingua` 引擎。 | | **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 28 | JS/ONNX 移植版（MobileBERT / XLM-RoBERTa），用作我们 LLMLingua 引擎的 worker-thread 后端。 | | **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 16 | PT-BR Token 压缩——驱动我们的 pt-BR 语言包：针对巴西葡萄牙语语法的赘语削减与填充词移除。 | | **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 68.8k | 病毒式传播的「懒惰资深开发者」YAGNI-coder 技能——启发了我们的 **less-code** Output Style：以最小可行变更引导，削减_生成_代码（与 Caveman 简洁文风相对应的输出轴姊妹方案）。 | ### 🧩 紧凑格式、Token 研究与代码感知工具 | Project | ⭐ | How it inspired OmniRoute | | ---------------------------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[TOON](https://github.com/toon-format/toon)** · toon-format | 24.7k | Token 导向对象表示法（Token-Oriented Object Notation）——其列式、表头加行的模型塑造了我们的表格压缩阶段。 | | **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 14 | 面向 Schema 的「面向 LLM 的 JSON」表示法——与 `[N rows]` 标记共同启发了我们的无损同质数组压缩。 | | **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples | 421 | Brotli/SQLite 缓存 + 每会话上下文增量——启发了我们的 `session-dedup` 引擎。 | | **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 1.0k | Bash 输出压缩 + MCP 配置文件——启发了我们的压缩退出（bail-out）机制与 MCP 工具清单精简。 | | **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 110 | 内容感知、按文件类型的输出压缩，带失败感知的退出策略——验证了我们的按类型分发与最小收益跳过逻辑。 | | **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh | 1.5k | 「找出幽灵 Token」（Find the ghost tokens）——其卸载 + 可恢复句柄模式影响了我们的 CCR（Context Control & Recovery）卸载思路。 | | **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 2 | 会话图 + 跨轮次行级去重蓝图——为我们的会话去重设计提供了参考。 | | **[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 | 89 | MCP 工具 schema/描述压缩——为我们的 MCP 工具清单基数缩减提供了参考。 | | **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 181 | Aider 风格的仓库映射排序——为我们的 repo-map / 检索排序探索提供了参考。 | | **[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 | Project | ⭐ | How it inspired OmniRoute | | ------------------------------------------------------------------ | ----: | ------------------------------------------------------------------------------------------------------------------- | | **[Mem0](https://github.com/mem0ai/mem0)** · mem0ai | 59.8k | 通用记忆层——其以代理作为读/写边界的模型塑造了我们的记忆架构。 | | **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.6k | 带分层记忆的有状态智能体——启发了我们的上下文控制与恢复（Context Control & Recovery，CCR）分层模型。 | | **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 1.8k | 涵盖 16 种常见 RAG/LLM 故障模式的 ProblemMap 分类法——是我们故障排查指南中的共用词汇。 | ### 🛰️ 流量检查、MITM 与透明代理 | Project | ⭐ | How it inspired OmniRoute | | --------------------------------------------------------------------------------- | ---: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** · chouzz | 48 | 对编程助手 ↔ LLM 流量的 MITM 拦截/分析——我们的 Traffic Inspector 移植了其 SSE 合并、会话归一化、主机透传与密钥掩码（MIT）。 | | **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.3k | 透明的逐进程代理路由——启发了我们崩溃安全的 MITM 拆卸、Socket 空闲超时、`/proc` 进程归因与 TPROXY 捕获。 | ### 📚 模型数据、可观测性与 UI | Project | ⭐ | How it inspired OmniRoute | | -------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------- | | **[models.dev](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 5.6k | AI 模型规格、定价与能力的开放数据库——已原生同步至我们的模型目录。 | | **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.4k | 基于节点的图库——驱动我们实时的 Compression Studio 与 Combo/Routing Studio。 | | **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 36.1k | LangGraph Studio 的实时工作流图可视化——启发了我们 Studios 的实时级联视图。 | | **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 30.1k | 其 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.2k | AI/LLM 品牌 Logo——在我们的仪表盘各处渲染服务商图标。 | ### 🛡️ 安全（Security） | 项目 | ⭐ | 对 OmniRoute 的启发 | | ------------------------------------------------------------------------------------------- | --: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** · tldrsec | 708 | 一份精心整理的默认安全（secure-by-default）库清单，指导我们的安全选型（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。 | ## ❤️ 支持 OmniRoute 免费且开源，在公开环境中构建与维护。若它为您节省了时间或金钱，欢迎考虑支持开发： - ⭐ **为仓库点 Star** — 这确实有助于提升可见度 - 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — 资助持续维护与新供应商接入 - 🐛 **报告 Bug 并分享反馈**，欢迎在 [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions) ## 📄 许可证 MIT License — 详见 [LICENSE](LICENSE)。 ---

**[⬆ 返回顶部](#-omniroute)** · 为开源 AI 社区倾力打造 ❤️ _{OmniRoute v3.8.43 · Node ≥22.0.0 · MIT License · omniroute.online}