# OmniRoute: một cổng AI dùng chung cho 375 nhà cung cấp, nhiều gói miễn phí — hướng dẫn cài đặt và dùng

> OmniRoute là một cổng AI (AI gateway) chạy trên máy bạn, gom hàng trăm nhà cung cấp mô hình AI về một địa chỉ API duy nhất theo kiểu OpenAI. Bạn dùng nó để nối Claude Code, Codex, Cursor, Cline... vào nhiều nguồn, trong đó có các gói miễn phí, và tự động chuyển nguồn khi hết hạn mức. Cài bằng Node.js hoặc Docker, không quá khó nhưng cần tự điền vài khoá bí mật trong file .env.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-04 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/omniroute-cong-ai-mien-phi-mot-endpoint-huong-dan-cai-dat

OmniRoute là một cổng AI (AI gateway) mã nguồn mở, giấy phép MIT, chạy ngay trên máy hoặc máy chủ của bạn. Nó cho bạn **một địa chỉ API duy nhất** để gọi tới rất nhiều nhà cung cấp mô hình AI. Theo mô tả của tác giả, con số là 375 nhà cung cấp (hơn 150 nơi có gói miễn phí) và hơn 1.400 mô hình, gồm Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax.

Vấn đề nó giải quyết rất đời thường. Bạn dùng một công cụ lập trình AI, đang làm dở thì hết hạn mức hoặc nhà cung cấp báo lỗi. Bạn phải tự đổi key, đổi địa chỉ, đổi tên mô hình. OmniRoute đứng ở giữa: bạn chỉ trỏ công cụ vào một địa chỉ, còn việc chọn nguồn nào và chuyển sang nguồn nào khi hết quota là việc của nó. Nó hợp với lập trình viên, người hay dùng Claude Code, Codex, Cursor, OpenCode, Cline hay Copilot, và cả người làm kinh doanh muốn thử nhiều mô hình mà không bị khoá vào một hãng.

Điểm đáng giá nhất là chế độ `auto`. Bạn đặt tên mô hình là `auto`, OmniRoute tự dựng một chuỗi dự phòng từ các nhà cung cấp bạn đã nối. Repo hiện có khoảng 86.900 sao và khoảng 13.300 fork, vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | cheaper-inference/OmniRoute
- kind | Ứng dụng
- desc | OmniRoute là cổng AI mã nguồn mở MIT: một địa chỉ API duy nhất nối tới hàng trăm nhà cung cấp, tự chuyển sang nguồn khác khi hết quota.
- stars | 87k
- lang | TypeScript
- license | MIT
```

## OmniRoute làm được gì

### Một địa chỉ cho nhiều nhà cung cấp

Bạn gọi tới một endpoint kiểu OpenAI (ví dụ `/v1/chat/completions`), phần còn lại OmniRoute lo. Lợi ích thực tế: đổi nhà cung cấp mà không phải sửa lại cấu hình trong từng công cụ. README còn nhắc tới `/v1/responses` và một API tra cứu mô hình `/v1/models/query` ở các bản mới.

### Combo: chuỗi mô hình tự chuyển

Một combo là danh sách các mô hình mà OmniRoute chạy lần lượt. Nếu hết quota, nhà cung cấp lỗi hoặc chi phí tăng vọt, nó chuyển sang mô hình khoẻ kế tiếp. Với người dùng, điều này nghĩa là đang làm việc thì ít bị gián đoạn hơn.

### Các biến thể `auto` không cần cấu hình

Bạn không cần tạo combo. Chỉ cần đặt tên mô hình là một trong các giá trị sau:

- `auto`: mặc định cân bằng, bám vào nhà cung cấp chạy tốt gần nhất.
- `auto/coding`: ưu tiên chất lượng cho việc viết code.
- `auto/fast`: ưu tiên độ trễ thấp nhất.
- `auto/cheap`: ưu tiên rẻ nhất theo token.
- `auto/subscription`: chỉ dùng hạn mức gói thuê bao bạn đã trả, không tự chuyển sang nguồn tính tiền.
- `auto/thrifty`: dùng hạn mức gói trước, rồi xuống dần các lựa chọn trả phí rẻ nhất.

Ngoài ra còn `auto/offline`, `auto/smart`, `auto/lkgp` và `auto/chaos` (gửi song song tới một nhóm mô hình rồi trả về một câu trả lời).

### 20 chiến lược định tuyến

Nếu muốn tự xây combo, bạn chọn trong 20 chiến lược: `priority` (dùng hết nguồn này mới sang nguồn kế), `round-robin`, `cost-optimized` (chọn rẻ nhất theo giá trong danh mục), `headroom` (chọn nơi còn nhiều quota nhất), `fusion` (nhiều mô hình trả lời rồi một mô hình làm giám khảo tổng hợp), `pipeline` (đầu ra bước này làm đầu vào bước sau) và nhiều kiểu khác. Công cụ `auto` chấm điểm 16 yếu tố như sức khoẻ nguồn, quota, giá, độ trễ.

### Trang theo dõi gói miễn phí

OmniRoute lập danh mục các gói miễn phí của bên thứ ba và hiển thị tổng hạn mức ước tính ở trang `/dashboard/free-tiers`. README ghi rõ đây là **ước tính tổng hợp từ các gói miễn phí của từng nhà cung cấp**, không phải token do OmniRoute tặng. Mỗi nhà cung cấp tự quyết hạn mức, điều khoản và có thể đổi bất cứ lúc nào.

### Những tính năng khác

Mô tả của tác giả nêu thêm nén token (RTK + Caveman, tiết kiệm 15-95% token), hỗ trợ MCP và A2A, bản Desktop/PWA. README cũng nhắc chế độ chạy không giao diện `serve --headless`.

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Node.js**: `package.json` yêu cầu phiên bản từ 22.22.2 trở lên và nhỏ hơn 23, hoặc từ 24.0.0 đến dưới 27. Nếu máy bạn đang dùng Node 20 hay 18, hãy nâng cấp trước.
- **Tài khoản nhà cung cấp AI**: OmniRoute không tặng token. Bạn phải tự đăng ký và lấy thông tin đăng nhập ở những nhà cung cấp bạn định dùng. Một số có gói miễn phí, một số cần key.
- **Docker** (không bắt buộc): repo có `Dockerfile` và nhiều file `docker-compose`, nên bạn có thể chạy bằng container nếu quen Docker.
- **Git**, nếu bạn muốn tải mã nguồn về.

Tư liệu chưa nói rõ yêu cầu về hệ điều hành hay phần cứng (GPU). Vì đây là cổng chuyển tiếp tới các dịch vụ AI bên ngoài nên nhìn chung không thấy yêu cầu GPU nào được nêu, nhưng bạn nên xem thêm trong thư mục `docs/` của repo.

```note
OmniRoute là nơi giữ key và thông tin đăng nhập các nhà cung cấp của bạn. Hãy đặt mật khẩu mạnh, đừng mở cổng ra Internet công cộng khi chưa bật yêu cầu API key, và đừng đưa file .env lên GitHub.
```

## Cài đặt từng bước

Lưu ý trung thực: phần README được cung cấp cho mình **chưa ghi lệnh cài đặt chi tiết** (mục Quick Start và Install bị cắt). Vì vậy bài này chỉ chép những thứ có chắc chắn trong tư liệu, và chỉ bạn chỗ xem phần còn lại.

```steps
- Kiểm tra Node.js | Xem máy bạn có Node đúng phiên bản yêu cầu chưa
- Lấy mã nguồn hoặc gói npm | Tải repo về bằng git, hoặc dùng gói npm tên omniroute
- Tạo file .env | Sao chép .env.example rồi điền các khoá bí mật
- Chạy OmniRoute | Làm theo mục Quick Start trong README hoặc dùng Docker
- Nối nhà cung cấp | Vào trang quản trị, thêm tài khoản và lấy key OmniRoute
```

### Kiểm tra Node.js

Mở terminal (trên Windows: PowerShell hoặc Windows Terminal) và gõ:

```bash
node --version
```

Kết quả phải thuộc khoảng mà `package.json` cho phép (từ 22.22.2 trở lên, trừ dải 23). Nếu thấp hơn, hãy cài lại Node từ trang chủ Node.js rồi mở terminal mới.

### Lấy mã nguồn hoặc gói npm

Tư liệu cho biết có gói npm tên `omniroute` kèm lệnh CLI, và có kho mã nguồn trên GitHub. Nếu muốn tải mã nguồn:

```bash
git clone https://github.com/cheaper-inference/OmniRoute.git
cd OmniRoute
```

Lệnh đầu tải repo về. Lệnh thứ hai đi vào thư mục vừa tải. Người mới hay quên bước `cd`, khiến các lệnh sau báo không tìm thấy file.

Nếu muốn dùng gói npm, dạng lệnh cài chung của npm là:

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

Đây là cách cài gói npm thông thường. README chưa nêu tên lệnh khởi chạy sau khi cài, nên bạn hãy xem mục Quick Start trong README hoặc thư mục `docs/` để biết lệnh chính xác. Bảng phiên bản trong README có nhắc `serve --headless`, cho thấy CLI có chế độ chạy không giao diện.

### Tạo file .env và điền khoá bí mật

Repo có sẵn file mẫu `.env.example`. Bạn sao chép nó thành `.env`. Trên Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

Trên macOS/Linux:

```bash
cp .env.example .env
```

Sau đó mở `.env` bằng trình soạn thảo và điền các biến quan trọng có trong file mẫu: `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD` (mật khẩu đăng nhập ban đầu) và `STORAGE_ENCRYPTION_KEY`. Cổng chạy nằm ở biến `PORT`. Ví dụ trong README dùng cổng 20128. Chỗ hay vấp: file phải tên đúng là `.env`, không phải `.env.txt`.

### Chạy OmniRoute

Có hai đường. Một là làm theo mục Quick Start trong README trên GitHub. Hai là dùng Docker: repo có `docker-compose.yml` (và các bản `docker-compose.selfhost.yml`, `docker-compose.prod.yml`). Phần README được cung cấp không ghi lệnh Docker cụ thể, nên mình không chép lệnh bịa vào đây. Hãy mở các file compose và thư mục `docs/` để xem cách dùng đúng với phiên bản bạn tải.

### Nối nhà cung cấp và lấy key

Sau khi chạy, bạn mở trang quản trị (dashboard), đăng nhập bằng mật khẩu đã đặt, rồi nối ít nhất một nhà cung cấp. README nhấn mạnh: **phải nối nhà cung cấp trước**, sau đó vào mục Dashboard → Endpoints để sao chép key OmniRoute của bạn. Trang `/dashboard/free-tiers` giúp bạn xem nhà cung cấp nào có gói miễn phí.

## Kiểm tra đã chạy được chưa

Cách kiểm tra mà README đưa ra là gửi thử một câu hỏi qua `curl`. Thay `YOUR_OMNIROUTE_KEY` bằng key lấy ở Dashboard → Endpoints:

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

Nếu nhận được một phản hồi JSON có câu trả lời của mô hình, bạn đã cài thành công. Trên Windows PowerShell, dấu `\` xuống dòng không dùng được và `curl` có thể là bí danh của lệnh khác. Bạn nên dùng Git Bash hoặc gõ lệnh trên một dòng bằng `curl.exe`.

Lưu ý README nói rõ: `auto` cần có ít nhất một đường đi hợp lệ. Cài mới mà chưa nối nhà cung cấp nào có thể không có đích nào dùng được, nên lỗi lúc này là bình thường. Ngoài ra thư mục `examples/quickstart/` có sẵn script mẫu cho Python, Node.js, PHP và cURL.

## Dùng vào việc thật

### Lập trình viên dùng Claude Code hay Cline mà hay hết quota

Bạn đang viết code và công cụ báo hết hạn mức giữa chừng. Thay vì đổi key thủ công, bạn trỏ công cụ vào địa chỉ OmniRoute và đặt tên mô hình là `auto/coding`. OmniRoute ưu tiên mô hình chất lượng cao cho viết code, và khi nguồn đó hết hạn mức thì chuyển sang nguồn khác bạn đã nối. Kết quả: phiên làm việc ít bị ngắt. Cách điền địa chỉ và key vào từng công cụ, bạn xem trong thư mục `docs/` của repo.

### Người mới học lập trình, muốn thử AI mà không tốn tiền

Bạn nối vài nhà cung cấp có gói miễn phí, xem trang `/dashboard/free-tiers` để biết hạn mức còn lại, rồi gọi thử bằng `auto/cheap` hoặc `auto`. Bạn nhận được câu trả lời mà không phải tự đi canh từng nhà cung cấp. Nhớ rằng hạn mức do từng bên quyết định và có thể đổi.

> Một địa chỉ, nhiều nguồn: hết quota ở nơi này thì tự chạy sang nơi khác, bạn không phải ngừng việc.
>
> — Ông T

### Nhóm nhỏ muốn dùng đúng gói thuê bao đã trả

Một nhóm đã mua gói thuê bao AI và không muốn bị tính thêm tiền ngoài ý muốn. Họ đặt mô hình là `auto/subscription`. Theo README, chế độ này chỉ dùng hạn mức gói đã có, hết là dừng chứ không tự chuyển sang nguồn tính tiền. Nếu chấp nhận trả thêm khi hết, họ có thể dùng `auto/thrifty`: dùng gói trước, rồi xuống từng bậc tới nguồn trả phí rẻ nhất.

### Chủ shop hoặc nhân viên văn phòng viết script nhỏ

Bạn cần một script Python tóm tắt đánh giá khách hàng. Repo có sẵn mẫu trong `examples/quickstart/`, bạn chép về, đổi key thành key OmniRoute và đặt `model` là `auto`. Kết quả là script dùng một địa chỉ cố định; sau này muốn đổi nhà cung cấp, bạn chỉ chỉnh trong OmniRoute chứ không sửa script.

## Lỗi hay gặp và cách xử lý

### Lỗi báo không có đích nào dùng được với `auto`

Cài mới mà chưa nối nhà cung cấp, hoặc chỉ có nhà cung cấp không cần key bị từ chối khi gọi từ ứng dụng bên thứ ba. Hãy nối ít nhất một nhà cung cấp có tài khoản hợp lệ. README cũng ghi các nhà cung cấp gắn nhãn `tos: avoid` (kể cả Kiro) mặc định bị loại khỏi định tuyến tự động, và nối tài khoản không thay đổi điều đó.

### Node.js sai phiên bản

Nếu lệnh cài hoặc chạy báo lỗi lạ ngay từ đầu, kiểm tra `node --version`. Phiên bản phải nằm trong khoảng `package.json` yêu cầu. Nâng Node lên rồi cài lại.

### Lỗi 401 hoặc không đăng nhập được

Thường do dùng sai key. Key để gọi API là key OmniRoute lấy ở Dashboard → Endpoints, không phải key của nhà cung cấp. Với trang quản trị, kiểm tra mật khẩu bạn đã đặt ở `INITIAL_PASSWORD`. Nếu mới sửa `.env`, hãy khởi động lại OmniRoute.

### Cổng 20128 đang bị chương trình khác dùng

Đổi giá trị `PORT` trong `.env` sang số khác rồi chạy lại, và nhớ đổi cả địa chỉ trong lệnh gọi. Nếu bạn chạy bằng Docker, cổng ánh xạ nằm trong file compose.

### Lệnh curl trên Windows không chạy

Nhiều bạn dán lệnh nhiều dòng vào PowerShell và gặp lỗi. Hãy chạy trong Git Bash, hoặc gộp thành một dòng bằng `curl.exe`. Cũng chú ý dấu nháy đơn và nháy kép khi dán JSON.

## Có nên dùng không

**Điểm mạnh:** mã nguồn mở MIT, một endpoint cho rất nhiều nhà cung cấp, tự chuyển nguồn khi hết quota, có nhiều chế độ `auto` dễ dùng, và công cụ theo dõi gói miễn phí. Dự án có cộng đồng lớn (hơn 900 người đóng góp theo mô tả) và vẫn được cập nhật đều. README còn có tài liệu so sánh với 9router, OpenRouter, CLIProxyAPI và LiteLLM trong `docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md` nếu bạn đang cân nhắc.

**Giới hạn:** README rất dài và thay đổi nhanh, nên có thể bạn phải đọc thêm tài liệu mới cài trơn tru. Các con số về token miễn phí chỉ là ước tính, đi lên hoặc xuống tuỳ nhà cung cấp. Bạn phải tự quản lý tài khoản và điều khoản của từng bên. Chuyện dữ liệu của bạn đi qua đâu phụ thuộc vào nhà cung cấp bạn chọn, nên đừng gửi thông tin nhạy cảm nếu chưa đọc điều khoản của họ.

**Nên chọn cách khác khi:** bạn chỉ dùng đúng một nhà cung cấp và không bao giờ hết quota (khi đó nối thẳng là đơn giản nhất), hoặc bạn không muốn tự vận hành một dịch vụ chạy trên máy mình. Còn nếu bạn dùng nhiều công cụ AI và hay bị ngắt vì hết hạn mức, OmniRoute rất đáng thử.

## Câu hỏi thường gặp

### OmniRoute có miễn phí không?

Chính OmniRoute là phần mềm mã nguồn mở giấy phép MIT, dùng miễn phí. Tuy vậy token AI không do OmniRoute tặng: bạn phải tự đăng ký các nhà cung cấp, và mỗi nhà cung cấp có hạn mức và giá riêng. Nhiều nơi có gói miễn phí, nhưng điều kiện do họ quyết định.

### Cần cài Node.js phiên bản nào?

package.json yêu cầu Node từ 22.22.2 trở lên và nhỏ hơn 23, hoặc từ 24.0.0 đến dưới 27. Bạn nên chạy node --version để kiểm tra trước khi cài.

### OmniRoute có cần GPU không?

Tư liệu không nêu yêu cầu GPU. OmniRoute là cổng chuyển tiếp tới các nhà cung cấp AI bên ngoài nên phần nặng do họ xử lý. Thông tin chi tiết về cấu hình máy chưa có trong tư liệu, bạn nên xem thư mục docs trong repo.

### Chạy trên Windows được không?

Tư liệu không liệt kê rõ hệ điều hành hỗ trợ. Repo có bản Desktop/PWA, Dockerfile và gói npm, nên nhiều khả năng có cách chạy trên Windows, nhưng bạn cần xác nhận trong README và docs của repo. Khi gọi thử bằng curl trên Windows, nên dùng Git Bash hoặc curl.exe.

### Key và dữ liệu của tôi có an toàn không?

OmniRoute chạy trên máy hoặc máy chủ của bạn, và file .env.example có các biến như JWT_SECRET, API_KEY_SECRET, STORAGE_ENCRYPTION_KEY để bạn đặt khoá bảo mật. Tuy nhiên yêu cầu gửi đi vẫn đến nhà cung cấp AI bạn chọn, nên an toàn còn phụ thuộc điều khoản của họ. Đừng mở cổng ra Internet khi chưa bật yêu cầu API key.

### OmniRoute khác gì OpenRouter hay LiteLLM?

README có tài liệu so sánh riêng với 9router, OpenRouter, CLIProxyAPI và LiteLLM trong docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md. Phần được cung cấp cho mình chưa có nội dung chi tiết của bảng so sánh đó, nên bạn nên mở file này để xem.

### Dùng được với công cụ nào?

Mô tả của tác giả nêu OmniRoute hoạt động với Claude Code, Codex, Cursor, OpenCode, Cline và Copilot. Cách cấu hình từng công cụ chưa có trong phần README mình nhận được, bạn xem thêm trong tài liệu của repo.
