OmniRoute

1. OmniRoute là gì?

OmniRoute là một "cổng trung chuyển" AI chạy ngay trên máy bạn. Thay vì mỗi công cụ AI phải cấu hình riêng với từng nhà cung cấp mô hình (OpenAI, Anthropic, Google, DeepSeek…), bạn trỏ tất cả về một địa chỉ duy nhất trên máy mình; OmniRoute lo việc chuyển yêu cầu tới nhà cung cấp phù hợp. Khi một nhà cung cấp hết hạn mức hoặc bị lỗi, nó tự chuyển sang nhà cung cấp khác còn dùng được. Nó cũng nén bớt nội dung gửi đi để tiết kiệm token (đơn vị tính tiền của các mô hình AI).

Phần mềm miễn phí, mã nguồn mở, giấy phép MIT. README ghi nó kết nối được hơn 350 nhà cung cấp, trong đó hơn 150 có gói miễn phí. Bản thân OmniRoute không bán mô hình AI: gói miễn phí hay trả phí là của từng nhà cung cấp, và dự án nói rõ các con số hạn mức miễn phí thay đổi theo thời gian.

Nói thẳng: OmniRoute chủ yếu dành cho người dùng các công cụ lập trình bằng AI như Claude Code, Codex, Cursor, Cline. Nó có bảng điều khiển trên trình duyệt khá dễ nhìn và có bản cài dạng ứng dụng, nhưng giá trị của nó chỉ rõ khi bạn có một công cụ AI cần nối vào.

Hợp với bạn nếu:

• Bạn dùng công cụ lập trình AI và hay bị chặn vì hết hạn mức giữa chừng.
• Bạn muốn tận dụng các gói miễn phí của nhiều nhà cung cấp qua một chỗ.
• Bạn muốn nhìn thấy mình đang tiêu bao nhiêu token, bao nhiêu tiền.

Chưa hợp nếu:

• Bạn chỉ cần một ứng dụng chat AI để hỏi đáp hằng ngày. Dùng thẳng ứng dụng chat sẽ đơn giản hơn nhiều.
• Bạn chưa dùng công cụ nào có ô cấu hình "Base URL" và "API Key".
• Máy bạn ít dung lượng trống: file cài ứng dụng nặng từ khoảng 300 MB đến khoảng 680 MB tùy hệ điều hành.

2. Cần chuẩn bị gì?

Tùy cách cài bạn chọn ở mục 3:

• Cách 1, ứng dụng máy tính: không cần cài gì trước. Cần Windows, macOS hoặc Linux và từ khoảng 300 đến 680 MB trống để tải file cài (Windows khoảng 580 MB, macOS khoảng 670 MB, Linux khoảng 310 đến 430 MB).
• Cách 2, dòng lệnh: cần Node.js, phần mềm nền để chạy công cụ viết bằng JavaScript. OmniRoute yêu cầu bản từ 22.22.2 trở lên của dòng 22, hoặc bản 24 trở lên (dưới 27); dự án khuyên dùng Node.js 24 LTS. Tải tại https://nodejs.org
• Cách 3, Docker: cần Docker, công cụ chạy phần mềm trong "hộp" đóng gói sẵn. Tải tại https://www.docker.com
• Điện thoại Android: chạy được qua ứng dụng Termux (một cửa sổ dòng lệnh cho Android). Đây là đường dành cho người đã quen; xem hướng dẫn riêng tại https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TERMUX_GUIDE.md

Về tài khoản: một bản cài mới đã trả lời được ngay mà không cần khóa API hay đăng ký, nhờ một nhà cung cấp miễn phí không cần đăng nhập được nối sẵn. Muốn dùng mô hình mạnh hơn, bạn kết nối thêm tài khoản hoặc khóa API của các nhà cung cấp; khoản nào mất tiền thì do nhà cung cấp đó quy định.

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

Bước 1 (cách dễ nhất): Tải ứng dụng máy tính

Mở trang phát hành chính thức:

https://github.com/diegosouzapw/OmniRoute/releases

Ở bản mới nhất (tại ngày viết là v3.8.51, phát hành 30/9/2026), kéo xuống phần Assets và tải file hợp với máy:

Hệ điều hành	File cần tải
Windows (cài đặt)	OmniRoute.Setup.3.8.51.exe
Windows (chạy luôn, không cài)	OmniRoute.exe
macOS chip Apple	OmniRoute-3.8.51-arm64.dmg
macOS chip Intel	OmniRoute-3.8.51.dmg
Linux	OmniRoute-3.8.51.AppImage hoặc file .deb

Số phiên bản trong tên file sẽ đổi theo bản mới.

Bước 2: Cài và mở ứng dụng

Windows: chạy file OmniRoute.Setup…exe, làm theo các bước, rồi mở OmniRoute từ menu Start hoặc biểu tượng ngoài màn hình.

Lưu ý: Dự án cho biết bộ cài Windows chưa được ký số, nên một số phần mềm diệt virus (tài liệu nêu tên Kaspersky) có thể báo nhầm và tự gỡ bản cài. Chỉ tải từ trang Releases chính thức ở trên. Cách xử lý nằm ở mục 5.

macOS: mở file .dmg, kéo OmniRoute.app vào thư mục Applications, rồi mở từ đó. Ứng dụng chưa được ký bằng chứng chỉ Apple; nếu macOS chặn, bấm chuột phải vào ứng dụng, chọn Open, rồi Open lần nữa. Hoặc chạy lệnh:

xattr -cr /Applications/OmniRoute.app

Linux: cấp quyền chạy cho file AppImage rồi mở:

chmod +x OmniRoute-*.AppImage
./OmniRoute-*.AppImage

Đúng là khi cửa sổ OmniRoute hiện bảng điều khiển (dashboard), và có biểu tượng OmniRoute ở khay hệ thống. Ứng dụng tự chạy máy chủ bên trong ở cổng 20128.

Cách 2: Cài bằng dòng lệnh (npm)

Kiểm tra Node.js trước:

node --version

Số in ra phải thuộc dòng 22 (từ 22.22.2) hoặc từ 24 trở lên. Sau đó:

npm install -g omniroute
omniroute

Dòng đầu tải và cài; dòng hai khởi động. Trong lúc cài bạn có thể thấy nhiều dòng npm warn; dự án xác nhận chúng vô hại, miễn là cuối cùng có dòng added … packages.

Đúng là khi trình duyệt tự mở bảng điều khiển tại http://localhost:20128. Giữ cửa sổ dòng lệnh đó mở; đóng nó là OmniRoute dừng.

Cách 3: Chạy bằng Docker

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

Sau đó mở http://localhost:20128 trên trình duyệt. Mặc định bản Docker chỉ cấp 1024 MB bộ nhớ cho OmniRoute, đủ cho bảng điều khiển và chat nhẹ. Nếu nối công cụ lập trình AI vào, tài liệu khuyên tăng lên theo bảng trong Docker Guide: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md

4. Dùng lần đầu

Bước 1: Kết nối một nhà cung cấp miễn phí

Trong bảng điều khiển, vào Providers. README gợi ý hai lựa chọn không tốn tiền để bắt đầu:

• OpenCode Free: không cần đăng nhập.
• Kiro AI: cho dùng Claude miễn phí, khoảng 50 credit mỗi tháng cho mỗi tài khoản.

Bấm kết nối và làm theo hướng dẫn trên màn hình. Đúng là khi nhà cung cấp hiện trạng thái đã kết nối.

Bước 2: Lấy khóa API của OmniRoute

Vào Endpoints, tạo một khóa API rồi chép lại. Đây là khóa do OmniRoute trên máy bạn cấp, dùng để các công cụ khác gọi vào nó; không phải khóa của OpenAI hay bất kỳ hãng nào.

Bước 3: Trỏ công cụ AI của bạn về OmniRoute

Trong phần cài đặt của công cụ (Cursor, Cline, Continue… hoặc bất kỳ công cụ nào tương thích chuẩn OpenAI), điền ba ô:

Base URL: http://localhost:20128/v1
API Key:  (khóa vừa chép ở Endpoints)
Model:    auto

Tên mô hình auto nghĩa là để OmniRoute tự chọn nhà cung cấp tốt nhất đang dùng được.

Nếu bạn cài bằng dòng lệnh và dùng Claude Code hay Codex, có thể khởi động công cụ xuyên qua OmniRoute bằng một lệnh. Ví dụ README đưa ra:

omniroute run claude --model openai/gpt-5.4

Bước 4: Kiểm tra

Thay YOUR_KEY bằng khóa của bạn rồi chạy (trên PowerShell của Windows, gõ curl.exe thay cho curl):

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

Đúng là khi bạn nhận về danh sách các mô hình đã kết nối. Từ đây, gửi một câu hỏi trong công cụ AI của bạn; câu trả lời đi qua OmniRoute và lượt dùng hiện lên trong bảng điều khiển. Hạn mức miễn phí còn lại xem ở trang /dashboard/free-tiers.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Công cụ AI báo không kết nối được	OmniRoute chưa chạy	Mở ứng dụng, hoặc chạy omniroute; với Docker: docker restart omniroute
Windows báo omniroute is not recognized	Thư mục npm toàn cục chưa nằm trong PATH	Chạy npm config get prefix để xem đường dẫn, rồi thêm đường dẫn đó vào PATH của Windows
Trang đăng nhập trắng hoặc lỗi "Module did not self-register"	Bản Node.js nằm ngoài khoảng được hỗ trợ	Cài Node.js 24 LTS, chạy lại npm install -g omniroute, rồi omniroute
Không đăng nhập được bảng điều khiển	Chưa đặt mật khẩu quản trị, hoặc quên	Chạy omniroute setup để đặt mật khẩu và nhà cung cấp đầu tiên; quên thì omniroute reset-password. Cũng có thể đặt biến môi trường INITIAL_PASSWORD cho lần đăng nhập đầu
Báo "Rate limit exceeded" hoặc 429	Gửi quá nhiều yêu cầu tới một nhà cung cấp miễn phí	Chờ khoảng một phút, dùng mô hình auto, hoặc kết nối thêm nhà cung cấp
Báo "Quota exceeded"	Hết hạn mức của tài khoản đó	Kết nối thêm nhà cung cấp hoặc thêm tài khoản thứ hai
Báo 401 hoặc "Invalid API key"	Khóa sai hoặc hết hạn	Chép lại khóa ở Endpoints; với nhà cung cấp, đăng nhập lại hoặc lấy khóa mới
Kaspersky báo Trojan và tự gỡ ứng dụng trên Windows	Báo nhầm do bộ cài chưa ký số	Đối chiếu mã sha512 của file với latest.yml trên trang Releases, khôi phục file, thêm ngoại lệ cho thư mục %LOCALAPPDATA%\Programs\OmniRoute, rồi cài lại
Avast hoặc AVG cách ly file README.md của OmniRoute	Báo nhầm với một file văn bản có nhiều đường link	Khôi phục file và thêm ngoại lệ; không cần làm gì thêm
Báo EACCES: permission denied	Không ghi được vào thư mục dữ liệu	Đặt biến môi trường DATA_DIR trỏ tới một thư mục bạn ghi được
macOS báo dlopen … slice is not valid mach-o file	Thành phần gốc không khớp máy	Chạy các lệnh bên dưới

Lệnh sửa lỗi dlopen trên macOS:

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Nếu cổng 20128 đang bị chương trình khác dùng, khởi động ở cổng khác (nhớ đổi số cổng trong Base URL cho khớp):

omniroute --port 3000

Khi không rõ lỗi ở đâu, chạy omniroute doctor để kiểm tra thư mục dữ liệu, cơ sở dữ liệu, nhà cung cấp và cổng. Danh sách lỗi đầy đủ: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TROUBLESHOOTING.md

6. Gỡ cài đặt / cập nhật

Cập nhật

• Bản dòng lệnh: chạy omniroute update để kiểm tra và áp dụng bản mới.
• Ứng dụng máy tính: tải bộ cài mới nhất ở trang Releases và cài đè.
• Docker: nhãn :latest trỏ tới bản ổn định mới nhất; cách thay container xem trong Docker Guide.

Gỡ

Ứng dụng trên Windows: vào Settings, Apps, tìm OmniRoute, chọn Uninstall.

Ứng dụng trên macOS và Linux: kéo OmniRoute.app từ Applications vào Thùng rác (macOS), hoặc xóa file AppImage (Linux). Dữ liệu nằm ở thư mục riêng, xem ngay bên dưới.

Bản dòng lệnh (npm):

npm uninstall -g omniroute

Docker:

docker stop omniroute
docker rm omniroute
docker volume rm omniroute-data

Dòng cuối xóa toàn bộ dữ liệu.

Dữ liệu của OmniRoute (nhà cung cấp, khóa, lịch sử dùng) mặc định nằm ở ~/.omniroute/ trên macOS và Linux, và ở %APPDATA%\omniroute trên Windows (nếu bạn đã đặt biến DATA_DIR hoặc XDG_CONFIG_HOME thì nằm ở đó). Gỡ chương trình không tự xóa thư mục này. Giữ lại nếu bạn định cài lại; xóa đi nếu muốn gỡ sạch, ví dụ trên macOS và Linux:

rm -rf ~/.omniroute

Lưu ý: Xóa thư mục dữ liệu là mất hết kết nối nhà cung cấp, khóa API và lịch sử, không khôi phục được.

7. Câu hỏi hay gặp

Có mất tiền không? OmniRoute miễn phí. Chi phí, nếu có, đến từ các nhà cung cấp mô hình bạn kết nối. Có thể bắt đầu hoàn toàn bằng các gói miễn phí, nhưng chúng có giới hạn và có thể thay đổi.

Có cần mạng không? Có. OmniRoute chạy trên máy bạn nhưng các mô hình AI nằm ở máy chủ của nhà cung cấp, trừ khi bạn nối nó với một mô hình chạy tại máy.

Dữ liệu của tôi có bị gửi đi đâu không? Theo README: cổng và bảng điều khiển chạy trên máy bạn; nội dung yêu cầu được gửi tới nhà cung cấp được chọn cho yêu cầu đó, không qua thêm máy chủ nào của OmniRoute; việc thu thập số liệu sử dụng mặc định tắt; khóa và thông tin đăng nhập được mã hóa khi lưu. Nhà cung cấp nhận yêu cầu thì xử lý theo chính sách riêng của họ.

Máy yếu có chạy được không? Bảng điều khiển và chat nhẹ thì được: bản Docker mặc định chỉ dùng 1024 MB bộ nhớ và tài liệu khuyên máy có từ 2 GB. Chạy công cụ lập trình AI với ngữ cảnh dài thì cần nhiều hơn hẳn; tài liệu nêu mức 10 GB trở lên cho một công cụ.

Dùng gói miễn phí kiểu này có vi phạm điều khoản không? Tùy nhà cung cấp. Dự án có một danh mục đánh giá rủi ro điều khoản và tự đánh dấu một số nhà cung cấp là "nên tránh". Hãy đọc điều khoản của nhà cung cấp trước khi kết nối tài khoản của bạn.