1. Tổng quan

Tài liệu này hướng dẫn cấu hình opencode để tự động lấy danh sách model từ 9router qua plugin opencode-models-discovery. Sau khi cấu hình, mọi model mà 9router cung cấp đều xuất hiện trong opencode, không cần khai báo từng model trong file cấu hình.

1.1. Mục đích

Tiêu chí	Khai báo thủ công	Tự động đồng bộ
Danh sách model	Liệt kê từng model trong opencode.json	Plugin đọc từ GET /v1/models của 9router
Khi 9router thêm hoặc bớt model	Sửa file cấu hình rồi khởi động lại	Tự cập nhật khi plugin làm mới danh sách
Metadata (context, giới hạn output)	Tự nhập hoặc bỏ trống	Lấy từ 9router
Chia sẻ cho team	Mỗi máy giữ một danh sách riêng	Dùng chung một file cấu hình
Nơi lưu API key	Dễ bị ghi thẳng vào file	Biến môi trường NINE_ROUTER_KEY

1.2. Kiến trúc

Hình 1. Kiến trúc tổng quan

1. Khi opencode service khởi động, plugin gọi GET /v1/models của 9router để lấy danh sách model.
2. Khi bạn chat với một model của 9router, opencode gửi POST /v1/chat/completions kèm header Authorization: Bearer chứa API key.
3. 9router chuyển yêu cầu tới provider tương ứng. Provider dùng API key chính thức là lựa chọn khuyến nghị. Provider dùng phiên OAuth thuê bao có rủi ro vi phạm điều khoản, xem 8.1.

Trong opencode, model của 9router có tên dạng 9router/<id>, trong đó <id> là id do 9router trả về. Ví dụ: 9router/oc/deepseek-v4.1-flash-free.

1.3. Thành phần

Thành phần	Vai trò	Ghi chú
opencode CLI	Công cụ lập trình với AI trên terminal	Gói npm @opencode/cli, lệnh opencode
opencode service	Tiến trình nền của opencode, nạp plugin và kết nối provider	Khởi động lại bằng opencode service restart
9router	Proxy chạy trên máy, gom nhiều provider AI sau một API chuẩn OpenAI	Cổng mặc định 20128
opencode-models-discovery	Plugin của opencode, đọc danh sách model từ endpoint chuẩn OpenAI	Ghim phiên bản 2.1.1
NINE_ROUTER_KEY	Biến môi trường chứa API key của 9router	Không ghi vào file

1.4. Phiên bản đã kiểm thử

Thành phần	Phiên bản	Ghi chú
Windows	11 Pro	Áp dụng cho Windows 10
Node.js	26.8.1	9router yêu cầu Node.js 18 trở lên
9router	0.5.112
opencode	2.2.5	Cú pháp cấu hình v2
opencode-models-discovery	2.1.1	Ghim phiên bản trong cấu hình

Phiên bản khác

Các bước vẫn áp dụng cho phiên bản mới hơn nếu không có thay đổi lớn. Trước khi nâng cấp, đọc changelog. Sau khi nâng cấp, chạy lại 4. Kiểm tra.

1.5. Yêu cầu

• Tài khoản Windows thông thường. Chỉ cần quyền quản trị cho bước tường lửa tuỳ chọn ở 8.5 và khi nvm-windows yêu cầu xác nhận UAC.
• Kết nối Internet để cài gói npm và gọi provider.
• Ít nhất một provider dùng API key mà 9router hỗ trợ.
• Git Bash hoặc PowerShell.

1.6. Quy ước

Ký hiệu	Ý nghĩa
~	Thư mục người dùng, ví dụ C:\Users\<tên-người-dùng>. Trong PowerShell là $env:USERPROFILE
%APPDATA%	Thư mục AppData\Roaming của người dùng. Trong PowerShell là $env:APPDATA
<...>	Giá trị cần thay bằng giá trị thật, ví dụ <địa-chỉ-server>
Tab Git Bash và PowerShell	Cùng một việc cho hai shell. Chọn tab theo shell bạn dùng
Khối mã vb	Nội dung file VBScript để đối chiếu, không phải lệnh để chạy