OpenCode 自訂供應商設定

確認設定範圍與相容介面

網站維護中。以下為規劃中的設定教學；api.ubtl.net 是預定網域，沒有執行真實 API 測試，不代表 OpenCode 已能連線。使用前須確認服務支援的 OpenAI 相容協定、路徑、驗證方式及模型識別碼。

先決定要使用專案或使用者層級的設定，再找出該版本實際讀取的 opencode.json。備份原檔並檢查其他設定來源是否會覆蓋它；共享專案不應包含個人金鑰。下列內容是需合併的最小供應商範例，不是覆蓋既有工具、權限或其他供應商的完整範本。

加入套件、網址與模型

provider.ubtl 使用 @ai-sdk/openai-compatible。options 中的欄位名稱是 baseURL，URL 必須維持大寫；預定值為 https://api.ubtl.net/v1，不是任意完整請求路徑。models 的物件鍵與頂層 model 的後半部都須取代成同一個經確認的模型識別碼，不要以顯示名稱代替。

apiKey 的 {env:UBTL_API_KEY} 是環境變數參照，與其他工具的參照語法不同，請完整保留。日後在啟動 OpenCode 的程序環境中設定獨立金鑰，不要把真實值直接寫入 JSON。若從桌面捷徑或服務啟動，必須另外確認其環境來源，避免把缺少變數誤判成模型問題。

需合併的 OpenCode JSON 範例 · json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ubtl": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "UBTL",
      "options": {
        "baseURL": "https://api.ubtl.net/v1",
        "apiKey": "{env:UBTL_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {"name": "UBTL model"}
      }
    }
  },
  "model": "ubtl/YOUR_MODEL_ID"
}

重啟、選模與排查

儲存後重新啟動 OpenCode，先確認設定能解析，再透過 /models 檢查自訂供應商與模型選擇；清單中出現模型並不能證明遠端支援。只有服務確認可用後，才在無私人資料的測試目錄傳送短提示，並維持工具權限最小化。認證錯誤先查變數繼承，路徑錯誤查 baseURL 與重複 /v1，模型錯誤查完整識別碼與權限。分享診斷時遮蔽金鑰，回復時還原備份並再次重啟。