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) mã nguồn mở, giấy phép MIT. Bạn kết nối tài khoản của các nhà cung cấp vào một nơi, rồi mọi công cụ như Claude Code, Codex, Cursor, Cline chỉ cần gọi một địa chỉ duy nhất. Cài bằng gói npm omniroute hoặc Docker, người mới làm được nhưng cần Node phiên bản mới.
OmniRoute là một cổng AI (AI gateway) mã nguồn mở: bạn chạy nó trên máy mình, và 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ả, repo gom khoảng 375 nhà cung cấp (hơn 150 nơi có tầng miễn phí) và hơn 1.400 mô hình như Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax.
Vấn đề nó giải quyết rất đời thường. Bạn có vài tài khoản AI, mỗi nơi một hạn mức, một cách gọi riêng. Dùng hết hạn mức ở nơi này thì phải tự đổi sang nơi khác, sửa cấu hình, thử lại. OmniRoute đứng ở giữa: bạn trỏ công cụ của mình vào nó, còn việc chọn nhà cung cấp nào, khi nào đổi sang nhà khác, nó lo.
Nên dùng nếu bạn là lập trình viên (kể cả mới học) hay dùng Claude Code, Codex, Cursor, OpenCode, Cline, Copilot, hoặc là người làm văn phòng, kinh doanh nhỏ muốn gom nhiều nguồn AI vào một chỗ để đỡ rối. Điểm đáng giá nhất là tính năng tự chuyển nhà cung cấp theo hạn mức còn lại, cộng với việc có thể dùng các tầng miễn phí của bên thứ ba. Repo hiện có khoảng 86.974 sao và 13.296 fork, viết bằng TypeScript, giấy phép MIT.
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 nhà khác khi hết hạn mức.
I.OmniRoute làm được gì
A.Một địa chỉ cho mọi công cụ
Bạn chỉ nhớ một địa chỉ (README dùng http://localhost:20128/v1/chat/completions) và một khoá của OmniRoute. Đổi nhà cung cấp phía sau không buộc bạn sửa lại từng công cụ. Lợi ích thực tế: nhà cung cấp A hết hạn mức, bạn không phải mở cài đặt của Cursor hay Cline ra sửa.
B.Chọn mô hình 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 đã kết nối và chấm điểm trực tiếp. Có sẵn vài biến thể:
auto: mặc định cân bằng, bám nhà cung cấp tốt gần nhất.auto/coding: ưu tiên chất lượng cho viết code.auto/fast: ưu tiên độ trễ thấp nhất.auto/cheap: ưu tiên rẻ nhất trên mỗi token.auto/subscription: chỉ dùng hạn mức gói thuê bao bạn đã trả, không tự chuyển sang loại tính tiền.auto/offline: ưu tiên nơi còn nhiều hạn mức nhất.
Ngoài ra còn auto/thrifty, auto/smart, auto/lkgp và auto/chaos. Nghe có vẻ nhiều, nhưng người mới cứ bắt đầu với auto là đủ.
C.Combo và 20 chiến lược định tuyến
Combo là một chuỗi mô hình mà OmniRoute chuyển qua lại tự động. Nếu hết hạn mức, nhà cung cấp lỗi hoặc chi phí tăng, nó có thể chuyển sang mô hình khỏe tiếp theo. Bạn có thể tự dựng combo với 20 chiến lược, ví dụ priority (dùng hết cái đầu rồi mới sang cái sau), round-robin (xoay vòng), cost-optimized (rẻ nhất theo giá trong danh mục), headroom (nơi còn nhiều hạn mức nhất), pipeline (đầu ra bước này làm đầu vào bước sau).
D.Bảng theo dõi tầng miễn phí
Trên trang quản trị có mục /dashboard/free-tiers thống kê các tầng miễn phí. README nói con số gộp khoảng 1,62 tỷ token mỗi tháng, nhưng đây là ước tính cộng dồn từ các tầng miễn phí của bên thứ ba, không phải OmniRoute tặng token. Bạn phải tự đăng ký tài khoản ở từng nhà cung cấp, và mỗi nơi tự quy định giới hạn, tình trạng và điều khoản.
E.Nén token
Mô tả của tác giả nhắc tới nén RTK + Caveman giúp tiết kiệm 15–95% token. README phần mình có không giải thích cách bật, nên bạn xem thêm trong tài liệu của repo (thư mục docs/).
F.Các tính năng khác
Theo README và mô tả: hỗ trợ MCP/A2A, có bản Desktop/PWA, chế độ không giao diện serve --headless, API tra cứu mô hình /v1/models/query, lập lịch theo hạn mức (Quota-Share) và theo dõi hạn mức trực tiếp.
II.Cần chuẩn bị gì
- Node.js
package.jsonyêu cầu Node từ 22.22.2 trở lên (dưới 23), hoặc từ 24.0.0 đến dưới 27. Node quá cũ sẽ không chạy. - Tài khoản nhà cung cấpREADME nhấn mạnh "mang tài khoản của bạn tới" (bring your own provider accounts). Bạn đăng ký và lấy khoá ở các nhà cung cấp muốn dùng.
- Dockerkhông bắt buộc, nhưng repo có
Dockerfile,docker-compose.ymlvà vài bản compose khác nếu bạn thích chạy bằng container. - Hệ điều hành và phần cứngtư liệu mình có chưa nêu yêu cầu cụ thể. Repo có cả Dockerfile lẫn bản Electron (Desktop), nên có vẻ chạy được nhiều nền tảng, nhưng bạn nên kiểm tra lại trong tài liệu.
- Cấu hìnhfile
.env.exampleliệt kê các biến nhưJWT_SECRET,API_KEY_SECRET,INITIAL_PASSWORD,STORAGE_ENCRYPTION_KEY,PORT,REQUIRE_API_KEY. Bạn sẽ cần điền một số biến này nếu chạy từ mã nguồn hoặc Docker.
OmniRoute giữ khoá và thông tin đăng nhập của các nhà cung cấp trên máy bạn. Đặt mật khẩu và các khoá bí mật riêng, đừng để mặc định, đừng công khai địa chỉ máy chạy OmniRoute ra Internet nếu chưa bật yêu cầu khoá API. Hạn mức miễn phí có thể thay đổi bất cứ lúc nào, và một số nhà cung cấp có thể tính phí nếu bạn dùng vượt gói.
III.Cài đặt từng bước
Lưu ý trước: phần README mình có chưa ghi lệnh cài đặt cụ thể (mục Install bị cắt khỏi đoạn tư liệu). Mình chỉ biết repo có gói npm tên omniroute kèm lệnh CLI, và có Dockerfile, docker-compose.yml, Makefile. Vì vậy mình sẽ không bịa lệnh cài. Bạn mở mục Install trong README trên GitHub, hoặc thư mục docs/ và examples/quickstart/, để lấy lệnh chính xác.
- Kiểm tra NodeXác nhận máy đang dùng Node đúng phiên bản yêu cầu
- Lấy mã nguồnTải repo về máy bằng git clone
- Điền cấu hìnhSao chép .env.example thành .env rồi điền khoá bí mật
- Chạy OmniRouteLàm theo mục Install trong README hoặc dùng docker-compose.yml
- Kết nối nhà cung cấpMở trang quản trị, thêm tài khoản nhà cung cấp, lấy khoá OmniRoute
A.Kiểm tra phiên bản Node
Mở terminal (trên Windows: PowerShell hoặc Terminal; trên macOS/Linux: Terminal) rồi gõ:
node --versionKết quả phải là phiên bản trong khoảng README yêu cầu (từ 22.22.2, hoặc 24 trở lên và dưới 27). Nếu thấp hơn, bạn cần nâng cấp Node trước, nếu không các bước sau sẽ lỗi.
B.Lấy mã nguồn về máy
Lệnh này tải toàn bộ repo về một thư mục mới, rồi bạn đi vào thư mục đó. Chỗ người mới hay vấp: phải chạy các lệnh sau ở trong thư mục này, không phải thư mục khác.
git clone https://github.com/cheaper-inference/OmniRoute.git
cd OmniRouteC.Điền cấu hình
Repo có file mẫu .env.example. Bạn sao chép nó thành .env rồi mở ra điền. Các biến quan trọng cần để ý gồm JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD và STORAGE_ENCRYPTION_KEY. Hãy tự đặt giá trị riêng, đừng dùng giá trị ví dụ.
cp .env.example .envTrên PowerShell, lệnh sao chép tương đương là Copy-Item .env.example .env. Biến PORT quyết định cổng chạy; ví dụ trong README dùng cổng 20128.
D.Chạy OmniRoute
Có hai hướng, bạn chọn một:
- Qua gói npm
omniroute: gói này có lệnh CLI. README phần mình có chỉ nhắcserve --headless(chế độ không giao diện), chưa thấy lệnh khởi động đầy đủ. Hãy chép đúng lệnh từ mục Install của README. - Qua Docker: repo có
docker-compose.yml. Nếu bạn đã cài Docker, lệnh phổ thông để chạy một file compose là:
docker compose up -dLệnh này đọc docker-compose.yml ở thư mục hiện tại và chạy nền. Còn có các bản docker-compose.selfhost.yml, docker-compose.prod.yml; mục đích của từng bản được nêu trong tài liệu repo, bạn nên đọc trước khi chọn.
E.Kết nối nhà cung cấp và lấy khoá
Sau khi OmniRoute chạy, mở trang quản trị (Dashboard) trong trình duyệt. Thêm ít nhất một nhà cung cấp mà bạn có tài khoản. Sau đó vào Dashboard → Endpoints để sao chép khoá OmniRoute của bạn. Khoá này dùng ở bước kiểm tra bên dưới.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra theo README: gửi một yêu cầu thử tới địa chỉ cục bộ. Thay YOUR_OMNIROUTE_KEY bằng khoá bạn vừa sao chép:
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 thành công, bạn nhận về một phản hồi dạng JSON có câu trả lời của mô hình. Lưu ý quan trọng từ README: auto cần có ít nhất một tuyến phù hợp. Máy mới cài, chưa kết nối nhà cung cấp nào, có thể chưa có tuyến nào dùng được. Một số nhà cung cấp không cần khoá cũng có thể từ chối ứng dụng bên thứ ba. Ngoài ra, nhà cung cấp gắn nhãn tos: avoid (kể cả Kiro) bị loại khỏi định tuyến tự động theo mặc định, và kết nối tài khoản cũng không đổi được điều đó.
Nếu muốn chạy thử nhanh bằng ngôn ngữ khác, README nói thư mục examples/quickstart/ có 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, Cursor hay Cline mà hay hết hạn mức
Bối cảnh: bạn code cả ngày, đang dùng dở thì hạn mức của một nhà cung cấp cạn. Cách làm: kết nối vài nhà cung cấp vào OmniRoute, trong công cụ của bạn trỏ địa chỉ API về OmniRoute (cổng 20128 trong ví dụ) và đặt mô hình là auto/coding. Kết quả: khi nơi này hết quota, cổng tự chuyển sang nơi khác còn khả dụng, bạn không phải dừng việc để sửa cấu hình.
Đừng ngồi canh hạn mức từng nơi, hãy để một cổng duy nhất lo việc đổi chỗ giúp bạn.
Ông T
B.Sinh viên hoặc người mới học lập trình muốn tiết kiệm
Bối cảnh: bạn chưa muốn trả tiền thuê bao AI. Cách làm: đăng ký tài khoản ở vài nhà cung cấp có tầng miễn phí, kết nối vào OmniRoute, dùng auto/cheap hoặc xem trang /dashboard/free-tiers để biết mình còn bao nhiêu hạn mức. Kết quả: bạn có chỗ nhìn tổng quan thay vì mở từng trang của từng nhà cung cấp. Hãy nhớ đây là tầng miễn phí của bên thứ ba, có thể thay đổi hoặc biến mất.
C.Chủ shop hay nhân viên văn phòng cần viết nội dung, trả lời khách
Bối cảnh: bạn dùng một ứng dụng hoặc script nhỏ gọi AI để soạn mô tả sản phẩm hay trả lời email. Cách làm: nhờ người biết lập trình trỏ ứng dụng đó về địa chỉ OmniRoute, dùng mô hình auto. Kết quả: khi một nhà cung cấp lỗi hoặc hết quota, ứng dụng vẫn chạy nhờ cơ chế dự phòng, bạn không phải sửa gì.
D.Nhóm nhỏ cần kiểm soát chi phí
Bối cảnh: cả nhóm đang đã có gói thuê bao AI và không muốn bị tính phí ngoài ý muốn. Cách làm: dùng auto/subscription, theo README chỉ dùng hạn mức thuê bao bạn đã trả và "fails closed", tức là không tự chuyển sang loại tính tiền. Kết quả: nếu hết hạn mức gói thì yêu cầu thất bại thay vì tốn thêm tiền ngoài dự tính.
VI.Lỗi hay gặp và cách xử lý
A.Node không đủ phiên bản
Dấu hiệu: lệnh cài hoặc chạy báo lỗi ngay, hoặc cảnh báo về phiên bản engine. Cách xử lý: chạy node --version, nâng Node lên phiên bản README yêu cầu rồi thử lại.
B.Gọi auto nhưng không có phản hồi hoặc báo không có tuyến phù hợp
Nguyên nhân thường gặp: bạn chưa kết nối nhà cung cấp nào, hoặc nhà cung cấp bạn nối nằm trong nhóm bị loại khỏi tự động (như tos: avoid). Cách xử lý: vào dashboard thêm một nhà cung cấp hợp lệ, kiểm tra lại khoá, rồi thử lại; hoặc chỉ định thẳng mô hình thay vì auto.
C.Lỗi xác thực (401 hoặc tương tự)
Thường do dán sai khoá OmniRoute, thiếu chữ Bearer trước khoá, hoặc nhầm khoá OmniRoute với khoá của nhà cung cấp. Cách xử lý: lấy lại khoá ở Dashboard → Endpoints và dán đúng định dạng như ví dụ ở trên.
D.Cổng bị chiếm hoặc không kết nối được
Nếu cổng đã có chương trình khác dùng, OmniRoute sẽ không khởi động được. Đổi giá trị PORT trong .env sang cổng trống, khởi động lại, và đổi cả địa chỉ trong công cụ của bạn cho khớp.
E.Hạn mức miễn phí bỗng hết hoặc nhà cung cấp từ chối
Đây là chuyện của bên thứ ba: README cho biết số liệu tầng miễn phí được rà soát định kỳ và "có thể tăng hoặc giảm". Cách xử lý: kiểm tra /dashboard/free-tiers, thêm nhà cung cấp dự phòng, và đừng xây quy trình quan trọng chỉ dựa vào một tầng miễn phí.
VII.Có nên dùng không
Điểm mạnh. Một địa chỉ cho mọi công cụ, tự chuyển nhà cung cấp theo hạn mức, nhiều chiến lược định tuyến, bảng theo dõi tầng miễn phí, giấy phép MIT và cộng đồng lớn (README nói hơn 900 người đóng góp). Repo còn được cập nhật trong vài tháng gần đây.
Giới hạn. Số lượng tính năng rất lớn, người mới dễ choáng, nên bắt đầu từ auto rồi tìm hiểu dần. Bạn vẫn phải tự đăng ký và quản lý tài khoản ở từng nhà cung cấp. Hạn mức miễn phí không do OmniRoute cam kết và có thể thay đổi. Phần cài đặt trong tư liệu mình có chưa đầy đủ, nên bạn cần đọc README gốc cho lệnh chính xác. Các nhà cung cấp riêng lẻ có điều khoản riêng, bạn nên đọc trước khi dùng.
Khi nào chọn cách khác. Nếu bạn chỉ dùng một nhà cung cấp, không bao giờ hết hạn mức, thì một cổng trung gian là thừa. Nếu bạn không muốn tự chạy và quản lý một dịch vụ trên máy, hãy dùng thẳng ứng dụng của nhà cung cấp. README có tài liệu so sánh với 9router, OpenRouter, CLIProxyAPI và LiteLLM (docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md), đáng đọc nếu bạn đang cân nhắc giữa các công cụ cùng loại.
Câu hỏi thường gặp
OmniRoute có miễn phí không?
Bản thân OmniRoute là mã nguồn mở giấy phép MIT, dùng miễn phí. Các tầng miễn phí đến từ nhà cung cấp bên thứ ba, bạn phải tự đăng ký và mỗi nơi tự quy định giới hạn. Con số khoảng 1,62 tỷ token mỗi tháng trong README chỉ là ước tính cộng dồn, không phải OmniRoute tặng token.
Cần Node phiên bản nào?
package.json yêu cầu Node từ 22.22.2 trở lên và dưới 23, hoặc từ 24.0.0 đến dưới 27. Bạn chạy node --version để kiểm tra trước khi cài.
Có cần GPU không?
Tư liệu mình có không nhắc yêu cầu GPU. OmniRoute là cổng định tuyến tới các nhà cung cấp, nên về nguyên tắc mô hình chạy ở phía nhà cung cấp, không phải trên máy bạn. Repo có một file docker-compose.ollama-local.yml cho trường hợp chạy mô hình cục bộ, nhưng chi tiết phần cứng thì chưa có thông tin.
Chạy trên Windows được không?
Tư liệu chưa nêu rõ danh sách hệ điều hành hỗ trợ. Repo có Dockerfile và thư mục electron (bản Desktop), nên có nhiều cách chạy. Bạn xem mục Install và tài liệu trong repo để biết chính xác.
Dữ liệu và khoá của tôi có an toàn không?
Bạn tự chạy OmniRoute trên máy mình, và .env.example có các biến như STORAGE_ENCRYPTION_KEY, JWT_SECRET, REQUIRE_API_KEY để bảo vệ lưu trữ và truy cập. Tuy vậy, yêu cầu của bạn vẫn được gửi tới nhà cung cấp bạn chọn, nên chính sách của họ vẫn áp dụng. README có mục riêng về chế độ riêng tư, bạn nên đọc trước khi dùng với dữ liệu nhạy cảm.
OmniRoute khác OpenRouter hay LiteLLM thế nào?
Cả ba đều là lớp trung gian gọi nhiều mô hình qua một địa chỉ. README có tài liệu so sánh chi tiết với 9router, OpenRouter, CLIProxyAPI và LiteLLM trong docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md. Điểm nhấn của OmniRoute theo mô tả là định tuyến theo hạn mức, nhiều tầng miễn phí và tương thích sẵn với các công cụ lập trình như Claude Code, Codex, Cursor.
Dùng với Claude Code, Cursor, Cline thế nào?
Mô tả của tác giả nói OmniRoute hoạt động với Claude Code, Codex, Cursor, OpenCode, Cline và Copilot. Ý tưởng chung là trỏ công cụ về địa chỉ OmniRoute và dùng khoá OmniRoute. Cách cấu hình chi tiết cho từng công cụ chưa có trong tư liệu mình có, bạn xem thêm trong docs của repo.


