--- title: OpenCode 自訂 Provider 設定：新增任何 OpenAI 相容 API description: >- 將 Haimaker、Ollama、OpenRouter 或任何 OpenAI 相容 API 加入 OpenCode。內容涵蓋 opencode auth login、opencode.json 設定、本機模型設定，以及常見的 provider 錯誤處理。 date: 2026-04-12T00:00:00.000Z updatedDate: 2026-06-26T00:00:00.000Z location: 'San Francisco, CA – 2026 年 4 月 12 日' image: /images/opencode-custom-provider-setup-hero.jpg keywords: >- opencode 自訂 provider, opencode 新增 provider, opencode 模型 provider, opencode openai 相容, opencode haimaker, opencode llm provider, opencode provider 設定, opencode 本機 provider faq: - question: 如何將自訂 LLM provider 加入 OpenCode？ answer: >- 執行 'opencode auth login'，選擇 Other 以儲存 provider 憑證；然後在 opencode.json 中新增對應的 provider 項目，將 npm 設為 '@ai-sdk/openai-compatible'，baseURL 指向你的 API，並在 'models' 下填入你要使用的模型。重新啟動 OpenCode，再用 /models 選取即可。若使用 Haimaker，執行 'npx -y @haimaker/connect --opencode' 就會自動寫入憑證與 provider 區塊。 - question: 為什麼我的自訂 provider 沒有出現在 /models 中？ answer: >- 常見原因包括：憑證與設定檔中的 provider ID 不一致、opencode.json 的 JSON 格式無效、模型 ID 與上游 API 不符，或是在編輯 provider 設定後忘了重新啟動 OpenCode。 - question: 可以在 OpenCode 中對多個 provider 使用同一個 OpenAI 相容 API 嗎？ answer: >- 可以。'provider' 區塊中的每個項目各自獨立，因此你可以把 Haimaker、Ollama、OpenRouter、LM Studio 及內部閘道分別新增為不同 provider。請使用不重複的 provider ID，方便閱讀 /models 清單。 locale: zh-tw translationKey: opencode-custom-provider-setup --- OpenCode 內建的 provider 目錄已涵蓋 75+ 個 LLM provider，但自訂 provider 仍然很重要。你可以透過自訂 provider 來加入閘道、本機執行環境、內部推論端點，或尚未收錄在目錄中的模型。 流程很簡單：儲存憑證、新增 provider 區塊、重新啟動 OpenCode，再從 `/models` 中選擇模型。 > **想直接串接 Haimaker？** 跳過手動步驟——執行 `npx -y @haimaker/connect --opencode`，CLI 會自動寫入 provider 區塊並儲存你的憑證（加上 `--project` 參數可產生專案層級的設定檔）。下方的完整教學適用於*任何* OpenAI 相容 provider——Ollama、LM Studio、內部閘道，或任何尚未收錄在目錄中的服務。只想用一行指令完成的話，請參閱[串接指南](/connect)。 ## 何時該用自訂 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 金鑰： ```bash opencode auth login ``` 選一個簡短的 provider ID，之後設定時也要用同一個 ID。例如： ```text haimaker ollama mygateway ``` OpenCode 會把憑證儲存在： ```text ~/.local/share/opencode/auth.json ``` 必要時可以手動編輯這個檔案，但用 `opencode auth login` 可以避免金鑰格式錯誤。 ## 步驟 2：設定 provider 開啟或建立 OpenCode 設定檔。依你的環境而定，可能是專案中的 `opencode.json`，或位於 `~/.config/opencode/` 下的全域設定檔。 新增一個 `provider` 區塊，使用與 auth 階段相同的 provider ID。以下以 [haimaker.ai](https://haimaker.ai) 為例： ```jsonc { "$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，重新啟動後執行： ```text /models ``` 你應該會看到 provider 的顯示名稱和已設定的模型。先選一個模型，在實際用於程式碼之前，先傳送一個簡單的 prompt 測試一下。 ## 完整範例：Haimaker 閘道 如果你希望透過單一 OpenAI 相容端點使用多個模型系列，可以這樣設定： ```jsonc { "$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 相容的本機端點： ```jsonc { "$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 前，先下載模型： ```bash 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。執行： ```bash opencode auth list ``` 然後確認 provider ID 與設定完全一致。金鑰欄位中不要包含 `Bearer`。 #### 模型有出現，但請求失敗 模型 ID 可能與上游 API 預期的名稱不一致。自訂 provider 會原封不動地傳送模型 ID。如果你的設定寫的是 `qwen/qwen3-coder`，API 就必須接受完全相同的 `qwen/qwen3-coder`。 以 Haimaker 為例，可以這樣測試金鑰與端點： ```bash curl https://api.haimaker.ai/v1/models \ -H "Authorization: Bearer your-haimaker-api-key" ``` 以 Ollama 為例，檢查本機模型： ```bash 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](/zh-tw/blog/opencode連接ollama本機模型/)。想找更完整的本機模型評比，請看[最適合 Coding Agent 的 Ollama 模型](/zh-tw/blog/適合程式設計代理的最佳ollama模型/)。*