3. Cấu hình opencode

3.1. Vị trí file cấu hình

Shell	Đường dẫn
Git Bash	~/.config/opencode/opencode.json
PowerShell	$env:USERPROFILE\.config\opencode\opencode.json

Tạo thư mục nếu chưa có:

Git Bash

mkdir -p ~/.config/opencode

PowerShell

New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null

Nếu file đã tồn tại, sao lưu trước khi sửa:

Git Bash

cp -p ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak-$(date +%F)

PowerShell

$cfg = "$env:USERPROFILE\.config\opencode\opencode.json"
Copy-Item $cfg "$cfg.bak-$(Get-Date -Format yyyy-MM-dd)"

3.2. Cấu hình tối thiểu

{
    "$schema": "https://opencode.ai/config.json",
    "plugins": ["opencode-models-discovery@2.1.1"],
    "providers": {
        "9router": {
            "name": "9Router",
            "package": "aisdk:@ai-sdk/openai-compatible",
            "settings": {
                "apiKey": "{env:NINE_ROUTER_KEY}",
                "baseURL": "http://127.0.0.1:20128/v1",
                "modelsDiscovery": {
                    "enabled": true,
                    "modelInfoFormat": "omniroute",
                    "smartModelName": true
                }
            }
        }
    }
}

Nếu file đã có nội dung:

1. Thêm "opencode-models-discovery@2.1.1" vào mảng plugins, giữ nguyên các plugin khác.
2. Thêm khối 9router vào providers, giữ nguyên các provider khác.
3. Nếu khối 9router cũ có danh sách models khai báo thủ công, xoá danh sách đó để plugin quản lý danh sách model.

Cú pháp opencode v2

opencode v2 dùng các trường plugins, providers và settings. Cấu hình của opencode v1 dùng plugin, provider và options. Không trộn hai cú pháp trong cùng một file.

Kiểm tra cú pháp JSON:

Git Bash

node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')); console.log('OK')" ~/.config/opencode/opencode.json

PowerShell

try { Get-Content "$env:USERPROFILE\.config\opencode\opencode.json" -Raw | ConvertFrom-Json -ErrorAction Stop | Out-Null; "OK" } catch { $_.Exception.Message }

Kết quả mong đợi: OK. File phải là JSON chuẩn: không có chú thích, không có dấu phẩy sau phần tử cuối.

3.3. Giải thích các trường

Trường	Giá trị	Ý nghĩa
plugins	["opencode-models-discovery@2.1.1"]	Nạp plugin. Ghim phiên bản để plugin không tự nâng cấp
name	"9Router"	Tên hiển thị của provider trong opencode
package	"aisdk:@ai-sdk/openai-compatible"	Bộ kết nối cho API chuẩn OpenAI
apiKey	"{env:NINE_ROUTER_KEY}"	Đọc key từ biến môi trường, không ghi key vào file
baseURL	"http://127.0.0.1:20128/v1"	Địa chỉ API của 9router
modelsDiscovery.enabled	true	Bật tự lấy danh sách model. Mặc định tắt
modelsDiscovery.modelInfoFormat	"omniroute"	Đọc metadata model theo định dạng của 9router. Plugin không gọi nguồn bên ngoài
modelsDiscovery.smartModelName	true	Tạo tên hiển thị dễ đọc từ id model. Mặc định false

Danh sách đầy đủ tuỳ chọn của plugin nằm ở Phụ lục B.

Dùng 9router trên server của team

Đổi baseURL thành http://<địa-chỉ-server>:20128/v1. Chỉ truy cập server qua LAN hoặc VPN, vì kết nối HTTP không mã hoá. Mỗi người dùng một API key riêng.

3.4. Áp dụng cấu hình

1. Mở terminal mới để nạp biến NINE_ROUTER_KEY.
2. Từ terminal đó, chạy opencode service restart.
3. Chờ vài giây. Lần chạy đầu tiên, opencode tải plugin từ npm nên cần kết nối Internet.
4. Kiểm tra theo 4. Kiểm tra.

3.5. Lọc model (khuyến nghị)

Ẩn model của provider dùng phiên OAuth thuê bao (xem 8.1). Thêm khối models vào modelsDiscovery:

"modelsDiscovery": {
    "enabled": true,
    "modelInfoFormat": "omniroute",
    "smartModelName": true,
    "models": {
        "excludeBy": [
            { "field": "id", "match": "^(ag|cx|cc|gc|gh|kr)/" }
        ]
    }
}

Quy tắc lọc:

• excludeBy ẩn model khớp bất kỳ điều kiện nào trong danh sách.
• includeBy không rỗng thì opencode chỉ giữ model khớp ít nhất một điều kiện, ví dụ { "field": "id", "match": "^oc/" }.
• Mỗi điều kiện có field là tên trường cấp cao nhất trong dữ liệu /v1/models, ví dụ id hoặc owned_by. Điều kiện dùng đúng một trong hai khoá:
  • equals: so sánh bằng chính xác với chuỗi, số, boolean hoặc null;
  • match: biểu thức chính quy, chỉ áp dụng cho giá trị dạng chuỗi.
• excludeRegex và includeRegex là cách viết tắt, chỉ lọc theo id, ví dụ "excludeRegex": ["^(ag|cx|cc|gc|gh|kr)/"].
• Điều kiện loại trừ luôn được xét trước điều kiện giữ lại.
• Id dùng để so khớp là id gốc do 9router trả về, không có tiền tố 9router/.
• Trong JSON, mỗi dấu \ phải viết thành \\, ví dụ "^oc/jev-1\\.13-free$".
• filterNonChat (mặc định true) ẩn model không dùng để chat, ví dụ model embedding.

Sau khi lưu file, plugin tự làm mới danh sách. Nếu danh sách chưa đổi, chạy opencode service restart.