Phụ lục

A. Bảng lệnh nhanh

Các lệnh dưới đây dành cho Git Bash. Lệnh PowerShell tương ứng nằm ở mục được dẫn.

Việc	Lệnh	Mục
Xem phiên bản	node --version, 9router --version, opencode --version	1.4
Kiểm tra key đã nạp	echo ${#NINE_ROUTER_KEY}	2.4
Kiểm tra cú pháp cấu hình	node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')); console.log('OK')" ~/.config/opencode/opencode.json	3.2
Áp dụng cấu hình	opencode service restart	3.4
Kiểm tra 9router	curl -s http://127.0.0.1:20128/v1/models -H "Authorization: Bearer $NINE_ROUTER_KEY" | grep -oE '"id":"[^"]+"' | head -5	4.1
Kiểm tra plugin	opencode api plugin.list | grep -oE '"(id|status)":"[^"]*"' | grep -A1 'opencode.models-discovery'	4.2
Đếm model của 9router trong opencode	opencode models | grep -c '^9router/'	4.3
Chat thử	opencode run -m 9router/oc/deepseek-v4.1-flash-free "Reply with exactly: OK"	4.4
Làm mới danh sách trong TUI	/models-discovery-refresh	5.2
Cập nhật 9router	npm install -g 9router@latest	5.4
Xem log của plugin	opencode models --standalone --print-logs 2>&1 | grep 'opencode-models-discovery'	6.4
Kiểm tra endpoint có cần key	curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:20128/v1/models	8.5.1
Kiểm tra địa chỉ lắng nghe	netstat -ano | grep ':20128' | grep LISTENING	8.5.2

B. Tham chiếu tuỳ chọn của plugin

Các tuỳ chọn nằm trong providers.9router.settings.modelsDiscovery.

Tuỳ chọn	Mặc định	Mô tả
enabled	false	Bật tự lấy danh sách model
endpoint	/v1/models	Đường dẫn của endpoint danh sách model. Phải bắt đầu bằng / và được ghép với phần gốc (origin) của baseURL
timeoutMs	5000	Thời gian chờ tối đa, tính bằng mili giây. Tối thiểu 1000
smartModelName	false	Tạo tên hiển thị dễ đọc từ id model
modelInfoFormat	Không đặt	Định dạng metadata: omniroute (9router), models.dev, aiproxy, bifrost, litellm, vllm, lmstudio, llama-swap. Khi không đặt, plugin không gọi nguồn bên ngoài. Chỉ models.dev và aiproxy tải https://models.dev/models.json
filterNonChat	true	Ẩn model không dùng để chat
models.includeBy	[]	Chỉ giữ model khớp ít nhất một điều kiện theo trường, xem 3.5
models.excludeBy	[]	Ẩn model khớp bất kỳ điều kiện nào theo trường
models.includeRegex	[]	Cách viết tắt của includeBy, chỉ so khớp id
models.excludeRegex	[]	Cách viết tắt của excludeBy, chỉ so khớp id
cache.enabled	false	Lưu đệm danh sách model
cache.ttlSeconds	Không đặt	Thời gian lưu đệm, tính bằng giây. Không được âm

Ghi chú:

• Thứ tự xét: excludeBy, excludeRegex, includeBy, rồi includeRegex.
• includeBy và excludeBy phải nằm trong modelsDiscovery.models. Đặt ở vị trí khác thì plugin bỏ qua và in cảnh báo.
• Biểu thức chính quy sai cú pháp bị bỏ qua kèm cảnh báo, xem 6.4.

C. Thuật ngữ

Thuật ngữ	Giải thích
opencode	Công cụ lập trình với AI chạy trên terminal
opencode service	Tiến trình nền của opencode, nạp plugin và provider
9router	Proxy AI chạy trên máy, gom nhiều provider sau một API chuẩn OpenAI
Provider	Nhà cung cấp model AI, kết nối vào 9router bằng API key hoặc OAuth
Model id	Định danh model dạng <alias>/<tên-model>, ví dụ oc/deepseek-v4.1-flash-free. Trong opencode có thêm tiền tố 9router/
Plugin discovery	Plugin opencode-models-discovery, tự lấy danh sách model từ endpoint chuẩn OpenAI
API chuẩn OpenAI	Bộ endpoint như /v1/models và /v1/chat/completions mà nhiều công cụ hỗ trợ
Phiên OAuth thuê bao	Phiên đăng nhập của gói thuê bao cá nhân, không phải API key. Dùng qua proxy có rủi ro vi phạm điều khoản
Biến môi trường mức User	Biến môi trường áp dụng cho tài khoản Windows hiện tại
Loopback	Địa chỉ 127.0.0.1, chỉ dùng được từ chính máy đó

D. Thanh trạng thái caveman cho Claude Code (tuỳ chọn)

Phần này chỉ dành cho người dùng Claude Code đã cài plugin caveman. Phần này không liên quan tới opencode hay 9router.

1. Xác định thư mục cấu hình của Claude Code: giá trị biến CLAUDE_CONFIG_DIR nếu có, nếu không thì là %USERPROFILE%\.claude.

2. Mở <thư-mục-cấu-hình>\plugins\installed_plugins.json, tìm mục caveman@caveman và lấy giá trị installPath, ví dụ ...\plugins\cache\caveman\caveman\2.7.0.

3. Thêm khối statusLine vào <thư-mục-cấu-hình>\settings.json. Trong JSON, mỗi dấu \ viết thành \\:

   "statusLine": {
       "type": "command",
       "command": "powershell -ExecutionPolicy Bypass -File \"<installPath>\\src\\hooks\\caveman-statusline.ps1\""
   }

4. Kiểm tra script trong Git Bash:

   echo '{}' | powershell -ExecutionPolicy Bypass -File "<installPath>\src\hooks\caveman-statusline.ps1"

   Kết quả mong đợi: dòng có chữ [CAVEMAN].

5. Khởi động lại Claude Code.

Đường dẫn có số phiên bản

installPath chứa số phiên bản của caveman. Sau mỗi lần caveman cập nhật, sửa lại đường dẫn trong statusLine.

E. Nhật ký thay đổi

Phiên bản	Ngày	Nội dung
1.0	04/11/2026	Phát hành lần đầu