OmniRoute: một cổng AI miễn phí cho Claude Code, Cursor, Cline — 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 AI gateway giấy phép MIT viết bằng TypeScript. Bạn kết nối tài khoản của các nhà cung cấp AI, rồi mọi công cụ (Claude Code, Codex, Cursor, Cline…) chỉ cần gọi vào một địa chỉ duy nhất. Khi một nhà hết hạn mức hoặc lỗi, OmniRoute tự chuyển sang nhà khác. Việc cài khá nhẹ nếu bạn đã có Node.js, nhưng phần cấu hình nhà cung cấp cần chút kiên nhẫn.
OmniRoute là một "cổng AI" (AI gateway) chạy trên máy của bạn. Nó cho bạn một địa chỉ API duy nhất, và đằng sau địa chỉ đó là hàng trăm nhà cung cấp mô hình AI như Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Theo mô tả của tác giả, repo hiện nối được khoảng 375 nhà cung cấp (hơn 150 nhà có gói miễn phí) và hơn 1.400 mô hình.
Vấn đề nó giải quyết rất đời thường. Bạn dùng Claude Code, Cursor hay Cline để viết code, nhưng đang làm dở thì hết hạn mức, hoặc nhà cung cấp bị lỗi, hoặc hoá đơn phình ra. Thay vì tự đổi key, đổi cấu hình, bạn đặt OmniRoute ở giữa. Nó theo dõi hạn mức và tự chuyển sang mô hình khác còn dùng được. Repo hiện có khoảng 86.974 sao và 13.296 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
Bạn nên đọc bài này nếu bạn là lập trình viên, hoặc người làm văn phòng có dùng trợ lý AI viết code mỗi ngày và muốn tiết kiệm. Điểm đáng giá nhất là chế độ auto: bạn không cần tự ghép chuỗi mô hình, chỉ cần ghi auto vào trường model.
cheaper-inference/OmniRoute
OmniRoute là cổng AI mã nguồn mở: 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ì
Một địa chỉ cho mọi công cụ. OmniRoute nói chuyện theo kiểu giống API OpenAI. Mô tả của tác giả nói nó chạy được với Claude Code, Codex, Cursor, OpenCode, Cline và Copilot. Bạn khỏi phải cấu hình riêng cho từng nhà cung cấp trong từng công cụ.
Tự chuyển nhà khi hết hạn mức (combo). Một "combo" là chuỗi các mô hình mà OmniRoute tự đi qua. Nếu hạn mức cạn, nhà cung cấp lỗi hoặc chi phí tăng, nó chuyển sang mô hình khỏe kế tiếp. Lợi ích thực tế: phiên làm việc của bạn không bị đứt giữa chừng.
Chế độ auto không cần cấu hình. Bạn ghi model là auto, OmniRoute tự dựng một combo ảo từ các nhà cung cấp bạn đã kết nối và chấm điểm trực tiếp. README liệt kê các biến thể:
auto: cân bằng, bám nhà cung cấp chạy tốt gần nhất.auto/coding: ưu tiên chất lượng khi 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 bao giờ tự tính phí thêm.auto/thrifty: dùng hạn mức gói trước, rồi mới xuống dần các lựa chọn trả phí rẻ nhất.
20 chiến lược định tuyến nếu muốn tự build. Ví dụ priority (hết cái này mới sang cái kia), round-robin (xoay vòng), cost-optimized (tối thiểu chi phí mỗi yêu cầu), headroom (chọn nhà còn nhiều hạn mức nhất), fusion (hỏi nhiều mô hình rồi để một "giám khảo" tổng hợp một câu trả lời), pipeline (đầu ra bước này làm đầu vào bước sau).
Bảng theo dõi gói miễn phí. README nói trang /dashboard/free-tiers tính tổng hạn mức token miễn phí từ các nhà cung cấp bạn kết nối. Con số này chỉ là ước tính từ các gói miễn phí của bên thứ ba, không phải OmniRoute tặng token. Mỗi nhà tự quyết định giới hạn và điều khoản.
Nén token. Mô tả của tác giả nhắc cơ chế nén RTK + Caveman, tiết kiệm 15-95% token. Mình chưa có phần giải thích chi tiết trong tư liệu, nên bạn xem trong thư mục docs/ của repo trước khi trông chờ vào con số này.
Các thứ đi kèm. MCP/A2A, giao diện Desktop/PWA, chế độ serve --headless (chạy không giao diện), và API tìm mô hình /v1/models/query, theo bảng phiên bản trong README.
II.Cần chuẩn bị gì
- Node.js:
package.jsonyêu cầu Node từ 22.22.2 trở lên nhưng dưới 23, hoặc từ 24.0.0 đến dưới 27. Nghĩa là Node 23 không được, bạn cần tránh đúng bản này. - Tài khoản nhà cung cấp: README nhấn mạnh "bring your own provider accounts": bạn tự đăng ký tài khoản và lấy khoá ở những nhà cung cấp muốn dùng. OmniRoute không tặng token.
- Docker (không bắt buộc): repo có
Dockerfilevà nhiều filedocker-compose, nên bạn có thể chạy bằng Docker nếu quen. - Phần cứng và hệ điều hành: tư liệu mình có không nói yêu cầu GPU hay hệ điều hành cụ thể. Đây là cổng gọi API tới nhà cung cấp, nên về nguyên tắc không cần GPU, nhưng bạn hãy xác nhận trong
docs/. - Biến cấu hình: file
.env.examplecó các biến nhưJWT_SECRET,API_KEY_SECRET,INITIAL_PASSWORD,STORAGE_ENCRYPTION_KEY,PORT,REQUIRE_API_KEY. Phần dưới sẽ nói cách dùng.
Các key bạn nhập vào OmniRoute là chìa khoá tài khoản AI của bạn. Đừng chụp màn hình, đừng đưa file .env lên GitHub hay gửi cho người khác. Đặt mật khẩu riêng, đừng để mặc định. Chi phí vẫn do nhà cung cấp tính, nên với gói trả phí hãy kiểm tra hạn mức trước.
III.Cài đặt từng bước
Lưu ý trước: phần README mình nhận được bị cắt trước mục "Install" chi tiết. Vì vậy mình chỉ chép đúng những gì có trong tư liệu, và chỉ ra chỗ bạn cần đọc thêm.
- Kiểm tra Node.jsĐảm bảo Node nằm trong khoảng package.json yêu cầu
- Cài OmniRouteDùng gói npm omniroute hoặc chạy bằng Docker từ mã nguồn
- Cấu hình file .envSao chép .env.example và điền các biến bảo mật
- Mở bảng điều khiểnVào Dashboard để kết nối nhà cung cấp
- Lấy key OmniRouteCopy key ở Dashboard → Endpoints để gọi API
A.Kiểm tra phiên bản Node.js
Mở terminal (trên Windows là PowerShell hoặc Terminal, trên macOS/Linux là Terminal) và gõ:
node --versionKết quả phải là 22.22.2 trở lên (nhưng không phải dòng 23) hoặc 24 đến 26. Nếu thấp hơn, bạn cần cài lại Node trước. Đây là chỗ người mới hay vấp nhất.
B.Cài OmniRoute
Tư liệu cho biết gói npm tên omniroute và có lệnh CLI. Cách cài toàn cục phổ thông là:
npm install -g omnirouteLệnh này tải gói về và đưa lệnh CLI vào máy bạn. Bảng phiên bản trong README có nhắc serve --headless cho chế độ chạy không giao diện, nhưng phần README mình có chưa ghi rõ lệnh khởi động đầy đủ. Hãy xem phần Install trong README gốc trên GitHub hoặc thư mục docs/, hoặc chạy omniroute --help để xem danh sách lệnh.
Nếu bạn thích Docker, repo có Dockerfile và docker-compose.yml. Cách lấy mã nguồn:
git clone https://github.com/cheaper-inference/OmniRoute.git
cd OmniRouteSau đó dùng file docker-compose.yml ở thư mục gốc. README chưa ghi lệnh Docker cụ thể trong phần mình có, nên hãy đọc ghi chú trong chính file đó và trong docs/ trước khi chạy.
C.Chuẩn bị file .env
Repo có sẵn file mẫu .env.example. Bạn sao chép thành .env rồi điền giá trị:
cp .env.example .envTrên PowerShell, lệnh tương đương là Copy-Item .env.example .env. Trong file này có các biến như JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD và STORAGE_ENCRYPTION_KEY. Tên biến mình biết, còn ý nghĩa và cách đặt giá trị an toàn thì bạn đọc ghi chú ngay trong .env.example. Đừng giữ giá trị mẫu cho môi trường dùng thật.
D.Mở bảng điều khiển và kết nối nhà cung cấp
Từ ví dụ trong README, OmniRoute lắng nghe ở cổng 20128 trên máy bạn, tức địa chỉ http://localhost:20128. Bạn mở trình duyệt vào bảng điều khiển (Dashboard), thêm nhà cung cấp mà bạn có tài khoản. README lưu ý: máy mới cài có thể chưa có đích nào dùng được mà không cần key, và có nhà cung cấp không cho công cụ bên thứ ba dùng. Nhà cung cấp gắn nhãn tos: avoid (ví dụ Kiro) bị loại khỏi định tuyến tự động theo mặc định, kết nối tài khoản cũng không đổi được điều đó.
E.Lấy key OmniRoute
Sau khi kết nối nhà cung cấp, vào Dashboard → Endpoints để copy key OmniRoute. Key này là thứ bạn dán vào Claude Code, Cursor, Cline… Nó khác với key gốc của từng nhà cung cấp.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra duy nhất README đưa ra là gọi thử API. Bạn thay YOUR_OMNIROUTE_KEY bằng key vừa copy:
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 mọi thứ ổn, bạn nhận về một câu trả lời dạng JSON từ một mô hình nào đó. Nếu báo lỗi, rất có thể bạn chưa kết nối nhà cung cấp nào đủ điều kiện cho auto (xem phần lỗi bên dưới). Trên Windows PowerShell, curl có thể là bí danh của lệnh khác, nên hãy dùng curl.exe thay cho curl và để nguyên phần còn lại, hoặc chạy trong Git Bash.
Bạn cũng có thể mở trang /dashboard/free-tiers để xem ước tính hạn mức miễn phí của các nhà cung cấp đã kết nối. README cũng có thư mục examples/quickstart/ với script mẫu cho Python, Node.js, PHP và cURL, tiện nếu bạn muốn gọi từ code.
V.Dùng vào việc thật
A.Lập trình viên không muốn bị đứt mạch vì hết hạn mức
Bạn đang dùng Claude Code hoặc Cline để sửa một dự án. Thay vì trỏ thẳng vào một nhà cung cấp, bạn trỏ công cụ vào http://localhost:20128/v1 với key OmniRoute và đặt model là auto/coding. Khi một nhà cạn hạn mức, OmniRoute chuyển sang mô hình khác trong số đã kết nối. Kết quả: bạn không phải dừng lại đổi key giữa chừng. Cách điền cấu hình cụ thể trong từng công cụ, bạn xem ở docs/, vì mình chưa có hướng dẫn riêng cho từng công cụ.
Đặt một cổng ở giữa, bạn đổi nhà cung cấp mà không phải đổi thói quen làm việc.
Ông T
B.Sinh viên hoặc người mới học code, muốn dùng gói miễn phí
Bạn chưa muốn trả tiền. Bạn đăng ký vài nhà cung cấp có gói miễn phí, thêm vào OmniRoute, rồi dùng auto/cheap. OmniRoute ưu tiên mô hình rẻ nhất theo token. Bạn mở /dashboard/free-tiers để biết mình còn bao nhiêu hạn mức. Kết quả: bạn có một chỗ để theo dõi, thay vì nhớ từng trang của từng nhà. Hãy nhớ mỗi nhà tự đặt giới hạn và điều khoản, và các con số thay đổi theo thời gian.
C.Nhóm nhỏ dùng chung một cổng
Một công ty nhỏ có vài lập trình viên. Họ chạy OmniRoute trên một máy chủ chung, và mỗi người lấy một key OmniRoute riêng để gọi vào. Repo có biến REQUIRE_API_KEY trong .env.example và các file docker-compose.selfhost.yml, docker-compose.prod.yml cho việc tự lưu trữ. Mình chưa có tài liệu chi tiết về phân quyền nhiều người dùng, nên hãy đọc docs/ và SECURITY.md trước khi mở ra mạng.
D.Gọi từ script của chính bạn
Bạn có một đoạn script Python hoặc Node.js cần gọi mô hình AI. Bạn dùng lại ví dụ trong examples/quickstart/, đổi địa chỉ sang http://localhost:20128/v1/chat/completions và dùng key OmniRoute. Kết quả: đổi nhà cung cấp chỉ bằng cách đổi tên model, không phải viết lại phần gọi API.
VI.Lỗi hay gặp và cách xử lý
Cài hoặc chạy báo sai phiên bản Node. Gói yêu cầu Node 22.22.2 trở lên nhưng loại bản 23. Chạy node --version để xem, rồi cài lại đúng bản.
Gọi model: auto mà báo không có đường đi hợp lệ. README nói auto cần ít nhất một tuyến đủ điều kiện, và máy mới cài có thể chưa có đích nào không cần key. Hãy vào Dashboard kết nối ít nhất một nhà cung cấp có tài khoản thật. Nhà cung cấp gắn tos: avoid bị loại khỏi auto, nên đừng trông chờ nó.
Bị từ chối xác thực (401). Có thể bạn dán nhầm key gốc của nhà cung cấp thay vì key OmniRoute, hoặc quên tiền tố Bearer . Copy lại key ở Dashboard → Endpoints.
Cổng đã bị chiếm. Ví dụ trong README dùng cổng 20128, và .env.example có biến PORT. Nếu cổng bận, hãy tắt chương trình đang dùng cổng đó hoặc đổi PORT trong .env.
Một nhà cung cấp từ chối công cụ bên thứ ba. README cảnh báo có nhà cung cấp không nhận client bên thứ ba. Khi đó đừng cố ép, hãy chọn nhà cung cấp khác trong cùng combo.
VII.Có nên dùng không
Điểm mạnh: miễn phí và giấy phép MIT; một địa chỉ cho nhiều nhà cung cấp; tự chuyển nhà khi hết hạn mức; chạy tự lưu trữ trên máy bạn; cộng đồng lớn và repo còn được cập nhật. README cũng khá thẳng thắn khi nói số liệu hạn mức miễn phí là ước tính, tăng giảm theo từng nhà.
Giới hạn: dự án rất lớn (hàng trăm nhà cung cấp, 20 chiến lược định tuyến), nên người mới dễ choáng. Bạn vẫn phải tự đăng ký tài khoản và quản lý key. Gói miễn phí do bên thứ ba cấp, nên có thể đổi bất cứ lúc nào. Mình chưa có thông tin về yêu cầu phần cứng hay hệ điều hành hỗ trợ.
Khi nào chọn cách khác: nếu bạn chỉ dùng đúng một nhà cung cấp và không bao giờ hết hạn mức, một cổng ở giữa là thừa. Nếu bạn cần dịch vụ thương mại có hỗ trợ chính thức, hãy cân nhắc các dịch vụ trả phí. README có file so sánh với 9router, OpenRouter, CLIProxyAPI và LiteLLM tại docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md, bạn nên đọc trước khi quyết định.
Câu hỏi thường gặp
OmniRoute có miễn phí không?
Bản thân OmniRoute là phần mềm mã nguồn mở, giấy phép MIT, nên dùng miễn phí. Tuy nhiên các nhà cung cấp AI phía sau có thể tính phí hoặc có gói miễn phí riêng, và mỗi nhà tự quyết hạn mức. OmniRoute không tặng token.
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 nhưng dưới 23, hoặc từ 24.0.0 đến dưới 27. Nghĩa là Node dòng 23 không nằm trong khoảng hỗ trợ. Bạn chạy `node --version` để kiểm tra.
OmniRoute có cần GPU không?
Tư liệu mình có không nói về yêu cầu GPU. OmniRoute là cổng chuyển yêu cầu tới các nhà cung cấp AI, nên không phải công cụ chạy mô hình trên máy bạn theo mô tả. Bạn nên xem thư mục docs/ để chắc chắn.
Dùng với Claude Code, Cursor, Cline được không?
Có. Mô tả của tác giả nói OmniRoute chạy với Claude Code, Codex, Cursor, OpenCode, Cline và Copilot. Cách điền cấu hình cụ thể cho từng công cụ mình chưa có trong tư liệu, bạn xem tài liệu của repo.
Chế độ model "auto" hoạt động thế nào?
Khi bạn đặt model là `auto`, OmniRoute dựng một combo ảo từ các nhà cung cấp bạn đã kết nối và chấm điểm trực tiếp. Có các biến thể như `auto/coding`, `auto/fast`, `auto/cheap`. Nó cần ít nhất một tuyến đủ điều kiện, nên máy mới cài chưa kết nối nhà cung cấp có thể báo lỗi.
Dữ liệu và key của tôi có an toàn không?
OmniRoute chạy tự lưu trữ, và .env.example có các biến như JWT_SECRET, API_KEY_SECRET, STORAGE_ENCRYPTION_KEY cho việc bảo mật. Mình chưa có thông tin chi tiết về cách lưu trữ dữ liệu. Hãy tự đặt giá trị riêng, không đưa file .env lên mạng, và đọc SECURITY.md trong repo.
Chạy được trên Windows không?
Tư liệu mình có không ghi rõ danh sách hệ điều hành. Gói là Node.js nên về nguyên tắc chạy được nơi có Node phù hợp, và repo cũng có Dockerfile. Bạn nên xác nhận trong README gốc hoặc docs/ của repo.


