Không tìm thấy provider hoặc model OpenCode: hướng dẫn chẩn đoán

Đối với lỗi không tìm thấy nhà cung cấp hoặc mô hình của OpenCode, trước tiên hãy khớp mô hình đã chọn với ID nhà cung cấp và mô hình mà OpenCode thực sự đã tải. Tham chiếu thường có dạng providerId/modelId. Một khóa API đúng không thể sửa ID viết sai, mô hình tùy chỉnh chưa khai báo hoặc tệp cấu hình mà tiến trình đang chạy không bao giờ đọc.

Lần theo lỗi, không chỉ cụm “provider problem”

Hướng dẫn khắc phục sự cố chính thức hướng các lỗi không tìm thấy model đến các tham chiếu model. Trong mã nguồn provider, việc tra cứu kiểm tra cả mục provider và map model của nó. Cùng một lỗi cũng có thể bao bọc lỗi thiếu model của bộ điều hợp. Ghi lại chính xác thông báo trước khi thay đổi thông tin xác thực hoặc mua thêm credit.

1. Xác định phiên bản và model đã chọn

Chạy các kiểm tra này từ dự án nơi lỗi xảy ra. Nếu ứng dụng desktop sử dụng một máy chủ khác, hãy so sánh phiên bản và cấu hình của nó với bản cài đặt trong terminal này:

opencode --version
opencode models
opencode auth list

Tìm tham chiếu model đầy đủ trong danh sách, sau đó so sánh từng ký tự với lựa chọn của bạn. Tiền tố provider là một phần của danh tính. Model được cung cấp qua gateway tùy chỉnh không trở thành provider Anthropic tích hợp sẵn chỉ vì tên của nó chứa Claude.

Đừng xem thông tin xác thực đã lưu là bằng chứng cho việc xác thực từ xa thành công. Nó chỉ xác nhận rằng thông tin xác thực tồn tại cục bộ; endpoint vẫn phải chấp nhận nó khi yêu cầu được gửi.

2. Sửa cặp provider/model

Ví dụ này sử dụng định dạng provider v1 và minh họa ba mã định danh tương ứng. Đặt biến môi trường được tham chiếu trong tiến trình khởi chạy OpenCode hoặc sử dụng quy trình thông tin xác thực được ghi lại. Gộp các trường liên quan vào cấu hình thay vì ghi đè các thiết lập không liên quan:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "kunavo/claude-sonnet-5",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5"
        }
      }
    }
  }
}

Ở đây, kunavo là khóa provider và claude-sonnet-5 là khóa model. Vì vậy, lựa chọn là kunavo/claude-sonnet-5. Chọn anthropic/claude-sonnet-5 sẽ chọn một provider khác; chọn Kunavo/Claude Sonnet 5 sẽ thay thế các khóa tra cứu bằng tên hiển thị. Không lựa chọn nào trong hai lựa chọn này tham chiếu đến mục được hiển thị ở trên.

Khi sử dụng /connect và Other cho provider tùy chỉnh, hãy nhập cùng một ID provider. Thông tin xác thực không tự xác định danh mục model. Hãy kiểm tra cả bộ điều hợp: bộ điều hợp tương thích v1 được hiển thị ở đây sử dụng Chat Completions; endpoint Responses yêu cầu bộ điều hợp phù hợp.

3. Tách riêng cấu hình v1 và v2

Tài liệu provider v2 sử dụng providers, package và settings, thay cho provider, npm và options của v1. Hãy sử dụng thiết lập dành riêng cho phiên bản thay vì sao chép nguyên khối phía trước vào cấu hình v2.

Trong v2, khóa map của model cũng có thể khác với modelID upstream. Nếu map chứa coder và gửi model upstream upstream/coder-v2, hãy chọn company/coder cho provider company. Thay đổi lựa chọn thành tên upstream sẽ bỏ qua bí danh đã cấu hình.

4. Kiểm tra cấu hình nào được ưu tiên

OpenCode gộp các nguồn cấu hình. Tệp dự án có thể ghi đè model toàn cục; đường dẫn tùy chỉnh, cấu hình nội tuyến và các thiết lập được quản lý cũng có thể ảnh hưởng. Kiểm tra tệp của dự án bị lỗi, cấu hình toàn cục và mọi ghi đè đã cấu hình. Kiểm tra danh sách cho phép của provider hoặc các mục provider bị vô hiệu hóa.

Thực hiện một thay đổi có mục tiêu, khởi động lại tiến trình bị ảnh hưởng rồi liệt kê model lần nữa. Nếu model hiện khả dụng nhưng yêu cầu đầu tiên trả về lỗi HTTP, hãy xử lý lỗi mới đó. Giữ lại các tệp gốc và dữ liệu phiên trong khi chẩn đoán; xóa toàn bộ thư mục dữ liệu có thể xóa thông tin xác thực và lịch sử mà không sửa được tham chiếu model sai.

Kết thúc bằng một yêu cầu nhỏ

Sau khi lựa chọn được phân giải, hãy thử một prompt ngắn trước khi thực hiện tác vụ trên repository. Xác nhận provider dự kiến nhận được yêu cầu và ghi nhận đúng model. Nếu vẫn thất bại, thu thập phiên bản, cấu hình đã loại bỏ thông tin nhạy cảm, lỗi chính xác và đoạn log liên quan. Kiểm tra log để loại bỏ khóa và nội dung dự án trước khi chia sẻ.

Đối với Kunavo, hãy tiếp tục với hướng dẫn tích hợp OpenCode và kiểm tra bản ghi sử dụng của bạn. Mức giá hiện tại của Claude Sonnet 5 là $1,40 cho input và $7,00 cho output trên mỗi triệu token. So sánh giá chỉ hữu ích sau khi client chọn đúng tuyến.

Câu hỏi thường gặp

Tài liệu chính thức và mã nguồn provider được kiểm tra ngày 17 tháng 9 năm 2026. Ví dụ giải thích danh tính cấu hình; đây không phải là benchmark tác vụ end-to-end.