OmniRoute 免费 AI 网关详细部署教程

OmniRoute 是一个强大的开源 AI 网关，它聚合了超过 350 家 AI 提供商和 1200+ 模型（包括 Claude、GPT、Gemini、DeepSeek 等），通过一个统一的 OpenAI 兼容接口提供服务。其最大亮点是集成了大量免费模型，并具备智能路由、自动故障转移和先进的上下文压缩功能，能显著降低 AI 使用成本。

📋 目录

  1. OmniRoute 是什么
  2. 核心特性与优势
  3. 安装前准备
  4. 快速开始
  5. 详细安装方法
  6. 配置与连接提供商
  7. 使用 OmniRoute
  8. 高级功能与配置
  9. 更新与卸载
  10. 常见问题排查

OmniRoute 是什么

OmniRoute 是一个本地部署的 AI 网关服务。它就像一个“AI 路由器”，将您和各种 AI 模型提供商之间的连接统一管理起来。

核心价值：

  • 统一接口：提供与 OpenAI 兼容的 API 端点 (http://localhost:20128/v1)，您所有的 AI 工具（如 Claude Code、Cursor、OpenCode）都可以直接指向它，无需为每个工具分别配置不同的 API。
  • 聚合免费资源：自动发现并整合了超过 154 个带免费额度的 AI 提供商（如 OpenCode Zen、Kilo Code、SiliconFlow 等）。通过 auto 模型，网关会自动在它们之间智能路由。
  • 智能路由与容灾：如果一个模型调用失败或额度耗尽，auto 模式会自动将请求转移到另一个健康的免费模型上，实现零中断。
  • 上下文压缩：内置 12 种压缩引擎（如 RTK、Caveman），可自动压缩请求中的提示词和工具输出，在不影响质量的前提下节省 15%-95% 的 token 消耗。

核心特性与优势

特性 说明 实际好处
⚡ 零配置启动 安装后无需任何 API Key 即可使用 auto 模型 安装即用，快速体验
🌐 海量提供商 支持 350+ 提供商，1200+ 模型 丰富的免费和付费模型选择
🧭 智能路由 (auto) 15 因素评分自动选择最优模型 平衡成本、速度和质量
🛡️ 自动故障转移 当前模型失败时自动切换备用 极高的服务可用性
🗜️ 上下文压缩 12 种压缩引擎堆栈，节省 15%-95% tokens 大幅降低 API 使用成本
🖥️ 广泛兼容性 兼容所有 OpenAI API 工具 (Claude Code, Cursor 等) 无缝集成现有工作流
🔒 本地优先 所有数据在本地处理，不经过第三方云服务 数据隐私和安全
📦 多方式部署 支持 npm、Docker、Desktop、Android (Termux) 可运行在任何设备上

安装前准备

系统要求

  • Node.js：版本 22.x 或 24.x LTS (>=22.22.2 <23 || >=24.0.0 <27)
  • 包管理器：npm (随 Node.js 安装), 或 pnpm, Bun
  • 操作系统：Linux, macOS, Windows (WSL2 推荐), 甚至 Android (通过 Termux)

检查环境

打开终端，执行以下命令确认版本：

1
2
3
4
node --version
# 应显示 v22.x.x 或 v24.x.x
npm --version
# 应显示对应的 npm 版本

快速开始

这是最快速的启动方式，适合立即体验。

1. 全局安装 OmniRoute

1
npm install -g omniroute

2. 启动服务
在终端中执行：

1
omniroute

您会看到类似 Server listening on http://localhost:20128 的输出。

3. 验证服务
打开浏览器访问 http://localhost:20128，您应该能看到 OmniRoute 的仪表板界面。在仪表板中，您可以管理提供商、查看模型列表和流量统计。

您也可以使用 curl 进行测试：

1
2
3
4
5
6
7
# 列出可用模型（无需认证）
curl http://localhost:20128/v1/models

# 使用 auto 模型发送一个聊天请求
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

如果看到 JSON 格式的回复，说明 OmniRoute 已成功运行！

详细安装方法

除了全局 npm 安装，OmniRoute 还支持多种部署方式，以适应不同场景。

1. 通过 Docker 安装（推荐生产环境）

Docker 提供了隔离和易于管理的环境。

1
2
3
4
5
# 拉取并运行最新稳定版镜像
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

对于编码助手负载，需要增加内存限制，详见 Docker Guide。

2. 从源码安装（开发或自定义）

适合想要贡献代码或进行深度定制的用户。

1
2
3
4
5
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
cp .env.example .env
npm install
npm run dev

3. 通过 pnpm 安装（更快的安装速度）

1
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute

4. 在 Android (Termux) 上运行（移动端方案）

1
2
pkg install nodejs
npx -y omniroute

配置与连接提供商

OmniRoute 本身是一个网关，需要连接到真实的 AI 提供商才能工作。启动后，您可以通过 Web 仪表板或 API 来配置。

通过仪表板配置（推荐）：

  1. 打开 http://localhost:20128。
  2. 进入 Providers 页面。
  3. 点击 Connect 按钮。您可以看到所有可用的提供商列表，包括标记为 Free 的免费选项。
  4. 选择您想使用的提供商（例如 Kimi, OpenCode Free, Groq 等）。根据提供商，您可能需要提供 API Key（可从提供商官网获取）或直接点击连接。
  5. 连接成功后，该提供商的模型就会出现在 /v1/models 列表中。

关键免费提供商（无需信用卡）：

  • OpenCode Zen: 提供 DeepSeek V4, Nemotron 3 等模型，无 token 上限。
  • Kilo Code: 提供自动路由和 Tencent Hy3 模型。
  • SiliconFlow: 提供 DeepSeek V3.2 / R1 的免费额度。
  • Z.AI GLM: 提供 GLM-4.7 / 4.5-Flash 模型。
  • Pollinations: 提供 GPT, Llama, Claude 等，无需 API Key。

只需连接一个或多个免费提供商，OmniRoute 的 auto 模型就能开始工作。

使用 OmniRoute

配置好提供商后，就可以像使用 OpenAI API 一样使用 OmniRoute。

1. 作为 AI 编程助手的后端

这是 OmniRoute 最流行的用例。您需要将您的 AI 编码工具（如 Claude Code, Cursor）的 API 端点指向 OmniRoute。

通用配置：

  • Base URL: http://localhost:20128/v1
  • API Key: 从仪表板 Endpoints 页面获取（默认可以不填，但推荐设置一个）。

Claude Code 配置示例：
在 Claude Code 中设置环境变量或配置文件：

1
2
export ANTHROPIC_BASE_URL=http://localhost:20128/v1
export ANTHROPIC_API_KEY=your-omniroute-key

然后 Claude Code 就会通过 OmniRoute 路由所有请求。

一键启动支持的工具：
OmniRoute 提供了 omniroute run 命令，可以直接启动多个流行的 CLI 工具：

1
2
3
4
5
6
# 启动 Claude Code
omniroute run claude --model auto/coding
# 启动 Codex
omniroute run codex --model auto/fast
# 查看所有支持的工具
omniroute run --help

2. 直接在终端交互

您也可以使用 omniroute chat 命令，在终端中与 OmniRoute 进行对话（TUI 界面）：

1
omniroute chat

在聊天界面中，您可以使用 /model auto 切换模型，/combo 管理路由组合等。

高级功能与配置

🎯 智能组合 (Combos) 与路由策略

auto 模型是多种路由策略的组合。您可以创建自定义组合，指定模型切换的规则。

创建自定义组合：
通过仪表板或 API，您可以定义一个组合，例如：

  • 优先使用 openai/gpt-4o，如果失败则回退到 anthropic/claude-3.5-sonnet，若都不可用则使用 google/gemini-1.5-flash。

支持的 19 种路由策略包括 priority (优先级), round-robin (轮询), cost-optimized (成本优化), cache-optimized (缓存优化) 等。

🗜️ 上下文压缩优化

OmniRoute 的压缩引擎默认开启（standard 模式），可节省约 30% token。您可以为不同任务选择不同压缩级别。

在请求中指定压缩级别（通过 HTTP Header）：

1
2
3
4
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Compression: ultra" \
  -d '{"model":"auto","messages":[{"role":"user","content":"..."}]}'

有效的压缩模式：off, lite, standard, aggressive, ultra, rtk, stacked。

🛰️ 远程模式

您可以在 VPS 上部署 OmniRoute，然后从本地电脑通过 omniroute connect 命令远程管理它，所有 CLI 命令都会透明地作用于远程实例。

1
2
omniroute connect your-vps-ip
omniroute models list  # 现在列出的是远程服务器的模型

🧩 集成 MCP / A2A

OmniRoute 本身可以作为一个 MCP (模型上下文协议) 或 A2A (智能体到智能体) 服务器，让其他 AI 智能体能够调用其 110+ 个工具来管理路由、提供商、压缩等。

1
2
# 以 MCP 模式启动
omniroute --mcp

更新与卸载

更新 OmniRoute

  • 通过 npm 安装的：npm update -g omniroute
  • 通过 Docker 安装的：docker pull diegosouzapw/omniroute:latest 并重新创建容器。
  • 通过源码运行的：git pull 并重新执行 npm install && npm run build。

卸载 OmniRoute

  1. 停止正在运行的 OmniRoute 进程（按 Ctrl+C）。
  2. 全局卸载 npm 包：npm uninstall -g omniroute
  3. （可选）删除配置和数据目录。默认情况下，数据存储在 ~/.omniroute/ 或项目目录下的 data/ 文件夹中。

常见问题排查

问题：npm install -g omniroute 安装失败或有 ERESOLVE 警告。

  • 解决：这些通常是关于 peer dependencies 的警告，可以安全忽略。如果安装卡住，可以尝试使用 pnpm 或 bun 安装。

问题：启动后访问 http://localhost:20128 无响应。

  • 解决：检查是否有其他程序占用了 20128 端口。可以通过 PORT=3000 omniroute 指定其他端口。

问题：auto 模型调用返回错误。

  • 解决：确保您已经通过仪表板至少连接了一个提供商。如果提供商有额度限制，也可能因为超出限额而失败。

问题：我想使用的免费提供商在仪表板中找不到。

  • 解决：一些提供商可能需要通过“商店”或“社区目录”手动添加。可以查看仪表板的 Providers 页面底部的导入选项或参考 Provider Reference。

通过以上步骤，您应该能够顺利安装、配置并开始使用 OmniRoute。它将为您提供一个统一、智能且成本友好的 AI 访问层，无论您是个人开发者还是团队，都能从中受益。如需更详细的指南，可以随时查阅 OmniRoute 的官方文档。