OmniRoute 项目详细总结
仓库地址：https://github.com/diegosouzapw/OmniRoute 官网：https://omniroute.online 协议：MIT ｜ 语言：TypeScript ｜ 包名：npm
omniroute｜ Docker：diegosouzapw/omniroute当前版本：v3.8.43 ｜ Star：23,000+ ｜ Fork：3,100+ ｜ 创建时间：2026-02-13
一、它是什么
OmniRoute 是一个免费、开源（MIT）、本地优先的 AI 网关（AI Gateway），由 Diego Souza（diegosouzapw） 发起，500+ 贡献者参与。它最初是一个 fork，融合了 9router（TypeScript 多模态扩展）与 CLIProxyAPI（Go 版移植）两大项目的思路，如今已发展为功能最完整的开源 LLM 路由方案之一。
一句话定位：
一个端点，接入 250+ AI 服务商（90+ 含免费层，11 家永久免费），让你的 Claude Code、Codex、Cursor、Cline、Copilot、Antigravity 等编程工具共用一套配置，自动容灾，自动压缩 Token，从任何地区访问。
核心定位是「编程助手的统一代理层」，但也能作为通用大模型代理使用。
二、它解决了什么问题
| 日常痛点 | OmniRoute 的解法 |
|---|---|
| 订阅配额每月浪费 | 追踪配额，在重置前用尽每一枚 Token |
| 写到一半被限速打断 | 四层自动 fallback（订阅→API→廉价→免费），毫秒级切换 |
git diff、grep、日志等工具输出狂烧 Token |
RTK + Caveman 级联压缩，节省 15–95% |
| 每家 API 动辄 $20–50/月 | 成本优先路由，自动导向最便宜可用模型 |
| 每款 AI 工具配置各异 | 一个端点、一个控制台、一套配置 |
| 所在地区被封锁（俄罗斯/中国/伊朗等） | 三级代理 + TLS 指纹伪装 |
三、核心能力一览
1. 多服务商聚合（250+ 家，90+ 含免费层）
- 覆盖所有主流实验室：OpenAI、Anthropic、Gemini、xAI Grok、DeepSeek、Mistral、Qwen、Meta Llama、Groq、NVIDIA、MiniMax、Cohere、Perplexity、HuggingFace、Together、Fireworks、Cloudflare、Baidu 等。
- 11 家永久免费：Kiro（免费 Claude）、Qoder（无限免费 Kimi-K2/DeepSeek-R1）、Pollinations（无需密钥）、LongCat、Cloudflare AI、NVIDIA NIM、Cerebras 等。
- 每月约 1.6B 免费 Token（稳定），首月可到 2.1B；额外有不可计数的永久免费无 Cap 服务商（SiliconFlow、Z.AI GLM-Flash 等）。
2. 路由策略（18 种）
| 类别 | 策略 |
|---|---|
| 顺序/配额榨取 | priority、fill-first |
| 负载均衡 | weighted、round-robin、p2c、least-used |
| 成本控制 | cost-optimized、headroom、reset-window、reset-aware |
| 随机/隐私 | random、strict-random |
| 上下文接力 | context-relay、context-optimized |
| 高级 | lkgp（沿用上次最佳）、auto（12 因子实时评分）、fusion（多模型并行 + 裁判合成）、pipeline（链式串联） |
⚡ 零配置 auto 模式
| 模型 ID | 优化目标 |
|---|---|
auto |
均衡默认（LKGP 黏住上次好用的服务商） |
auto/coding |
代码质量优先 |
auto/fast |
最低延迟优先 |
auto/cheap |
单位 Token 成本最低 |
auto/offline |
配额/限速余量最充裕 |
auto/smart |
质量优先 + 10% 探索 |
3. 三层容灾
- 熔断器（Circuit Breaker）：整家服务商级别，失败后停止发请求，自动探测恢复。
- 连接冷却（Connection Cooldown）：单个账号/密钥级别，跳过限速密钥，其他密钥继续服务。
- 模型隔离（Model Lockout）：仅隔离单一配额耗尽模型，不影响同服务商其他连接。
4. Token 压缩（RTK + Caveman 级联，节省 15–95%）
10 大可组合引擎流水线：
| # | 引擎 | 作用 |
|---|---|---|
| 1 | Session-Dedup | 跨轮次内容去重 |
| 2 | CCR | 大块归档到检索标记后按需拉取 |
| 3 | RTK | 智能工具输出过滤/去重/截断 |
| 4 | Headroom | 同构 JSON 数组无损表格式压缩（~30%） |
| 5 | Relevance | 针对最近用户 query 的抽取式句子评分 |
| 6 | Caveman | 基于规则的叙述性压缩（输出端 ~65–75%） |
| 7 | LLMLingua-2 | MobileBERT ONNX ML 语义剪枝（代码安全、异步） |
| 8 | Lite | 空白符/图片 URL 精简（低延迟基线） |
| 9 | Aggressive | 摘要 + 老旧轮次渐进老化 |
| 10 | Ultra | 启发式 + 可选小模型（SLM）层 |
一键预设：
| 模式 | 节省 | 场景 |
|---|---|---|
| Lite | ~15% | 常驻安全默认 |
| Standard (Caveman) | ~30% | 日常编码 |
| Aggressive | ~50% | 长时间工具密集型 |
| Ultra | ~75% | 最大化节省 |
| RTK | 60–90% | Shell/测试/构建/Git 输出 |
| Stacked (RTK → Caveman) | 78–95% | 混合提示 + 工具日志 |
代码块、URL、JSON 永远逐字节保留，不影响精度。
5. Agent 协议
- MCP（stdio / HTTP / SSE 三种传输，94 个工具，30 个权限域，完整审计轨迹）
- A2A（JSON-RPC 2.0 + SSE，6 项技能）：让 AI Agent 自主操控 OmniRoute（路由、服务商、Combo、缓存、压缩、记忆）。
6. 其他企业级能力
- 记忆系统（FTS5 + 向量，可选 int8 量化，默认关闭）
- 安全护栏（PII、提示注入、视觉；红队测试套件）
- 评估框架（golden-set：exact/contains/regex/custom）
- 三级代理 + TLS 指纹伪装（JA3/JA4，
wreq-js）+ 1proxy 免费代理市场 - 兼容开放协议：OpenAI ↔ Claude ↔ Gemini ↔ Responses API 自动翻译
- 多账号轮询、OAuth 2.0 PKCE 自动刷新（8 家服务商）
- Batch + Files API、OpenAPI 3.0 spec、WebSocket 桥接
- Quota-Share：把一份订阅跨团队公平分配
- 远程模式：本机 CLI 远程操控 VPS 上的 OmniRoute
- Notion + Obsidian 集成、插件市场、AI Agent Skills（markdown 清单，43 个）
- 透明 MITM 解密（TPROXY）：捕获忽略代理变量的 CLI 流量
- 成本遥测：每请求响应头
X-OmniRoute-*返回成本/用量
四、兼容的编程工具（24+）
一个配置 http://localhost:20128/v1，几乎所有 OpenAI 兼容客户端可用：
Claude Code、Codex CLI、Cursor、Copilot、Continue、OpenCode、Kilo Code、Droid、OpenClaw、Kiro、Command Code、Cline、Antigravity、Windsurf、AMP、Hermes、Qwen CLI、Roo，乃至任何 OpenAI 兼容工具。
五、如何上手（Quick Start）
步骤 1：安装并运行
npm install -g omniroute
omniroute
- 控制台：http://localhost:20128
- API：http://localhost:20128/v1
步骤 2：连接免费服务商（无需注册）
控制台 → Providers → 连接 Kiro AI（免费 Claude，约 50 积分/月）或 OpenCode Free（无需认证）→ 完成。
步骤 3：配置你的编程工具
Base URL: http://localhost:20128/v1
API Key: [从 控制台 → Endpoints 复制]
Model: auto # 零配置智能路由，或指定任意 provider/model
步骤 4：验证
curl http://localhost:20128/v1/models -H "Authorization: Bearer ***"
看到已连接模型列表即成功。
六、其他安装方式
Docker
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
源码
cp .env.example .env && npm install
PORT=20128 npm run dev
pnpm
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
桌面端（Electron，Windows/macOS/Linux）
npm run electron:build
Android（Termux，无需 Root）
pkg install nodejs && npx -y omniroute
跳过原生构建（CI/慢机）
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute
七、日常使用
CLI 命令（80+ 条）
omniroute # 启动网关 + 控制台（端口 20128）
omniroute chat # 交互式 TUI 聊天（/model /combo /skill /memory）
omniroute setup # 引导向导
omniroute doctor # 诊断服务商、端口、原生依赖
omniroute launch # 零配置启动器
omniroute launch-codex # 零配置启动 Codex
其余命令域：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 等。
Combo 模式：4 层容灾示例
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 ← 免费、无限（永不断线）
$0 永久免费 Combo
1. kr/claude-sonnet-4.5 (Kiro — ~50 credits/mo)
2. if/kimi-k2-thinking (Qoder — 无限)
3. pol/gpt-5 (Pollinations — 无需密钥)
4. lc/LongCat-2.0 (一次性 10M，需 KYC)
压缩: aggressive (~50%) → 翻倍免费配额 · 成本: $0/月
远程模式：本机 CLI 远操控 VPS
omniroute connect 192.168.0.15
omniroute models list # 在远端执行
omniroute configure codex # 选远端模型写本地配置
omniroute tokens create --name ci --scope read
omniroute contexts use default # 切回本机
Agent 接入
# 给 Claude Code 授予 OmniRoute 的 MCP 工具集
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
| 协议 | 端点 |
|---|---|
| MCP (stdio) | omniroute --mcp |
| MCP (HTTP) | http://localhost:20128/api/mcp/stream |
| MCP (SSE) | http://localhost:20128/api/mcp/sse |
| A2A | http://localhost:20128/.well-known/agent.json |
八、隐私与安全
- 100% 本地运行（npm、Docker、桌面、手机），请求链路中无任何 OmniRoute 云端节点
- API 密钥与 OAuth 令牌 AES-256-GCM 加密静态保存
- 默认零遥测，提示词只发往你自己选定的服务商
- 网关加固：API 密钥权限域、IP 过滤、速率限制、提示注入防御、loopback 进程路由
- MIT 协议完全开源，逐行可审计
九、关键环境变量
| 变量 | 默认值 | 用途 |
|---|---|---|
PORT |
20128 |
API + 控制台端口 |
REQUIRE_API_KEY |
false |
是否要求所有请求带 API Key |
DATA_DIR |
~/.omniroute |
数据库与配置存储位置 |
十、技术栈
- Runtime：Node.js 22.x / 24.x LTS（推荐 24）
- 语言：TypeScript 6.0，core 模块零
any - 前端：Next.js 16 + React 19 + Tailwind CSS 4
- 数据库：better-sqlite3 + LowDB（JSON legacy）
- 校验：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 Keys + MCP Scoped Authorization
- 测试：Node test runner + Vitest，21,000+ 测试用例，2,586 文件
- 平台：Electron、Termux、PWA
- 国际化：42 种语言
十一、同类对比（官方）
| 能力 | OmniRoute | 其他路由 |
|---|---|---|
| 服务商数量 | 250 | 20–100 |
| 免费服务商 | 90+（11 家永久免费） | 1–5 |
| 路由策略 | 18 种 | 1–3 种 |
| Token 压缩 | RTK + Caveman 级联 15–95% | 无 / 20–40% |
| 内置 MCP | 94 工具，3 传输，30 scope | 少见 |
| A2A | 6 技能，JSON-RPC 2.0 | 无 |
| 记忆系统 | FTS5 + 向量 | 少见 |
| 安全护栏 | PII/注入/视觉 | 少见 |
| 云代理 | Codex/Cursor/Devin/Jules | 无 |
| TLS 指纹伪装 | JA3/JA4 via wreq-js | 无 |
| 多平台 | Web/桌面/Termux/PWA | 仅 Web |
| i18n | 42 语言 | 0–4 |
十二、资源链接
- GitHub：https://github.com/diegosouzapw/OmniRoute
- 官网：https://omniroute.online
- npm：https://www.npmjs.com/package/omniroute
- Docker Hub：https://hub.docker.com/r/diegosouzapw/omniroute
- Discord：https://discord.gg/EkzRkpzKYt
- Telegram：https://t.me/omnirouteOficial
常用文档路径（仓库内）：
- docs/guides/USER_GUIDE.md：用户指南
- docs/guides/SETUP_GUIDE.md：完整安装
- docs/reference/CLI-TOOLS.md：各编程工具逐项配置
- docs/routing/AUTO-COMBO.md：自动路由引擎
- docs/compression/COMPRESSION_GUIDE.md：压缩指南
- docs/architecture/RESILIENCE_GUIDE.md：容灾架构
- docs/reference/PROVIDER_REFERENCE.md：完整服务商目录
- docs/reference/FREE_TIERS.md：免费层完整目录
- docs/ops/PROXY_GUIDE.md：代理指南
- docs/frameworks/MCP-SERVER.md / A2A-SERVER.md：协议接入
总结结论： OmniRoute 是目前开源生态中最完整的 AI 网关之一，核心价值在于：用一套本地自托管服务把分散的 AI 服务商、编程 CLI、配额、压缩、容灾和 Agent 协议整合在一个端点上。对个人开发者可零成本起步（永久免费服务商 + 压缩翻倍配额），对团队可做 Quota-Share 与远程模式管理，对受限地区可用三级代理 + TLS 伪装绕过封锁。如果你正在用 Claude Code / Cursor / Codex 等编程助手并希望降低成本、提升可用性，OmniRoute 是一个值得尝试的方案。