diegosouzapw/OmniRoute · 上手攻略
- 仓库：diegosouzapw/OmniRoute
- 链接：https://github.com/diegosouzapw/OmniRoute
- 分类：AI Router / Gateway
- 作者：Tom
- 更新：2026-07-23
是什么
OmniRoute 是一个自托管 AI 网关，用单一端点聚合 278+ 提供商（含 90+ 免费层）的 500+ 模型，替开发者省去逐一对接每个 AI 提供商的麻烦。它支持自动 fallback 组合、Token 压缩、多策略路由、MCP 服务器、A2A 代理协议、内存持久化、Guardrails 安全过滤、TLS 指纹伪装等企业级特性，同时提供 Web 界面、桌面客户端、命令行和 PWA 多端体验。License 是 MIT。
核心定位：解决"免费额度散落在几十个平台、手动管理每个 SDK 让人崩溃"的问题——把这一切收敛到一个本地（可远程）端点，工具侧只对接 OmniRoute 一个入口。
解决什么问题
- 额度碎片化：43 个提供商各自有独立的免费层级，累加费脑子，OmniRoute 将其聚合成"诚实数字"统一展示在 Dashboard。
- SDK 地狱：不想维护十几个 provider SDK，一个 OpenAI 兼容端点搞定所有。
- 额度耗尽中断：请求到一半 provider Quota 用完，其他工具只能报错；OmniRoute 自动切换到 combo 下一个健康节点。
- 成本不可控：订阅制 provider 被按 $0 计费（无感），但预算和路由层仍能追踪实际用量。
- 多工具配置繁琐：Claude Code、Codex、Cursor、Cline 等每个都要单独配 API Key + endpoint，OmniRoute 的
setup-*命令一键搞定。
快速安装
OmniRoute 由 Node.js 编写，安装方式：
# 推荐：npm 全局安装（含 optional 依赖）
npm install -g omniroute@latest --include=optional
# 或用 npx 直接跑（不安装）
npx omniroute
# Docker（适合服务器）
docker run -p 20128:20128 \
-v ~/.omniroute:/data \
diegosouzapw/omniroute:latest
安装完成后访问 http://localhost:20128 打开 Dashboard（Web 界面默认端口 20128）。
注意：v3.8.49 为当前稳定版，文档中
release/v3.8.49分支对应最新功能。建议优先用latesttag。
核心用法
1. 零配置尝鲜（无需任何 API Key）
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
OmniRoute 内置了 OpenCode Free、Felo 等无需 Key 的 Provider，auto 模型会从这些内置免费节点构建虚拟 combo，开箱即答，无需注册任何账号。
2. 添加 Provider（以 OpenAI 为例）
在 Dashboard（http://localhost:20128）的 Providers 页填入 API Key，或命令行：
# 通过环境变量（推荐，不落盘）
export OPENAI_API_KEY=sk-...
# 或在 Dashboard UI 配置
添加后 Provider 自动加入 auto 候选池，无需重启。
3. 模型选择策略（auto 的 6 种模式）
设置 model 为以下值，控制路由策略：
| model 值 | 策略 |
|---|---|
auto |
均衡默认（LKGP — 粘滞上次成功节点） |
auto/coding |
代码质量优先 |
auto/fast |
最低延迟优先 |
auto/cheap |
单 Token 成本最低优先 |
auto/offline |
额度/速率限制余量最大优先 |
auto/smart |
质量优先 + 10% 探索新模型 |
4. 19 种路由策略（手动指定 combo 时使用）
combo 是 OmniRoute 的核心概念——一条由多个模型串联的链路，Quota 用完/节点失败/成本飙升时自动滑到下一个：
| # | 策略名 | 说明 |
|---|---|---|
| 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 | cache-optimized |
相同 prompt prefix 粘滞同一节点，最大化缓存命中 |
| 16 | lkgp |
Last-Known-Good-Path — 粘滞上次成功节点 |
| 17 | auto |
12 因子实时评分（默认） |
| 18 | fusion |
并行请求多个模型 + judge 综合一个答案 |
| 19 | pipeline |
链式，每节点输出进下一节点 |
📖 详细原理见 Auto-Combo Engine 文档。
5. CLI 工具一键配置
OmniRoute 为主流 Coding CLI 提供了 setup-* 命令，从本地 OmniRoute 读取模型目录并写入目标工具的配置：
# 配置 Claude Code
omniroute setup-claude
omniroute launch --profile glm52 # 启动指定 profile
# 配置 OpenAI Codex CLI
omniroute setup-codex
codex --profile glm52
# 配置 OpenCode（OpenAI 兼容）
omniroute setup-opencode
export OMNIROUTE_API_KEY=sk-... # 存环境变量，不落盘
opencode -m omniroute/glm/glm-5.2 "你的需求"
# 配置 Cline（需指定模型）
omniroute setup-cline --model glm/glm-5.2
# 配置 Continue（cn CLI）
omniroute setup-continue --dry-run # 先预览不落盘
所有命令支持 --remote http://host:port --api-key <key> 指向远程 OmniRoute，或用 omniroute connect <host> 建立持久上下文。
6. Token 压缩
OmniRoute 支持 RTK + Caveman 堆叠压缩，节省 15–95% Token：
# 开启压缩（Dashboard 或配置）
# RTK：对 Gradle/.NET 等结构化代码过滤噪音
# Caveman：对 DE/FR/JA/中文等语言高效压缩
# 效果：同等上下文窗口可容纳 3–6 倍对话历史
详细压缩引擎配置见 Compression Engines 文档。
7. MCP Server（内置 104 工具）
OmniRoute 自带 MCP Server，无需单独部署即可让 LLM 调用工具：
# 开启 MCP（Dashboard → MCP 页）
# 支持 3 种传输协议，31 个 scopes，104 内置工具
# 包括：FTS5+向量内存、文件读写、Git、Web Search 等
8. 远程模式（Remote Mode）
在 VPS 或 Tailnet 上运行 OmniRoute，本地机器通过 omniroute connect 配对：
# VPS 上
omniroute --remote --port 20128
# 本地
omniroute connect <vps-ip> # 建立 scoped token 上下文
omniroute setup-codex # 本地落配置，catalog 从远程拉取
典型适用场景
- AI 工具集玩家：同时用 Claude Code、Codex、Cursor、Cline，每个都要单独配 API Key —— OmniRoute 一个端点搞定所有。
- 额度猎人：薅尽 Google AI Studio、OpenRouter、SiliconFlow 等几十个平台的免费额度，OmniRoute 自动帮你在它们之间 failover。
- 自托管 AI 平台：在私有服务器上搭 AI 网关，给团队成员统一的 API 入口，支持 quota 管控和 Guardrails。
- 多模型对比评测：用 Fusion 策略并行问多个模型 + judge 打分，一次调用拿到聚合答案。
- 成本敏感项目：用
auto/cheap策略自动选最便宜的可用模型，配合 Quota-Share 在多 Key 之间公平分配订阅额度。 - 企业安全合规：内置 PII 检测、Prompt Injection Guard、Guardrails，对外暴露的只有 OmniRoute 而非每个 Provider。
坑与注意
- MIT License ≠ 无成本：OmniRoute 本身免费，但调用各 Provider 的模型仍有各自费用。免费 Provider 有额度上限，
auto默认不会无限薅。 - TPROXY/MITM 依赖系统权限：TLS 指纹伪装（绕过 CAPTCHA）需要 TPROXY 劫持，需要
sudo且在 Linux 上配置，Windows/macOS 不支持。 - 部分 Provider 需要 OAuth（Claude、Codex、Copilot 等 15+），OmniRoute 有 Antigravity OAuth helper 简化配置，但须注意这些 provider 的使用政策。
- Dashboard 默认无认证：本地运行风险可控，但暴露在公网时必须配置认证（支持 API Key、Bearer Token 等）。
- Quota-Share 策略：多 Key 共享一个 Provider 账号时，默认是 work-conserving（空闲 Key 的额度会借给活跃 Key），需注意是否有 Provider 禁止账号共享。
- Model ID 大小写敏感：某些 Provider 的模型 ID 大小写敏感（如
openai/gpt-4ovsOpenAI/GPT-4O），写 combo 时注意校验。 - 多语言压缩非均质：Caveman 对中文文言文（wényán）效果显著，但白话中文和其他语言效率不同，建议按语言选引擎。
- 版本更新快：
release/v3.8.49分支对应最新功能，但 npmlatesttag 有时略有滞后，更新前建议比对 CHANGELOG。
与同类对比
| 特性 | OmniRoute | LiteLLM | OpenRouter | Portkey |
|---|---|---|---|---|
| 自托管 | ✅ | ✅ | ❌ | ⚠ 付费 |
| Provider 数量 | 278+ | ~100 | ~50 | ~30 |
| 免费 Provider | 90+ | n/a | 直通 | n/a |
| 路由策略 | 19 种 | 少数 | 3 层 | 少数 |
| Token 压缩 | RTK+Caveman+LLMLingua-2 等 | 无 | 无 | 无 |
| 内置 MCP Server | ✅（104 工具） | ❌ | ❌ | ❌ |
| A2A 协议 | ✅（6 skills） | ❌ | ❌ | ❌ |
| 内存持久化 | ✅（FTS5+向量） | ❌ | ❌ | ❌ |
| Guardrails | ✅免费 | ⚠ 部分 | ❌ | ⚠ 付费 |
| TLS 指纹伪装 | ✅ JA3/JA4 | ❌ | ❌ | ❌ |
| 云端 Agent 集成 | Codex/Cursor/Devin/Jules | ❌ | ❌ | ❌ |
| MIT License | ✅ | ✅ | ❌ 专有 | ❌ 专有 |
选 OmniRoute：需要自托管、免费 Provider 最大覆盖、MCP/A2A、企业级 Guardrails、不想在每个 Coding CLI 里单独配置 key。
选 LiteLLM：Python-first 项目，主要通过 litellm.completion() 调用，生态成熟。
选 OpenRouter：不想自己运维，愿意付 SaaS 溢价，要单一支付方式。
选 Portkey：企业需要商业 SLA + 合规审计，愿意付费。
一句话推荐结论
OmniRoute 是目前免费 Provider 最多、路由策略最丰富、内置工具最全的开源 AI 网关，尤其适合想用 auto 策略让 Claude Code、Codex 等 Coding CLI 自动在 500+ 模型间 failover、同时不想管理一堆 SDK 的个人开发者和小团队——开箱即用，MIT 免费，值得一试。
⚠ 本文基于 v3.8.49（release/v3.8.49 分支）公开文档整理。安装前请以 CHANGELOG 和实时文档为准。