Cách dùng 9Router cho OpenClaw: cấu hình từng bước

Để dùng 9Router cho OpenClaw, bạn khai báo 9Router là một Custom Provider tương thích OpenAI trong OpenClaw với ba giá trị: API Base URL http://localhost:20128/v1, API key tạo trong dashboard 9Router và Model ID là tên combo đã tạo trên 9Router. Từ đó, mọi yêu cầu của agent đi qua combo và 9Router tự chọn model thật phía sau.

Bài này chỉ nói phần cấu hình trong OpenClaw. Nếu chưa rõ 9Router là gì, có miễn phí và an toàn không, đọc trước bài 9Router là gì; các cách khác để đưa model vào OpenClaw nằm trong bài dùng nhiều model AI trên OpenClaw.

Vì sao nên kết nối 9Router với OpenClaw?

Kết nối 9Router với OpenClaw hữu ích khi bạn muốn OpenClaw dùng nhiều nguồn model mà không phải khai báo lại từng provider:

• Chỉ quản lý một Base URL và một API key nội bộ trong OpenClaw.
• Thêm, bớt hoặc đổi thứ tự model trong combo trên 9Router mà không sửa cấu hình OpenClaw.
• Combo tự chuyển model khi nguồn chính lỗi hoặc hết hạn mức.
• Theo dõi token, hạn mức và lịch sử yêu cầu tập trung trên dashboard 9Router.

Đổi lại, bạn thêm một lớp trung gian giữ token và key của mọi provider. Với gói thuê bao kết nối qua OAuth, chính 9Router cảnh báo tài khoản có thể bị hạn chế nếu nhà cung cấp không cho phép dùng qua proxy; chi tiết ở mục rủi ro điều khoản và bảo mật của 9Router.

Cách dùng 9Router cho OpenClaw từng bước

Hướng dẫn giả định 9Router và OpenClaw cài trên cùng một máy Windows, nên OpenClaw gọi 9Router qua localhost:20128. Máy cần Node.js và npm. Ảnh chụp dùng 9Router 0.5.45 và OpenClaw 2026.7.1; các bản 2026.10 có cùng trình hỏi đáp, chỉ khác vài chi tiết hiển thị.

Bước 1: Cài đặt và đăng nhập 9Router

Mở Windows PowerShell (chuột phải, chọn Run as administrator), rồi cài bản 9Router mới nhất:

npm install -g 9router@latest

Khởi động 9Router:

9router

Tại màn hình Choose Interface, dùng phím mũi tên chọn Web UI (Open in Browser) rồi nhấn Enter. Dashboard mặc định ở http://localhost:20128.

Nếu trình duyệt không tự mở, vào http://localhost:20128/login. Khi chưa đặt mật khẩu, mật khẩu mặc định là 123456.

Đăng nhập xong, vào Settings đổi mật khẩu ngay. Sau đó quay lại PowerShell, chọn Hide to Tray (Background) để 9Router chạy nền.

Khi cần mở lại dashboard, vào http://localhost:20128/dashboard.

• Sau khi chọn Hide to Tray, đóng PowerShell không làm 9Router dừng.
• Tắt máy, khởi động lại Windows hoặc chọn Exit trong menu 9Router thì phải chạy lại lệnh 9router.
• OpenClaw và 9Router là hai tiến trình riêng. Nếu Gateway OpenClaw đang chạy trực tiếp trong một cửa sổ terminal (chưa cài dịch vụ nền), đóng cửa sổ đó sẽ dừng Gateway.

Trên npm bản mới, nếu PowerShell báo install scripts blocked, cài lại và cho phép script của gói 9router:

npm install -g --allow-scripts=9router 9router@latest

Bước 2: Tạo API key và lấy endpoint trên 9Router

Trong dashboard, chọn Endpoint & Key, tìm mục API Keys rồi nhấn Create Key.

Đặt tên dễ nhận biết rồi nhấn Create.

Hộp thoại API Key Created chỉ hiện key một lần. Nhấn Copy và lưu key ở nơi an toàn.

Phần API Endpoint hiển thị http://localhost:20128/v1. Sao chép địa chỉ này để nhập vào OpenClaw. Nên bật luôn công tắc Require API key ở cùng trang để 9Router từ chối yêu cầu không có key; tuỳ chọn này mặc định tắt.

Bước 3: Thêm provider và tạo combo trên 9Router

Ví dụ dùng hai provider: OpenAI Codex (qua OAuth) và Gemini (qua API key). Cách quản lý provider, combo và hạn mức chi tiết hơn có trong bài 9Router là gì.

Vào Providers, tìm OpenAI Codex trong nhóm OAuth Providers và nhấn vào.

Nhấn Add Connection, đăng nhập tài khoản OpenAI có quyền dùng Codex và cấp quyền. Trang này có cảnh báo rủi ro tài khoản của 9Router; hãy đọc trước khi tiếp tục.

Thường 9Router tự nhận kết quả xác thực. Nếu không, sao chép Callback URL trên trình duyệt và dán vào ô trong 9Router.

Tiếp theo, quay lại Providers, kéo xuống nhóm Free Tier Providers và chọn Gemini.

Nhập tên kết nối, dán API key Gemini (tạo ở Google AI Studio) rồi nhấn Check. Khi trạng thái là Valid, giữ Priority 1, Proxy Pool để None và nhấn Save.

Bạn có thể dùng provider khác có API key miễn phí; danh sách và giới hạn từng nơi xem ở bài LLM lấy API key miễn phí cho AI Agent. Lưu ý gói miễn phí của Gemini API có giới hạn tốc độ và theo trang giá của Google, dữ liệu gửi qua gói miễn phí có thể được dùng để cải thiện sản phẩm.

Chọn Combos ở menu trái rồi nhấn Create Combo.

Nhập tên combo. OpenClaw sẽ dùng chính tên này làm Model ID, nên ghi lại chính xác.

Nhấn Add Model và chọn model từ Codex và Gemini.

Dùng mũi tên để sắp thứ tự. Thứ tự quan trọng với chiến lược Fallback vì 9Router thử model trên cùng trước.

Nhấn Create, rồi chọn chiến lược cho combo: Fallback (thử theo thứ tự), Round Robin (luân phiên để chia tải) hoặc Fusion (hỏi nhiều model rồi tổng hợp, tốn token hơn). Ví dụ chọn Round Robin; với tác vụ OpenClaw dài hoặc cần phản hồi ổn định, Fallback dễ kiểm soát hơn.

Nhấn biểu tượng Copy cạnh combo để lấy tên Test9Router.

Không thoát 9Router bằng Exit: endpoint sẽ ngừng trả lời và OpenClaw không gọi được combo.

Bước 4: Khai báo 9Router là Custom Provider trong OpenClaw

Mở PowerShell và chạy trình cấu hình. Theo tài liệu OpenClaw, openclaw config không kèm lệnh con mở cùng trình hỏi đáp với openclaw configure (OpenClaw CLI: config):

openclaw config

Nếu OpenClaw phát hiện cấu hình cũ, màn hình hiện workspace, model và Gateway đang dùng. Tại câu Where will the Gateway run?, chọn Local (this machine).

Tại What do you want to configure?, chọn Model. Muốn vào thẳng phần này, có thể chạy openclaw config --section model.

Trong danh sách Model/auth provider, chọn More… để mở đủ danh sách nhà cung cấp.

Chọn Custom Provider, mục dành cho mọi endpoint tương thích OpenAI hoặc Anthropic.

Tại API Base URL, nhập endpoint của 9Router rồi nhấn Enter:

http://localhost:20128/v1

Chỉ dùng localhost khi OpenClaw và 9Router chạy cùng máy. Nếu ở hai máy khác nhau, dùng địa chỉ mà máy OpenClaw truy cập được qua mạng riêng như Tailscale hoặc qua đường hầm SSH.

Tại How do you want to provide this API key?, chọn Paste API key now. Lựa chọn này lưu key thẳng vào file cấu hình OpenClaw; nếu bạn đã dùng trình quản lý secret, chọn Use external secret provider.

Dán API key đã tạo ở bước 2 rồi nhấn Enter.

Tại Endpoint compatibility, chọn OpenAI-compatible (dùng /chat/completions).

Tại Model ID, nhập đúng tên combo, ví dụ Test9Router.

OpenClaw gọi thử endpoint. Thông tin đúng thì màn hình báo Verification successful. Nếu báo fetch failed, kiểm tra:

• 9Router có đang chạy không.
• API Base URL có đúng cổng 20128 và có đuôi /v1 không.
• API key còn bật trong 9Router không.
• Tên combo có khớp hoàn toàn với Model ID không.

Endpoint ID có thể giữ giá trị OpenClaw tự tạo (ví dụ custom-localhost-20128). Model alias là tuỳ chọn, để trống rồi nhấn Enter; alias chỉ giúp gọi model bằng tên ngắn.

Tại Does this model support image input?, chọn Yes nếu combo có model nhận ảnh (ví dụ Gemini), chọn No nếu combo chỉ xử lý văn bản.

Khi OpenClaw báo cấu hình thành công, chọn Done để thoát. OpenClaw tự cập nhật ~/.openclaw/openclaw.json và tạo bản sao lưu openclaw.json.bak trước khi ghi.

Bước 5: Kiểm tra model mặc định trong OpenClaw

Xem model mặc định bằng:

openclaw models

Dòng Default cần hiển thị custom-localhost-20128/Test9Router.

Nếu combo chưa là mặc định, đặt lại rồi kiểm tra bằng openclaw models status (OpenClaw CLI: models):

openclaw models set custom-localhost-20128/Test9Router
openclaw models status

Gửi một câu hỏi trong OpenClaw hoặc kênh chat đã kết nối, rồi mở Usage trên 9Router. Khi kết nối chạy, Usage & Analytics hiển thị số yêu cầu, token vào và ra, model mà combo đã chọn và provider nhận yêu cầu.

Cấu hình thủ công trong openclaw.json

Không muốn dùng trình hỏi đáp, bạn có thể khai báo provider trong ~/.openclaw/openclaw.json (định dạng JSON5, cho phép chú thích). Gateway tự nạp lại khi file thay đổi. Cấu trúc theo tài liệu custom providers của OpenClaw (OpenClaw: Custom providers):

{
  agents: { defaults: { model: { primary: "nine/Test9Router" } } },
  models: {
    providers: {
      nine: {
        baseUrl: "http://127.0.0.1:20128/v1",
        apiKey: "${NINEROUTER_API_KEY}",   // đọc từ biến môi trường
        api: "openai-completions",
        models: [{ id: "Test9Router" }]
      }
    }
  }
}

Đặt key vào biến môi trường NINEROUTER_API_KEY thay vì ghi thẳng vào file giúp không lộ key khi sao lưu hoặc chia sẻ cấu hình. Sau khi sửa, chạy openclaw doctor để kiểm tra cấu hình.

Chạy 9Router và OpenClaw trên VPS an toàn

Trên VPS, 9Router và OpenClaw nên nằm cùng máy và nói chuyện qua 127.0.0.1; không mở cổng 20128 ra Internet. Tài liệu OpenClaw cũng khuyên giữ Gateway (cổng 18789) ở loopback và truy cập từ xa qua Tailscale hoặc đường hầm SSH (OpenClaw: Gateway ports and remote mode).

• Mở dashboard 9Router từ máy tính của bạn bằng đường hầm SSH, chạy trên máy cá nhân: ssh -N -L 20128:127.0.0.1:20128 user@dia-chi-vps, rồi vào http://localhost:20128.
• Đặt mật khẩu dashboard riêng (biến INITIAL_PASSWORD khi khởi động lần đầu) và bật Require API key.
• Nếu OpenClaw chạy trong Docker, localhost bên trong container là chính container. Cần trỏ tới địa chỉ host mà container truy cập được, và chỉ mở 9Router cho mạng nội bộ đó, không mở công khai.
• Dùng tường lửa chặn cổng 20128 từ bên ngoài, kể cả khi đã bật API key.

Các lớp bảo vệ khác cho VPS chạy agent xem ở bài bảo mật VPS chạy AI Agent bằng Tailscale và cách ly sandbox cho AI Agent trên VPS.

Lỗi thường gặp khi dùng 9Router cho OpenClaw

Khi nào không cần dùng 9Router cho OpenClaw?

9Router không bắt buộc. Kết nối thẳng provider với OpenClaw đơn giản và rõ điều khoản hơn khi:

• Bạn chỉ dùng một model cố định.
• Không cần chuyển dự phòng hay chia tải.
• Provider đã có sẵn trong OpenClaw với đăng nhập chính thức, ví dụ OpenAI Codex qua ChatGPT OAuth hoặc Gemini qua API key.
• Hệ thống cần ít thành phần trung gian nhất có thể.
• Bạn muốn đổi model ngay trong OpenClaw; xem cách đổi provider, model và API key trong OpenClaw.

Tài liệu OpenClaw xếp custom provider vào nhóm dùng cho proxy, endpoint riêng hoặc gateway tương thích OpenAI; với provider đã có plugin chính thức, dùng plugin đó trước.

Kết luận

Dùng 9Router cho OpenClaw chỉ cần ba giá trị: endpoint localhost:20128/v1, API key của 9Router và tên combo làm Model ID. Sau khi kết nối, hãy kiểm tra model mặc định bằng openclaw models, theo dõi Usage trên 9Router và giữ 9Router chạy nền. Trên VPS, để cả hai cùng máy, không mở cổng 20128 và bật Require API key trước khi cho agent chạy thật.

Muốn chạy OpenClaw 24/7 mà không tự cài? VPS OpenClaw của Tino cài sẵn OpenClaw trên VPS NVMe đặt tại Việt Nam; bạn vẫn có quyền root để cấu hình. Xem cấu hình và giá trên trang sản phẩm.

Những câu hỏi thường gặp