## 项目概述

OmniRoute 是一个免费开源的 AI 网关，通过单一端点聚合 340+ 个 AI 提供商（含 90+ 免费），支持 Claude、GPT、Gemini、DeepSeek 等 1200+ 模型。内置智能路由、自动故障转移和令牌压缩（节省 15-95%），兼容 Claude Code、Cursor、Cline 等主流编码工具，零配置即可使用。

## 核心功能

- **单一端点，多提供商**：通过一个 OpenAI 兼容的端点访问 340+ 个 AI 提供商，包括 Claude、GPT、Gemini、DeepSeek、Kimi、MiniMax 等。
- **智能路由与自动故障转移**：19 种路由策略（优先级、加权、轮询、成本优化等），支持自动故障转移，确保服务不中断。
- **令牌压缩**：RTK + Caveman 堆叠压缩引擎，可节省 15-95% 的令牌（平均约 89%），显著降低成本。
- **零配置启动**：安装后无需任何配置即可使用，内置免费提供商（如 OpenCode Free、Felo）。
- **广泛兼容性**：兼容 Claude Code、Codex CLI、Cursor、Cline、Copilot 等 30+ 种编码工具和 IDE。
- **MCP 与 A2A 协议支持**：内置 MCP 服务器（109 个工具）和 A2A 代理协议，支持智能体间通信。
- **本地优先与隐私保护**：所有数据本地处理，凭证使用 AES-256-GCM 加密存储，默认无遥测。
- **丰富的部署选项**：支持 npm、Docker、Electron 桌面应用、Android Termux、PWA 等多种部署方式。

## 适用与不适用场景

### 适用场景

- **AI 开发者与研究者**：需要访问多种 AI 模型进行实验和开发。
- **编码代理用户**：使用 Claude Code、Cursor、Cline 等工具，希望降低 API 成本并提高可靠性。
- **多模型路由需求**：需要根据成本、延迟、配额等因素智能选择最佳模型。
- **本地优先部署**：希望数据不出本地，同时享受多种 AI 服务。

### 不适用场景

- **对延迟极度敏感的生产环境**：作为代理网关，会引入额外的网络跳转和延迟。
- **需要原生 SDK 全部特性的场景**：部分高级 API 特性可能无法完全兼容。
- **大规模企业级部署**：单节点架构，缺乏内置的集群和负载均衡支持。

## 技术架构与依赖

- **运行时**：Node.js 22.x / 24.x LTS
- **语言**：TypeScript 6.0（100% TypeScript）
- **框架**：Next.js 16 + React 19 + Tailwind CSS 4
- **数据库**：better-sqlite3 (SQLite, WAL 日志) + LowDB (JSON 遗留)
- **协议**：MCP (stdio / HTTP / SSE) + A2A v0.3 (JSON-RPC 2.0 + SSE)
- **流式传输**：Server-Sent Events (SSE) + WebSocket 桥接
- **压缩引擎**：12 引擎管道（RTK, Caveman, LLMLingua-2, GCF, OmniGlyph 等）
- **认证与安全**：OAuth 2.0 (PKCE) + JWT + API Keys + MCP 作用域认证 · AES-256-GCM 静态加密
- **测试**：Node.js 测试运行器 + Vitest — 25,000+ 测试用例

## 安装与快速开始

### 快速安装

```bash
npm install -g omniroute
omniroute
```

启动后，仪表盘访问 `http://localhost:20128`，API 端点访问 `http://localhost:20128/v1`。

### Docker 部署

```bash
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
```

### 其他安装方式

- **从源码构建**：`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`
- **Arch Linux (AUR)**：`yay -S omniroute-bin && systemctl --user enable --now omniroute.service`

## 典型使用方法

### 1. 零配置使用

安装后，直接使用 `auto` 模型即可自动路由到免费提供商：

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```

### 2. 配置编码工具

将你的编码工具（如 Claude Code、Cursor、Cline）的 Base URL 指向 `http://localhost:20128/v1`，API Key 从仪表盘获取，模型设置为 `auto`。

### 3. 使用 CLI 命令

```bash
omniroute run claude   --model openai/gpt-5.4          # 启动 Claude Code
omniroute run codex    --model glm/glm-5.2             # 启动 Codex CLI
omniroute configure codex                              # 交互式配置
```

### 4. 创建自定义路由组合

通过仪表盘或 API 创建包含多个模型的路由组合，设置优先级、故障转移策略等。

## 配置与部署要点

- **环境变量**：关键变量包括 `PORT`（默认 20128）、`JWT_SECRET`、`API_KEY_SECRET`、`INITIAL_PASSWORD` 等。
- **数据目录**：默认 `~/.omniroute/`，可通过 `DATA_DIR` 环境变量修改。
- **Docker 部署**：支持多架构（AMD64 + ARM64），推荐使用 `docker-compose` 进行生产部署。
- **远程模式**：通过 `omniroute connect <host>` 连接远程实例，使用作用域令牌进行安全访问。
- **性能优化**：启用令牌压缩可显著降低成本，建议根据使用场景选择合适的压缩模式。

## 限制、风险与许可证

- **许可证**：MIT 开源许可证。
- **限制**：作为代理网关，会引入额外的网络延迟；部分高级 API 特性可能无法完全兼容。
- **风险**：依赖第三方 AI 提供商的可用性和服务质量；免费提供商可能有使用限制和配额。
- **安全**：建议在生产环境中启用 API 密钥认证，并配置 IP 白名单。

## 官方链接

- **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/U47eFqAXCn
- **Telegram 群组**：https://t.me/omnirouteOficial

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README、文档、源代码。
- **分析时间**：2026-08-17
- **版本**：v3.8.49