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
Bài này là một góc nhìn khác về cheaper-inference/OmniRoute — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: OmniRoute: một cổng AI gom nhiều nhà cung cấp, có tầng miễn phí — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
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.
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.
cheaper-inference/OmniRoute
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.
I.OmniRoute làm được gì
A.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.
B.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á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).
D.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ễ.
E.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.
F.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.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js:
package.jsonyê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ó
Dockerfilevà nhiều filedocker-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.
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.
III.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.
- Kiểm tra Node.jsXem 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 npmTải repo về bằng git, hoặc dùng gói npm tên omniroute
- Tạo file .envSao chép .env.example rồi điền các khoá bí mật
- Chạy OmniRouteLàm theo mục Quick Start trong README hoặc dùng Docker
- Nối nhà cung cấpVào trang quản trị, thêm tài khoản và lấy key OmniRoute
A.Kiểm tra Node.js
Mở terminal (trên Windows: PowerShell hoặc Windows Terminal) và gõ:
node --versionKế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.
B.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:
git clone https://github.com/cheaper-inference/OmniRoute.git
cd OmniRouteLệ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à:
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.
C.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:
Copy-Item .env.example .envTrên macOS/Linux:
cp .env.example .envSau đó 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.
D.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.
E.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í.
IV.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:
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.
V.Dùng vào việc thật
A.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.
B.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
C.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.
D.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.
VI.Lỗi hay gặp và cách xử lý
A.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 đó.
B.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.
C.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.
D.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.
E.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.
VII.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.


