6. Xử lý sự cố

Tra cứu nhanh

Triệu chứng	Mục
opencode không có model 9router/...	6.1
Lỗi 401 khi chat	6.2
Lỗi 400 với một model	6.3
Cần xem log của plugin	6.4
opencode models không nhận tên provider	6.5
Lệnh lỗi trong Git Bash vì tham số bị đổi thành đường dẫn	6.6
Mất lệnh 9router hoặc opencode sau khi đổi phiên bản Node.js	6.7
Cấu hình opencode bị thay đổi sau khi chạy 9router connect	6.8
npm install báo EBUSY hoặc EPERM	6.9

6.1. Không thấy model của 9router

Triệu chứng. opencode models không có dòng nào bắt đầu bằng 9router/.

Nguyên nhân. 9router chưa chạy hoặc chưa sẵn sàng khi opencode khởi động. Plugin chưa được nạp. Hoặc cấu hình thiếu "enabled": true trong modelsDiscovery.

Cách xử lý.

1. Kiểm tra 9router theo 4.1.
2. Kiểm tra plugin theo 4.2.
3. Đối chiếu baseURL và modelsDiscovery.enabled với 3.2.
4. Làm mới danh sách theo 5.2.
5. Nếu vẫn lỗi, xem log theo 6.4.

6.2. Lỗi 401 khi chat

Triệu chứng. Danh sách model hiện bình thường, nhưng chat báo 401 hoặc Unauthorized.

Nguyên nhân. opencode gửi key sai hoặc rỗng. Biến NINE_ROUTER_KEY chưa được nạp vào opencode service, hoặc key đã bị xoá trên 9router. 9router có thể trả danh sách model mà không cần key, nên danh sách hiện ra chưa chứng minh key đúng.

Cách xử lý.

1. Mở terminal mới và kiểm tra biến theo 2.4.
2. Từ chính terminal đó, chạy opencode service restart.
3. Trong dashboard của 9router, mở Endpoint và xác nhận key vẫn còn trong danh sách API Keys.
4. Nếu vẫn lỗi, đăng xuất rồi đăng nhập lại Windows.

Nếu lỗi 401 chỉ xảy ra với model của một provider, lỗi nằm ở kết nối giữa 9router và provider đó. Kết nối lại provider trong mục Providers của dashboard.

6.3. Lỗi 400 với một model

Triệu chứng. Một model báo lỗi 400, ví dụ oc/jev-1.13-free báo ModelProtocolUnsupported. Các model khác vẫn chạy.

Nguyên nhân. Lỗi nằm ở phía 9router hoặc provider, không nằm ở cấu hình opencode. Gọi thẳng 9router bằng curl cũng nhận cùng lỗi.

Cách xử lý. Ẩn model lỗi bằng excludeBy theo 3.5:

"excludeBy": [
    { "field": "id", "match": "^(ag|cx|cc|gc|gh|kr)/" },
    { "field": "id", "equals": "oc/jev-1.13-free" }
]

6.4. Xem log của plugin

Cảnh báo của plugin chỉ in ra console, không ghi vào file log của opencode. Chạy opencode ở chế độ độc lập, in log và lọc dòng của plugin:

Git Bash

opencode models --standalone --print-logs 2>&1 | grep 'opencode-models-discovery'

PowerShell

opencode models --standalone --print-logs 2>&1 | Select-String 'opencode-models-discovery'

Dòng của plugin bắt đầu bằng [opencode-models-discovery]. Một số cảnh báo thường gặp:

Cảnh báo	Ý nghĩa
Ignoring invalid model regex: ...	Biểu thức trong includeRegex hoặc excludeRegex sai cú pháp và bị bỏ qua
Ignoring invalid model field regex for ...	Biểu thức match trong includeBy hoặc excludeBy sai cú pháp và bị bỏ qua
Toast API not available ...	Môi trường hiện tại không hiển thị được thông báo dạng toast. Không ảnh hưởng chức năng

6.5. opencode models không nhận tên provider

Triệu chứng. opencode models 9router báo lỗi hoặc chỉ in hướng dẫn sử dụng.

Nguyên nhân. Lệnh opencode models không nhận tham số tên provider.

Cách xử lý. Lọc kết quả: opencode models | grep '^9router/', hoặc opencode models | Select-String '^9router/' trong PowerShell.

6.6. Git Bash đổi tham số thành đường dẫn

Triệu chứng. Một lệnh có tham số bắt đầu bằng / chạy sai trong Git Bash, ví dụ tham số bị đổi thành C:/Program Files/Git/....

Nguyên nhân. Git Bash tự chuyển tham số có dạng đường dẫn POSIX sang đường dẫn Windows trước khi gọi chương trình.

Cách xử lý. Thêm MSYS_NO_PATHCONV=1 vào đầu lệnh, ví dụ MSYS_NO_PATHCONV=1 opencode api .... Hoặc chạy lệnh trong PowerShell.

6.7. Mất lệnh sau khi đổi phiên bản Node.js

Triệu chứng. Sau khi đổi phiên bản Node.js bằng nvm-windows, terminal không nhận ra lệnh 9router hoặc opencode. 9router không tự khởi động khi đăng nhập.

Nguyên nhân. Mỗi phiên bản Node.js có thư mục gói toàn cục riêng. File 9router.vbs có thể trỏ tới đường dẫn không còn 9router.

Cách xử lý.

1. Chạy nvm use <phiên-bản>. Lệnh này có thể cần xác nhận UAC.
2. Cài lại: npm install -g 9router @opencode/cli.
3. Tạo lại file 9router.vbs theo 2.3.1.

Dữ liệu 9router trong %APPDATA%\9router không phụ thuộc phiên bản Node.js nên không bị mất.

6.8. Cấu hình bị thay đổi sau 9router connect

Triệu chứng. Sau khi chạy 9router connect ... --tools opencode, cấu hình opencode khác với tài liệu, ví dụ mất modelsDiscovery hoặc xuất hiện danh sách models cố định.

Nguyên nhân. Lệnh này ghi lại file cấu hình opencode và lưu bản gốc thành file có đuôi .bak-9router.

Cách xử lý. So sánh file hiện tại với file .bak-9router. Khôi phục bản gốc, hoặc sửa lại theo 3.2. Không dùng 9router connect cho opencode khi đã cấu hình theo tài liệu này.

6.9. npm báo EBUSY hoặc EPERM

Triệu chứng. npm install -g 9router@latest báo EBUSY: resource busy or locked hoặc EPERM: operation not permitted.

Nguyên nhân. 9router đang chạy và giữ file trong thư mục cài đặt.

Cách xử lý. Dừng 9router theo bước 2 ở 5.4, rồi chạy lại lệnh cài đặt.