2. Cài đặt

2.1. Tóm tắt các bước

Bước	Việc	Kết quả mong đợi
1	Cài Node.js	node --version in ra phiên bản
2	Cài 9router và tạo API key	Dashboard mở được, đã có API key
3	Tự khởi động 9router (tuỳ chọn)	9router chạy nền sau khi đăng nhập Windows
4	Đặt biến môi trường NINE_ROUTER_KEY	Terminal mới đọc được biến
5	Cài opencode	opencode --version in ra phiên bản
6	Cấu hình opencode	File opencode.json hợp lệ
7	Kiểm tra	Đạt toàn bộ bảng nghiệm thu

2.2. Cài Node.js

9router yêu cầu Node.js 18 trở lên. Nên dùng nvm-windows để dễ đổi phiên bản. Lệnh giống nhau trên Git Bash và PowerShell:

nvm install 26.8.1
nvm use 26.8.1
node --version

nvm use có thể hiện hộp thoại UAC hoặc cần terminal chạy với quyền quản trị. Nếu không dùng nvm-windows, cài bản LTS từ trang chủ Node.js.

Gói npm toàn cục gắn với từng phiên bản Node.js

Với nvm-windows, mỗi phiên bản Node.js có thư mục gói toàn cục riêng. Sau khi đổi phiên bản, cần cài lại 9router và opencode. Xem 6.7.

2.3. Cài 9router và tạo API key

npm install -g 9router
9router

Lệnh 9router khởi động server và hiện menu trong terminal. Chọn Web UI (Open in Browser) hoặc mở http://localhost:20128/dashboard. Trong dashboard:

1. Mở Providers và kết nối provider bạn có quyền dùng. Ưu tiên provider dùng API key chính thức. Tránh provider dùng phiên OAuth thuê bao, xem 8.1.
2. Mở Endpoint, tới mục API Keys và bấm Create Key. Nhập Key Name, ví dụ tên máy hoặc tên người dùng, rồi bấm Create.
3. Hộp thoại API Key Created hiện key mới. Sao chép key vào trình quản lý mật khẩu. Bạn có thể xem lại key trong danh sách API Keys.
4. Trên cùng trang, bật Require API key để 9router từ chối yêu cầu không có key hợp lệ.

Mỗi máy một key

Tạo key riêng cho từng máy hoặc từng người. Khi thu hồi một key, các máy khác không bị ảnh hưởng.

2.3.1. Tự khởi động cùng Windows (tuỳ chọn)

Để 9router chạy nền mỗi khi đăng nhập Windows, tạo file 9router.vbs trong thư mục Startup. Chạy trong PowerShell:

$node = (Get-Command node).Source
$cli  = Join-Path (npm root -g) "9router\cli.js"
$vbs  = Join-Path ([Environment]::GetFolderPath("Startup")) "9router.vbs"
$line = 'WshShell.Run """{0}"" ""{1}"" --tray --skip-update --host 127.0.0.1", 0, False' -f $node, $cli
Set-Content -Path $vbs -Encoding Unicode -Value @('Set WshShell = CreateObject("WScript.Shell")', $line)
Get-Content $vbs

Kết quả mẫu. Đường dẫn phụ thuộc cách cài Node.js:

Set WshShell = CreateObject("WScript.Shell")
WshShell.Run """C:\Program Files\nodejs\node.exe"" ""C:\Program Files\nodejs\node_modules\9router\cli.js"" --tray --skip-update --host 127.0.0.1", 0, False

Tham số	Ý nghĩa
--tray	Chạy nền với biểu tượng ở khay hệ thống, không mở menu trong terminal
--skip-update	Không kiểm tra cập nhật khi khởi động. Cập nhật thủ công theo 5.4
--host 127.0.0.1	Chỉ nhận kết nối từ chính máy này
0, False	Ẩn cửa sổ và không chờ tiến trình kết thúc

Nếu 9router đang chạy, dừng nó trước theo bước 2 ở 5.4. Sau đó nhấp đúp file 9router.vbs, hoặc đăng xuất rồi đăng nhập lại Windows. Để mở thư mục Startup, nhấn Win + R và nhập shell:startup.

9router có thể ghi đè file này

Mục Hide to Tray (Background) trong menu của 9router ghi đè 9router.vbs bằng lệnh không có --host. Mục này cũng chạy một tiến trình nền lắng nghe trên 0.0.0.0. Sau khi dùng mục này, chạy lại đoạn lệnh trên và kiểm tra địa chỉ lắng nghe theo 8.5.

Nếu team dùng chung 9router trong mạng LAN, bỏ --host 127.0.0.1 và giới hạn truy cập bằng tường lửa theo 8.5.

Không mở cổng 20128 ra Internet

Không chuyển tiếp cổng (port forwarding) hay mở cổng 20128 ra Internet. Ai kết nối được tới cổng này đều có thể dò API key, xem danh sách model và dùng quota provider của bạn khi có key.

2.4. Đặt biến môi trường NINE_ROUTER_KEY

opencode đọc API key từ biến môi trường NINE_ROUTER_KEY qua cú pháp {env:NINE_ROUTER_KEY} trong cấu hình. Đặt biến ở mức User để mọi terminal và opencode service đều đọc được.

Cách 1: giao diện Windows

1. Nhấn Win + R, nhập rundll32 sysdm.cpl,EditEnvironmentVariables rồi nhấn Enter.
2. Trong User variables, bấm New....
3. Nhập Variable name là NINE_ROUTER_KEY. Dán API key vào Variable value.
4. Bấm OK ở cả hai hộp thoại.

Cách 2: PowerShell. Key không hiện trên màn hình và không lưu vào lịch sử lệnh:

$s = Read-Host "Dan API key cua 9router" -AsSecureString
$k = [System.Net.NetworkCredential]::new("", $s).Password
[Environment]::SetEnvironmentVariable("NINE_ROUTER_KEY", $k, "User")
Remove-Variable s, k

Kiểm tra trong terminal mới. Lệnh chỉ in độ dài của key, không in key:

Git Bash

echo ${#NINE_ROUTER_KEY}

PowerShell

$env:NINE_ROUTER_KEY.Length

Kết quả mong đợi: một số lớn hơn 0. Nếu Git Bash in 0 hoặc PowerShell không in gì, terminal chưa nạp biến.

Terminal mới

Biến môi trường mức User chỉ có hiệu lực với tiến trình mở sau khi đặt biến. Terminal tích hợp trong IDE cần khởi động lại cả IDE. Nếu vẫn chưa thấy biến, đăng xuất rồi đăng nhập lại Windows.

2.5. Cài opencode

npm install -g @opencode/cli
opencode --version

Kết quả mong đợi: opencode v2.2.5 hoặc phiên bản mới hơn.