找不到 OpenCode 提供者：修正模型 ID

針對 OpenCode 的提供者或找不到模型錯誤，請先將所選模型與 OpenCode 實際載入的提供者及模型 ID 配對。參照通常採用 providerId/modelId格式。正確的 API 金鑰無法修復拼寫錯誤的 ID、未宣告的自訂模型，或執行中的程序從未讀取的設定檔。

追蹤錯誤，而不只是「提供者問題」這句話

你看到的情況	首先檢查的分支
`ProviderModelNotFoundError`	提供者/模型識別、已載入的目錄與模型介面卡
v2：模型不可用	非作用中的提供者、缺少或停用的模型、變更後的探索或別名
`ProviderInitError`	提供者套件與初始化設定
端點回傳 HTTP 401 或 403	憑證、主機與帳戶權限
HTTP 429 或計費訊息	回應提供者的速率與支出限制

官方疑難排解指南會將找不到模型錯誤指向模型參照。在提供者原始碼中，查找會同時檢查提供者項目與其模型 map。同一個錯誤也可能包裝介面卡的找不到模型錯誤。在變更憑證或購買更多額度前，請擷取完整錯誤訊息。

1. 識別版本與所選模型

請從發生失敗的專案執行這些檢查。如果桌面應用程式使用不同的伺服器，請將其版本與設定和此終端機安裝進行比較：

檢查相同的安裝與專案

opencode --version
opencode models
opencode auth list

在清單中找到完整的模型參照，然後逐字元與您的選擇比較。提供者前綴是識別的一部分。透過自訂閘道提供的模型，不會僅因名稱包含 Claude 就變成內建的 Anthropic 提供者。

不要將已儲存的憑證解讀為遠端驗證成功的證明。它只能證明本機存在憑證；端點仍必須在發出請求時接受它。

2. 修正提供者/模型組合

此範例使用v1 提供者格式，並示範三個相符的識別項。請在啟動 OpenCode 的程序中設定所參照的環境變數，或使用文件所述的憑證流程。請將相關欄位合併到設定中，而不是覆寫無關的設定：

v1 風格的 opencode.json — 提供者與模型識別

{
  "$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"
        }
      }
    }
  }
}

這裡，kunavo是提供者金鑰，claude-sonnet-5是模型金鑰。因此選擇項目是 kunavo/claude-sonnet-5。選取 anthropic/claude-sonnet-5會選擇不同的提供者；選取 Kunavo/Claude Sonnet 5則會以顯示名稱取代查找金鑰。兩者都不是上方顯示的項目。

使用 /connect與 Other 作為自訂提供者時，請輸入相同的提供者 ID。憑證本身不會定義模型目錄。也請檢查介面卡：此處顯示的 v1 相容介面卡使用 Chat Completions；Responses 端點需要適當的介面卡。

3. 將 v1 與 v2 設定分開

v2 提供者文件使用 providers、package與 settings，而不是 v1 的 provider、npm與 options。請使用其特定版本的設定方式，不要將前一個區塊原封不動複製到 v2 設定中。

在 v2 中，模型的 map 金鑰也可以不同於上游的 modelID。如果 map 包含 coder並傳送上游模型 upstream/coder-v2，請為提供者 company選擇 company/coder。將選擇改成上游名稱會繞過已設定的別名。

4. 檢查哪個設定生效

OpenCode 會合併設定來源。專案檔案可以覆寫全域模型；自訂路徑、內嵌設定與受管理設定也可能發揮作用。請檢查失敗專案的檔案、全域設定與任何已設定的覆寫項目。確認提供者允許清單或停用提供者項目。

進行一項針對性變更，重新啟動受影響的程序，然後再次列出模型。如果模型現在可用，但第一次請求回傳 HTTP 錯誤，請追蹤新的錯誤。診斷期間請保留原始檔案與工作階段資料；刪除整個資料目錄可能會移除憑證與歷史記錄，卻無法修正錯誤的模型參照。

以小型請求完成檢查

選擇解析成功後，先嘗試一個簡短提示，再進行儲存庫工作。確認預期的提供者收到請求，並記錄預期的模型。如果仍然失敗，請收集版本、已清理的設定、完整錯誤與相關日誌摘錄。分享前請檢查日誌中的金鑰與專案內容。

使用 Kunavo 時，請繼續參閱OpenCode 整合指南並檢查您的用量記錄。目前的 Claude Sonnet 5費率為每百萬 token 輸入 $1.40、輸出 $7.00。用戶端選定預期路徑後，價格比較才有意義。

常見問題

OpenCode 中的 ProviderModelNotFoundError 是什麼意思？

OpenCode 無法解析所選的提供者/模型組合，或其模型介面卡無法解析該模型。在將問題歸因於餘額或 API 金鑰前，請先檢查已載入的提供者 ID、模型金鑰與作用中的設定。提供者回傳的 HTTP 回應（例如 401）屬於不同的診斷分支。

為什麼加入 API 金鑰後沒有加入自訂模型？

已儲存的憑證與提供者/模型定義用途不同。在 v1 自訂提供者流程中，透過 /connect 輸入的提供者 ID 必須與設定金鑰相符，而模型必須在該提供者的 models map 中宣告。

在 opencode.json 中應該使用 provider 還是 providers？

請配合已安裝版本的文件。v1 文件使用 provider 搭配 npm 與 options。v2 文件使用 providers 搭配 package 與 settings。混用兩種格式不是可靠的移轉方式；請遵循相符的結構描述與提供者指南。

為什麼模型在一個專案中可用，在另一個專案中卻不可用？

專案設定可能覆寫全域設定，環境、內嵌或受管理的設定也可能影響結果。請從失敗專案的工作目錄檢查所選模型與提供者設定。如果桌面用戶端連線到不同的伺服器，也請檢查該伺服器的設定。

官方文件與提供者原始碼檢查日期：2026 年 9 月 17 日。此範例說明設定識別，不是端到端工作基準測試。