OpenCode 自訂 Provider 設定：新增任何 OpenAI 相容 API

OpenCode 內建的 provider 目錄已涵蓋 75+ 個 LLM provider，但自訂 provider 仍然很重要。你可以透過自訂 provider 來加入閘道、本機執行環境、內部推論端點，或尚未收錄在目錄中的模型。

流程很簡單：儲存憑證、新增 provider 區塊、重新啟動 OpenCode，再從 /models 中選擇模型。

想直接串接 Haimaker？ 跳過手動步驟——執行 npx -y @haimaker/connect --opencode，CLI 會自動寫入 provider 區塊並儲存你的憑證（加上 --project 參數可產生專案層級的設定檔）。下方的完整教學適用於任何 OpenAI 相容 provider——Ollama、LM Studio、內部閘道，或任何尚未收錄在目錄中的服務。只想用一行指令完成的話，請參閱串接指南。

何時該用自訂 provider

當模型或端點不在 OpenCode 內建 provider 清單中時，就會需要自訂 provider。

常見情境：

• Haimaker：一組 API 金鑰即可透過 OpenAI 相容閘道存取多個模型系列。
• Ollama：本機模型，端點為 http://localhost:11434/v1。
• LM Studio：本機模型，端點為 http://127.0.0.1:1234/v1。
• 內部閘道：公司自行託管的 OpenAI 相容端點。
• 新 provider：任何支援 OpenAI 相容 Chat API、但尚未被 OpenCode 目錄收錄的服務。

如果 provider 已經內建在 OpenCode 中，建議優先使用內建選項。當你需要自訂 base URL、閘道，或預設清單中缺少的模型時，自訂設定最能派上用場。

步驟 1：新增憑證

目前 OpenCode 文件建議用 opencode auth login 來處理 provider 憑證。若使用自訂 OpenAI 相容 provider，請選擇 Other，輸入 provider ID，再貼上 API 金鑰：

opencode auth login

選一個簡短的 provider ID，之後設定時也要用同一個 ID。例如：

haimaker
ollama
mygateway

OpenCode 會把憑證儲存在：

~/.local/share/opencode/auth.json

必要時可以手動編輯這個檔案，但用 opencode auth login 可以避免金鑰格式錯誤。

步驟 2：設定 provider

開啟或建立 OpenCode 設定檔。依你的環境而定，可能是專案中的 opencode.json，或位於 ~/.config/opencode/ 下的全域設定檔。

新增一個 provider 區塊，使用與 auth 階段相同的 provider ID。以下以 haimaker.ai 為例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

各欄位說明：

• npm：SDK 轉接器（adapter）。只要是 OpenAI 相容 API，就使用 @ai-sdk/openai-compatible。OpenCode 會視需要載入 adapter。
• name：顯示在 OpenCode 中的名稱。
• options.baseURL：這個 provider API 的 base URL。結尾應為 /v1，或該 provider 所使用的版本前綴。
• models：你想在 OpenCode 中使用的模型。鍵值必須與 provider API 在 completion 請求的 model 欄位中接受的名稱完全一致。

你可以新增任意數量的自訂 provider，每個都是 provider 下的獨立項目。

步驟 3：重新啟動並驗證

OpenCode 可能不會立刻套用 provider 設定變更。請完全退出 OpenCode，重新啟動後執行：

/models

你應該會看到 provider 的顯示名稱和已設定的模型。先選一個模型，在實際用於程式碼之前，先傳送一個簡單的 prompt 測試一下。

完整範例：Haimaker 閘道

如果你希望透過單一 OpenAI 相容端點使用多個模型系列，可以這樣設定：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

這個設定的好處是：OpenCode 只會看到一個 provider，而 Haimaker 負責處理多個上游模型系列的存取。如此一來，OpenCode 設定會更精簡，切換模型時也不會那麼麻煩。

完整範例：Ollama 本機 provider

Ollama 會在 http://localhost:11434/v1 提供 OpenAI 相容的本機端點：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

啟動 OpenCode 前，先下載模型：

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

如果 OpenCode 對本機 provider 要求驗證，請執行 opencode auth login，選擇 Other，以 ollama 作為 provider ID，並輸入任何非空字串作為金鑰，例如 ollama。Ollama 不會驗證本機 API 金鑰。

常見錯誤與修復方式

provider 沒有出現在 /models 中

檢查以下四點：

1. opencode auth login 的 provider ID 與設定檔中的 provider 鍵值一致。
2. 設定檔是有效的 JSON 或 JSONC。
3. 編輯 provider 設定後已重新啟動 OpenCode。
4. 模型已列在 provider 的 models 物件下。

第一次請求就驗證失敗

憑證遺失，或綁定到錯誤的 provider ID。執行：

opencode auth list

然後確認 provider ID 與設定完全一致。金鑰欄位中不要包含 Bearer。

模型有出現，但請求失敗

模型 ID 可能與上游 API 預期的名稱不一致。自訂 provider 會原封不動地傳送模型 ID。如果你的設定寫的是 qwen/qwen3-coder，API 就必須接受完全相同的 qwen/qwen3-coder。

以 Haimaker 為例，可以這樣測試金鑰與端點：

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

以 Ollama 為例，檢查本機模型：

ollama list

請使用輸出中的精確模型名稱。

本機模型的 tool call 失敗

本機模型對上下文長度與工具呼叫（tool call）格式更敏感。建議先用已知能妥善處理 agentic coding（代理式開發）的模型（例如 Qwen3 Coder），並控制上下文長度。OpenCode 文件也建議在 tool call 無法正常運作時，調高 Ollama 的 num_ctx。

內建 provider 停止運作

你可能不小心覆蓋了過多設定。請將自訂 provider 放在 provider 物件下，避免刪除現有 provider 項目。如果不確定，就只做最小的設定變更：先新增一個 provider ID 和一個模型，重新啟動、測試，然後再繼續加。

務實的設定組合

對大多數 OpenCode 使用者來說，最簡潔的配置是：

1. Haimaker：處理雲端模型與單一金鑰路由。
2. Ollama：處理需要隱私的本機工作。
3. 一個高階備用模型：用於複雜的除錯與多檔案重構。

這樣一來，需要隱私時有本機方案，日常工作有低成本的雲端模型，遇到需要高度專注的程式任務時則有更強的模型可依靠。

USE HAIMAKER WITH OPENCODE

---

本機設定請參閱在 OpenCode 中使用 Ollama。想找更完整的本機模型評比，請看最適合 Coding Agent 的 Ollama 模型。