---
title: 提供商
description: 在 OpenCode 中使用任意 LLM 提供商。
---

import config from "../../../../config.mjs"
export const console = config.console

OpenCode 使用 [AI SDK](https://ai-sdk.dev/) 和 [Models.dev](https://models.dev)，支援 **75+ LLM 提供商**，同時也支援執行本地模型。

要新增提供商，您需要：

1. 使用 `/connect` 指令新增提供商的 API 金鑰。
2. 在 OpenCode 設定中設定該提供商。

---

### 憑證

使用 `/connect` 指令新增提供商的 API 金鑰後，憑證會儲存在
`~/.local/share/opencode/auth.json` 中。

---

### 設定

您可以透過 OpenCode 設定中的 `provider` 部分來自訂提供商。

---

#### 自訂 Base URL

您可以透過設定 `baseURL` 選項來自訂任何提供商的 Base URL。這在使用代理服務或自訂端點時非常有用。

```json title="opencode.json" {6}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}
```

---

## OpenCode Zen

OpenCode Zen 是由 OpenCode 團隊提供的模型列表，這些模型已經過測試和驗證，能夠與 OpenCode 良好配合使用。[了解更多](/docs/zen)。

:::tip
如果您是新使用者，我們建議從 OpenCode Zen 開始。
:::

1. 在 TUI 中執行 `/connect` 指令，選擇 opencode，然後前往 [opencode.ai/auth](https://opencode.ai/auth)。

   ```txt
   /connect
   ```

2. 登入後新增帳單資訊，然後複製您的 API 金鑰。

3. 貼上您的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 在 TUI 中執行 `/models` 查看我們推薦的模型列表。

   ```txt
   /models
   ```

它的使用方式與 OpenCode 中的其他提供商完全相同，且完全可選。

---

## 目錄

下面我們來詳細了解一些提供商。如果您想將某個提供商新增到列表中，歡迎提交 PR。

:::note
沒有看到您想要的提供商？歡迎提交 PR。
:::

---

### 302.AI

1. 前往 [302.AI 控制台](https://302.ai/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **302.AI**。

   ```txt
   /connect
   ```

3. 輸入您的 302.AI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

---

### Amazon Bedrock

要在 OpenCode 中使用 Amazon Bedrock：

1. 前往 Amazon Bedrock 控制台中的**模型目錄**，申請存取您想要使用的模型。

   :::tip
   您需要先在 Amazon Bedrock 中取得對目標模型的存取權限。
   :::

2. 使用以下方法之一**設定身分驗證**：

   #### 環境變數（快速上手）

   執行 opencode 時設定以下環境變數之一：

   ```bash
   # Option 1: Using AWS access keys
   AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode

   # Option 2: Using named AWS profile
   AWS_PROFILE=my-profile opencode

   # Option 3: Using Bedrock bearer token
   AWS_BEARER_TOKEN_BEDROCK=XXX opencode
   ```

   或者將它們新增到您的 bash 設定檔中：

   ```bash title="~/.bash_profile"
   export AWS_PROFILE=my-dev-profile
   export AWS_REGION=us-east-1
   ```

   #### 設定檔（推薦）

   如需專案級別或持久化的設定，請使用 `opencode.json`：

   ```json title="opencode.json"
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "amazon-bedrock": {
         "options": {
           "region": "us-east-1",
           "profile": "my-aws-profile"
         }
       }
     }
   }
   ```

   **可用選項：**
   - `region` - AWS 區域（例如 `us-east-1`、`eu-west-1`）
   - `profile` - `~/.aws/credentials` 中的 AWS 命名設定檔
   - `endpoint` - VPC 端點的自訂端點 URL（通用 `baseURL` 選項的別名）

   :::tip
   設定檔中的選項優先順序高於環境變數。
   :::

   #### 進階：VPC 端點

   如果您使用 Bedrock 的 VPC 端點：

   ```json title="opencode.json"
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "amazon-bedrock": {
         "options": {
           "region": "us-east-1",
           "profile": "production",
           "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
         }
       }
     }
   }
   ```

   :::note
   `endpoint` 選項是通用 `baseURL` 選項的別名，使用了 AWS 特有的術語。如果同時指定了 `endpoint` 和 `baseURL`，則 `endpoint` 優先。
   :::

   #### 認證方式
   - **`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`**：在 AWS 控制台中建立 IAM 使用者並產生存取金鑰
   - **`AWS_PROFILE`**：使用 `~/.aws/credentials` 中的命名設定檔。需要先透過 `aws configure --profile my-profile` 或 `aws sso login` 進行設定
   - **`AWS_BEARER_TOKEN_BEDROCK`**：從 Amazon Bedrock 控制台產生長期 API 金鑰
   - **`AWS_WEB_IDENTITY_TOKEN_FILE` / `AWS_ROLE_ARN`**：適用於 EKS IRSA（服務帳號的 IAM 角色）或其他支援 OIDC 聯合的 Kubernetes 環境。使用服務帳號註解時，Kubernetes 會自動注入這些環境變數。

   #### 認證優先順序

   Amazon Bedrock 使用以下認證優先順序：
   1. **Bearer Token** - `AWS_BEARER_TOKEN_BEDROCK` 環境變數或透過 `/connect` 指令取得的 Token
   2. **AWS 憑證鏈** - 設定檔、存取金鑰、共享憑證、IAM 角色、Web Identity Token（EKS IRSA）、執行個體中繼資料

   :::note
   當設定了 Bearer Token（透過 `/connect` 或 `AWS_BEARER_TOKEN_BEDROCK`）時，它的優先順序高於所有 AWS 憑證方式，包括已設定的設定檔。
   :::

3. 執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

:::note
對於自訂推理設定檔，請在 key 中使用模型名稱和提供商名稱，並將 `id` 屬性設定為 ARN。這可以確保正確的快取行為：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      // ...
      "models": {
        "anthropic-claude-sonnet-4.5": {
          "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy"
        }
      }
    }
  }
}
```

:::

---

### Anthropic

1. 註冊完成後，執行 `/connect` 指令並選擇 Anthropic。

   ```txt
   /connect
   ```

2. 您可以選擇 **Claude Pro/Max** 選項，瀏覽器會自動開啟並要求您進行身分驗證。

   ```txt
   ┌ Select auth method
   │
   │ Claude Pro/Max
   │ Create an API Key
   │ Manually enter API Key
   └
   ```

3. 現在使用 `/models` 指令即可看到所有 Anthropic 模型。

   ```txt
   /models
   ```

:::info
在 OpenCode 中使用 Claude Pro/Max 訂閱不是 [Anthropic](https://anthropic.com) 官方支援的用法。
:::

##### 使用 API 金鑰

如果您沒有 Pro/Max 訂閱，也可以選擇 **Create an API Key**。瀏覽器會自動開啟並要求您登入 Anthropic，然後會提供一個代碼供您貼上到終端機中。

如果您已經有 API 金鑰，可以選擇 **Manually enter API Key** 並將其貼上到終端機中。

---

### Azure OpenAI

:::note
如果遇到 "I'm sorry, but I cannot assist with that request" 錯誤，請嘗試將 Azure 資源中的內容篩選器從 **DefaultV2** 更改為 **Default**。
:::

1. 前往 [Azure 入口網站](https://portal.azure.com/)並建立 **Azure OpenAI** 資源。您需要：
   - **資源名稱**：這會成為您的 API 端點的一部分（`https://RESOURCE_NAME.openai.azure.com/`）
   - **API 金鑰**：資源中的 `KEY 1` 或 `KEY 2`

2. 前往 [Azure AI Foundry](https://ai.azure.com/) 並部署一個模型。

   :::note
   部署名稱必須與模型名稱一致，OpenCode 才能正常運作。
   :::

3. 執行 `/connect` 指令並搜尋 **Azure**。

   ```txt
   /connect
   ```

4. 輸入您的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

5. 將資源名稱設定為環境變數：

   ```bash
   AZURE_RESOURCE_NAME=XXX opencode
   ```

   或者新增到您的 bash 設定檔中：

   ```bash title="~/.bash_profile"
   export AZURE_RESOURCE_NAME=XXX
   ```

6. 執行 `/models` 指令選擇您已部署的模型。

   ```txt
   /models
   ```

---

### Azure Cognitive Services

1. 前往 [Azure 入口網站](https://portal.azure.com/)並建立 **Azure OpenAI** 資源。您需要：
   - **資源名稱**：這會成為您的 API 端點的一部分（`https://AZURE_COGNITIVE_SERVICES_RESOURCE_NAME.cognitiveservices.azure.com/`）
   - **API 金鑰**：資源中的 `KEY 1` 或 `KEY 2`

2. 前往 [Azure AI Foundry](https://ai.azure.com/) 並部署一個模型。

   :::note
   部署名稱必須與模型名稱一致，OpenCode 才能正常運作。
   :::

3. 執行 `/connect` 指令並搜尋 **Azure Cognitive Services**。

   ```txt
   /connect
   ```

4. 輸入您的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

5. 將資源名稱設定為環境變數：

   ```bash
   AZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX opencode
   ```

   或者新增到您的 bash 設定檔中：

   ```bash title="~/.bash_profile"
   export AZURE_COGNITIVE_SERVICES_RESOURCE_NAME=XXX
   ```

6. 執行 `/models` 指令選擇您已部署的模型。

   ```txt
   /models
   ```

---

### Baseten

1. 前往 [Baseten](https://app.baseten.co/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Baseten**。

   ```txt
   /connect
   ```

3. 輸入您的 Baseten API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

---

### Cerebras

1. 前往 [Cerebras 控制台](https://inference.cerebras.ai/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Cerebras**。

   ```txt
   /connect
   ```

3. 輸入您的 Cerebras API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Qwen 3 Coder 480B_。

   ```txt
   /models
   ```

---

### Cloudflare AI Gateway

Cloudflare AI Gateway 允許您透過統一端點存取來自 OpenAI、Anthropic、Workers AI 等提供商的模型。透過 [Unified Billing](https://developers.cloudflare.com/ai-gateway/features/unified-billing/)，您無需為每個提供商單獨準備 API 金鑰。

1. 前往 [Cloudflare 儀表板](https://dash.cloudflare.com/)，導覽到 **AI** > **AI Gateway**，建立一個新的閘道。

2. 將您的 Account ID 和 Gateway ID 設定為環境變數。

   ```bash title="~/.bash_profile"
   export CLOUDFLARE_ACCOUNT_ID=your-32-character-account-id
   export CLOUDFLARE_GATEWAY_ID=your-gateway-id
   ```

3. 執行 `/connect` 指令並搜尋 **Cloudflare AI Gateway**。

   ```txt
   /connect
   ```

4. 輸入您的 Cloudflare API Token。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

   或者將其設定為環境變數。

   ```bash title="~/.bash_profile"
   export CLOUDFLARE_API_TOKEN=your-api-token
   ```

5. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

   您也可以透過 OpenCode 設定新增模型。

   ```json title="opencode.json"
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "cloudflare-ai-gateway": {
         "models": {
           "openai/gpt-4o": {},
           "anthropic/claude-sonnet-4": {}
         }
       }
     }
   }
   ```

---

### Cortecs

1. 前往 [Cortecs 控制台](https://cortecs.ai/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Cortecs**。

   ```txt
   /connect
   ```

3. 輸入您的 Cortecs API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Kimi K2 Instruct_。

   ```txt
   /models
   ```

---

### DeepSeek

1. 前往 [DeepSeek 控制台](https://platform.deepseek.com/)，建立帳號並點擊 **Create new API key**。

2. 執行 `/connect` 指令並搜尋 **DeepSeek**。

   ```txt
   /connect
   ```

3. 輸入您的 DeepSeek API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇 DeepSeek 模型，例如 _DeepSeek Reasoner_。

   ```txt
   /models
   ```

---

### Deep Infra

1. 前往 [Deep Infra 儀表板](https://deepinfra.com/dash)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Deep Infra**。

   ```txt
   /connect
   ```

3. 輸入您的 Deep Infra API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

---

### Firmware

1. 前往 [Firmware 儀表板](https://app.firmware.ai/signup)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Firmware**。

   ```txt
   /connect
   ```

3. 輸入您的 Firmware API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

---

### Fireworks AI

1. 前往 [Fireworks AI 控制台](https://app.fireworks.ai/)，建立帳號並點擊 **Create API Key**。

2. 執行 `/connect` 指令並搜尋 **Fireworks AI**。

   ```txt
   /connect
   ```

3. 輸入您的 Fireworks AI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Kimi K2 Instruct_。

   ```txt
   /models
   ```

---

### GitLab Duo

GitLab Duo 透過 GitLab 的 Anthropic 代理提供具有原生工具呼叫能力的 AI 驅動代理聊天。

1. 執行 `/connect` 指令並選擇 GitLab。

   ```txt
   /connect
   ```

2. 選擇您的身分驗證方式：

   ```txt
   ┌ Select auth method
   │
   │ OAuth (Recommended)
   │ Personal Access Token
   └
   ```

   #### 使用 OAuth（推薦）

   選擇 **OAuth**，瀏覽器會自動開啟進行授權。

   #### 使用個人存取權杖
   1. 前往 [GitLab 使用者設定 > Access Tokens](https://gitlab.com/-/user_settings/personal_access_tokens)
   2. 點擊 **Add new token**
   3. 名稱填寫 `OpenCode`，範圍選擇 `api`
   4. 複製權杖（以 `glpat-` 開頭）
   5. 在終端機中輸入該權杖

3. 執行 `/models` 指令查看可用模型。

   ```txt
   /models
   ```

   提供三個基於 Claude 的模型：
   - **duo-chat-haiku-4-5**（預設）- 快速回應，適合簡單任務
   - **duo-chat-sonnet-4-5** - 效能均衡，適合大多數工作流程
   - **duo-chat-opus-4-5** - 最強大，適合複雜分析

:::note
您也可以透過指定 `GITLAB_TOKEN` 環境變數來避免將權杖儲存在 OpenCode 的認證儲存中。
:::

##### 自架 GitLab

:::note[合規說明]
OpenCode 會使用一個小模型來執行部分 AI 任務，例如產生工作階段標題。預設情況下使用由 Zen 託管的 gpt-5-nano。如果您需要讓 OpenCode 僅使用您自己的 GitLab 託管實例，請在 `opencode.json` 檔案中新增以下內容。同時建議停用工作階段分享。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "small_model": "gitlab/duo-chat-haiku-4-5",
  "share": "disabled"
}
```

:::

對於自架 GitLab 實例：

```bash
export GITLAB_INSTANCE_URL=https://gitlab.company.com
export GITLAB_TOKEN=glpat-...
```

如果您的實例執行了自訂 AI Gateway：

```bash
GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com
```

或者新增到您的 bash 設定檔中：

```bash title="~/.bash_profile"
export GITLAB_INSTANCE_URL=https://gitlab.company.com
export GITLAB_AI_GATEWAY_URL=https://ai-gateway.company.com
export GITLAB_TOKEN=glpat-...
```

:::note
您的 GitLab 管理員必須啟用以下功能：

1. 為使用者、群組或實例啟用 [Duo Agent Platform](https://docs.gitlab.com/user/gitlab_duo/turn_on_off/)
2. 功能旗標（透過 Rails 控制台）：
   - `agent_platform_claude_code`
   - `third_party_agents_enabled`
     :::

##### 自架實例的 OAuth

要在自架實例上使用 OAuth，您需要建立一個新應用程式（設定 → 應用程式），回呼 URL 設定為 `http://127.0.0.1:8080/callback`，並選擇以下範圍：

- api（代表您存取 API）
- read_user（讀取您的個人資訊）
- read_repository（允許對儲存庫進行唯讀存取）

然後將應用程式 ID 匯出為環境變數：

```bash
export GITLAB_OAUTH_CLIENT_ID=your_application_id_here
```

更多文件請參閱 [opencode-gitlab-auth](https://www.npmjs.com/package/@gitlab/opencode-gitlab-auth) 首頁。

##### 設定

透過 `opencode.json` 進行自訂設定：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gitlab": {
      "options": {
        "instanceUrl": "https://gitlab.com",
        "featureFlags": {
          "duo_agent_platform_agentic_chat": true,
          "duo_agent_platform": true
        }
      }
    }
  }
}
```

##### GitLab API 工具（可選，但強烈推薦）

要存取 GitLab 工具（合併請求、Issue、流水線、CI/CD 等）：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@gitlab/opencode-gitlab-plugin"]
}
```

該外掛提供全面的 GitLab 儲存庫管理功能，包括 MR 審查、Issue 追蹤、流水線監控等。

---

### GitHub Copilot

要在 OpenCode 中使用您的 GitHub Copilot 訂閱：

:::note
部分模型可能需要 [Pro+ 訂閱](https://github.com/features/copilot/plans)才能使用。
:::

1. 執行 `/connect` 指令並搜尋 GitHub Copilot。

   ```txt
   /connect
   ```

2. 前往 [github.com/login/device](https://github.com/login/device) 並輸入驗證碼。

   ```txt
   ┌ Login with GitHub Copilot
   │
   │ https://github.com/login/device
   │
   │ Enter code: 8F43-6FCF
   │
   └ Waiting for authorization...
   ```

3. 現在執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

---

### Google Vertex AI

要在 OpenCode 中使用 Google Vertex AI：

1. 前往 Google Cloud Console 中的**模型花園**，查看您所在區域可用的模型。

   :::note
   您需要一個啟用了 Vertex AI API 的 Google Cloud 專案。
   :::

2. 設定所需的環境變數：
   - `GOOGLE_CLOUD_PROJECT`：您的 Google Cloud 專案 ID
   - `VERTEX_LOCATION`（可選）：Vertex AI 的區域（預設為 `global`）
   - 身分驗證（選擇其一）：
     - `GOOGLE_APPLICATION_CREDENTIALS`：服務帳號 JSON 金鑰檔案的路徑
     - 使用 gcloud CLI 進行身分驗證：`gcloud auth application-default login`

   在執行 opencode 時設定：

   ```bash
   GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json GOOGLE_CLOUD_PROJECT=your-project-id opencode
   ```

   或者新增到您的 bash 設定檔中：

   ```bash title="~/.bash_profile"
   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
   export GOOGLE_CLOUD_PROJECT=your-project-id
   export VERTEX_LOCATION=global
   ```

:::tip
`global` 區域可以提高可用性並減少錯誤，且不會產生額外費用。如果有資料駐留需求，請使用區域端點（例如 `us-central1`）。[了解更多](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#regional_and_global_endpoints)
:::

3. 執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

---

### Groq

1. 前往 [Groq 控制台](https://console.groq.com/)，點擊 **Create API Key** 並複製金鑰。

2. 執行 `/connect` 指令並搜尋 Groq。

   ```txt
   /connect
   ```

3. 輸入該提供商的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

---

### Hugging Face

[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) 提供對由 17+ 提供商支援的開放模型的存取。

1. 前往 [Hugging Face 設定](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained)，建立一個具有呼叫 Inference Providers 權限的權杖。

2. 執行 `/connect` 指令並搜尋 **Hugging Face**。

   ```txt
   /connect
   ```

3. 輸入您的 Hugging Face 權杖。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Kimi-K2-Instruct_ 或 _GLM-4.6_。

   ```txt
   /models
   ```

---

### Helicone

[Helicone](https://helicone.ai) 是一個 LLM 可觀測性平台，為您的 AI 應用程式提供日誌記錄、監控和分析功能。Helicone AI Gateway 會根據模型自動將請求路由到對應的提供商。

1. 前往 [Helicone](https://helicone.ai)，建立帳號並在儀表板中產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Helicone**。

   ```txt
   /connect
   ```

3. 輸入您的 Helicone API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

如需了解更多提供商以及快取、速率限制等進階功能，請查閱 [Helicone 文件](https://docs.helicone.ai)。

#### 可選設定

如果 Helicone 的某些功能或模型未透過 OpenCode 自動設定，您隨時可以手動設定。

[Helicone 模型目錄](https://helicone.ai/models)中可以找到您需要新增的模型 ID。

```jsonc title="~/.config/opencode/opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
      },
      "models": {
        "gpt-4o": {
          // Model ID (from Helicone's model directory page)
          "name": "GPT-4o", // Your own custom name for the model
        },
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
        },
      },
    },
  },
}
```

#### 自訂請求標頭

Helicone 支援用於快取、使用者追蹤和工作階段管理等功能的自訂請求標頭。使用 `options.headers` 將它們新增到提供商設定中：

```jsonc title="~/.config/opencode/opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helicone": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helicone",
      "options": {
        "baseURL": "https://ai-gateway.helicone.ai",
        "headers": {
          "Helicone-Cache-Enabled": "true",
          "Helicone-User-Id": "opencode",
        },
      },
    },
  },
}
```

##### 工作階段追蹤

Helicone 的 [Sessions](https://docs.helicone.ai/features/sessions) 功能允許您將相關的 LLM 請求歸為一組。使用 [opencode-helicone-session](https://github.com/H2Shami/opencode-helicone-session) 外掛可以自動將每個 OpenCode 對話記錄為 Helicone 中的一個工作階段。

```bash
npm install -g opencode-helicone-session
```

將其新增到設定中。

```json title="opencode.json"
{
  "plugin": ["opencode-helicone-session"]
}
```

該外掛會在您的請求中注入 `Helicone-Session-Id` 和 `Helicone-Session-Name` 請求標頭。在 Helicone 的 Sessions 頁面中，您可以看到每個 OpenCode 對話都作為獨立的工作階段列出。

##### 常用 Helicone 請求標頭

| 請求標頭                   | 描述                                                 |
| -------------------------- | ---------------------------------------------------- |
| `Helicone-Cache-Enabled`   | 啟用回應快取（`true`/`false`）                       |
| `Helicone-User-Id`         | 按使用者追蹤指標                                     |
| `Helicone-Property-[Name]` | 新增自訂屬性（例如 `Helicone-Property-Environment`） |
| `Helicone-Prompt-Id`       | 將請求與提示詞版本關聯                               |

有關所有可用請求標頭，請參閱 [Helicone Header Directory](https://docs.helicone.ai/helicone-headers/header-directory)。

---

### llama.cpp

您可以透過 [llama.cpp](https://github.com/ggml-org/llama.cpp) 的 llama-server 工具設定 OpenCode 使用本地模型。

```json title="opencode.json" "llama.cpp" {5, 6, 8, 10-15}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder: a3b-30b (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}
```

在這個範例中：

- `llama.cpp` 是自訂的提供商 ID，可以是任意字串。
- `npm` 指定該提供商使用的套件。這裡使用 `@ai-sdk/openai-compatible` 來相容任何 OpenAI 相容的 API。
- `name` 是該提供商在 UI 中顯示的名稱。
- `options.baseURL` 是本地伺服器的端點位址。
- `models` 是模型 ID 到其設定的對應。模型名稱會顯示在模型選擇列表中。

---

### IO.NET

IO.NET 提供 17 個針對不同使用情境最佳化的模型：

1. 前往 [IO.NET 控制台](https://ai.io.net/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **IO.NET**。

   ```txt
   /connect
   ```

3. 輸入您的 IO.NET API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

---

### LM Studio

您可以透過 LM Studio 設定 OpenCode 使用本地模型。

```json title="opencode.json" "lmstudio" {5, 6, 8, 10-14}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}
```

在這個範例中：

- `lmstudio` 是自訂的提供商 ID，可以是任意字串。
- `npm` 指定該提供商使用的套件。這裡使用 `@ai-sdk/openai-compatible` 來相容任何 OpenAI 相容的 API。
- `name` 是該提供商在 UI 中顯示的名稱。
- `options.baseURL` 是本地伺服器的端點位址。
- `models` 是模型 ID 到其設定的對應。模型名稱會顯示在模型選擇列表中。

---

### Moonshot AI

要使用 Moonshot AI 的 Kimi K2：

1. 前往 [Moonshot AI 控制台](https://platform.moonshot.ai/console)，建立帳號並點擊 **Create API key**。

2. 執行 `/connect` 指令並搜尋 **Moonshot AI**。

   ```txt
   /connect
   ```

3. 輸入您的 Moonshot API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇 _Kimi K2_。

   ```txt
   /models
   ```

---

### MiniMax

1. 前往 [MiniMax API 控制台](https://platform.minimax.io/login)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **MiniMax**。

   ```txt
   /connect
   ```

3. 輸入您的 MiniMax API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _M2.1_。

   ```txt
   /models
   ```

---

### Nebius Token Factory

1. 前往 [Nebius Token Factory 控制台](https://tokenfactory.nebius.com/)，建立帳號並點擊 **Add Key**。

2. 執行 `/connect` 指令並搜尋 **Nebius Token Factory**。

   ```txt
   /connect
   ```

3. 輸入您的 Nebius Token Factory API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Kimi K2 Instruct_。

   ```txt
   /models
   ```

---

### Ollama

您可以透過 Ollama 設定 OpenCode 使用本地模型。

:::tip
Ollama 可以自動為 OpenCode 進行設定。詳見 [Ollama 整合文件](https://docs.ollama.com/integrations/opencode)。
:::

```json title="opencode.json" "ollama" {5, 6, 8, 10-14}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}
```

在這個範例中：

- `ollama` 是自訂的提供商 ID，可以是任意字串。
- `npm` 指定該提供商使用的套件。這裡使用 `@ai-sdk/openai-compatible` 來相容任何 OpenAI 相容的 API。
- `name` 是該提供商在 UI 中顯示的名稱。
- `options.baseURL` 是本地伺服器的端點位址。
- `models` 是模型 ID 到其設定的對應。模型名稱會顯示在模型選擇列表中。

:::tip
如果工具呼叫不運作，請嘗試增大 Ollama 中的 `num_ctx` 值。建議從 16k - 32k 左右開始。
:::

---

### Ollama Cloud

要在 OpenCode 中使用 Ollama Cloud：

1. 前往 [https://ollama.com/](https://ollama.com/) 登入或建立帳號。

2. 導覽到 **Settings** > **Keys**，點擊 **Add API Key** 產生新的 API 金鑰。

3. 複製 API 金鑰以便在 OpenCode 中使用。

4. 執行 `/connect` 指令並搜尋 **Ollama Cloud**。

   ```txt
   /connect
   ```

5. 輸入您的 Ollama Cloud API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

6. **重要**：在 OpenCode 中使用雲端模型之前，必須先將模型資訊拉取到本地：

   ```bash
   ollama pull gpt-oss:20b-cloud
   ```

7. 執行 `/models` 指令選擇您的 Ollama Cloud 模型。

   ```txt
   /models
   ```

---

### OpenAI

我們建議註冊 [ChatGPT Plus 或 Pro](https://chatgpt.com/pricing)。

1. 註冊完成後，執行 `/connect` 指令並選擇 OpenAI。

   ```txt
   /connect
   ```

2. 您可以選擇 **ChatGPT Plus/Pro** 選項，瀏覽器會自動開啟並要求您進行身分驗證。

   ```txt
   ┌ Select auth method
   │
   │ ChatGPT Plus/Pro
   │ Manually enter API Key
   └
   ```

3. 現在使用 `/models` 指令即可看到所有 OpenAI 模型。

   ```txt
   /models
   ```

##### 使用 API 金鑰

如果您已經有 API 金鑰，可以選擇 **Manually enter API Key** 並將其貼上到終端機中。

---

### OpenCode Zen

OpenCode Zen 是由 OpenCode 團隊提供的經過測試和驗證的模型列表。[了解更多](/docs/zen)。

1. 登入 **<a href={console}>OpenCode Zen</a>** 並點擊 **Create API Key**。

2. 執行 `/connect` 指令並搜尋 **OpenCode Zen**。

   ```txt
   /connect
   ```

3. 輸入您的 OpenCode API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Qwen 3 Coder 480B_。

   ```txt
   /models
   ```

---

### OpenRouter

1. 前往 [OpenRouter 儀表板](https://openrouter.ai/settings/keys)，點擊 **Create API Key** 並複製金鑰。

2. 執行 `/connect` 指令並搜尋 OpenRouter。

   ```txt
   /connect
   ```

3. 輸入該提供商的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 預設已預先載入了許多 OpenRouter 模型，執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

   您也可以透過 OpenCode 設定新增更多模型。

   ```json title="opencode.json" {6}
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "openrouter": {
         "models": {
           "somecoolnewmodel": {}
         }
       }
     }
   }
   ```

5. 您還可以透過 OpenCode 設定自訂模型。以下是指定提供商的範例：

   ```json title="opencode.json"
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "openrouter": {
         "models": {
           "moonshotai/kimi-k2": {
             "options": {
               "provider": {
                 "order": ["baseten"],
                 "allow_fallbacks": false
               }
             }
           }
         }
       }
     }
   }
   ```

---

### SAP AI Core

SAP AI Core 透過統一平台提供對來自 OpenAI、Anthropic、Google、Amazon、Meta、Mistral 和 AI21 的 40+ 模型的存取。

1. 前往 [SAP BTP Cockpit](https://account.hana.ondemand.com/)，導覽到您的 SAP AI Core 服務實例，並建立服務金鑰。

   :::tip
   服務金鑰是一個包含 `clientid`、`clientsecret`、`url` 和 `serviceurls.AI_API_URL` 的 JSON 物件。您可以在 BTP Cockpit 的 **Services** > **Instances and Subscriptions** 下找到您的 AI Core 實例。
   :::

2. 執行 `/connect` 指令並搜尋 **SAP AI Core**。

   ```txt
   /connect
   ```

3. 輸入您的服務金鑰 JSON。

   ```txt
   ┌ Service key
   │
   │
   └ enter
   ```

   或者設定 `AICORE_SERVICE_KEY` 環境變數：

   ```bash
   AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}' opencode
   ```

   或者新增到您的 bash 設定檔中：

   ```bash title="~/.bash_profile"
   export AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'
   ```

4. 可選：設定部署 ID 和資源群組：

   ```bash
   AICORE_DEPLOYMENT_ID=your-deployment-id AICORE_RESOURCE_GROUP=your-resource-group opencode
   ```

   :::note
   這些設定是可選的，應根據您的 SAP AI Core 設定進行配置。
   :::

5. 執行 `/models` 指令從 40+ 個可用模型中進行選擇。

   ```txt
   /models
   ```

---

### STACKIT

STACKIT AI Model Serving 提供完全託管的主權託管環境，專注於 Llama、Mistral 和 Qwen 等大語言模型，在歐洲基礎設施上實現最大程度的資料主權。

1. 前往 [STACKIT Portal](https://portal.stackit.cloud)，導覽到 **AI Model Serving**，為您的專案建立認證權杖。

   :::tip
   您需要先擁有 STACKIT 客戶帳號、使用者帳號和專案，才能建立認證權杖。
   :::

2. 執行 `/connect` 指令並搜尋 **STACKIT**。

   ```txt
   /connect
   ```

3. 輸入您的 STACKIT AI Model Serving 認證權杖。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Qwen3-VL 235B_ 或 _Llama 3.3 70B_。

   ```txt
   /models
   ```

---

### OVHcloud AI Endpoints

1. 前往 [OVHcloud 管理面板](https://ovh.com/manager)。導覽到 `Public Cloud` 部分，`AI & Machine Learning` > `AI Endpoints`，在 `API Keys` 分頁中點擊 **Create a new API key**。

2. 執行 `/connect` 指令並搜尋 **OVHcloud AI Endpoints**。

   ```txt
   /connect
   ```

3. 輸入您的 OVHcloud AI Endpoints API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _gpt-oss-120b_。

   ```txt
   /models
   ```

---

### Scaleway

要在 OpenCode 中使用 [Scaleway Generative APIs](https://www.scaleway.com/en/docs/generative-apis/)：

1. 前往 [Scaleway Console IAM 設定](https://console.scaleway.com/iam/api-keys)產生新的 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Scaleway**。

   ```txt
   /connect
   ```

3. 輸入您的 Scaleway API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _devstral-2-123b-instruct-2512_ 或 _gpt-oss-120b_。

   ```txt
   /models
   ```

---

### Together AI

1. 前往 [Together AI 控制台](https://api.together.ai)，建立帳號並點擊 **Add Key**。

2. 執行 `/connect` 指令並搜尋 **Together AI**。

   ```txt
   /connect
   ```

3. 輸入您的 Together AI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Kimi K2 Instruct_。

   ```txt
   /models
   ```

---

### Venice AI

1. 前往 [Venice AI 控制台](https://venice.ai)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Venice AI**。

   ```txt
   /connect
   ```

3. 輸入您的 Venice AI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Llama 3.3 70B_。

   ```txt
   /models
   ```

---

### Vercel AI Gateway

Vercel AI Gateway 允許您透過統一端點存取來自 OpenAI、Anthropic、Google、xAI 等提供商的模型。模型按原價提供，不額外加價。

1. 前往 [Vercel 儀表板](https://vercel.com/)，導覽到 **AI Gateway** 分頁，點擊 **API keys** 建立新的 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **Vercel AI Gateway**。

   ```txt
   /connect
   ```

3. 輸入您的 Vercel AI Gateway API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型。

   ```txt
   /models
   ```

您也可以透過 OpenCode 設定自訂模型。以下是指定提供商路由順序的範例。

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "vercel": {
      "models": {
        "anthropic/claude-sonnet-4": {
          "options": {
            "order": ["anthropic", "vertex"]
          }
        }
      }
    }
  }
}
```

一些常用的路由選項：

| 選項                | 描述                             |
| ------------------- | -------------------------------- |
| `order`             | 提供商嘗試順序                   |
| `only`              | 限制為特定提供商                 |
| `zeroDataRetention` | 僅使用具有零資料留存策略的提供商 |

---

### xAI

1. 前往 [xAI 控制台](https://console.x.ai/)，建立帳號並產生 API 金鑰。

2. 執行 `/connect` 指令並搜尋 **xAI**。

   ```txt
   /connect
   ```

3. 輸入您的 xAI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _Grok Beta_。

   ```txt
   /models
   ```

---

### Z.AI

1. 前往 [Z.AI API 控制台](https://z.ai/manage-apikey/apikey-list)，建立帳號並點擊 **Create a new API key**。

2. 執行 `/connect` 指令並搜尋 **Z.AI**。

   ```txt
   /connect
   ```

   如果您訂閱了 **GLM Coding Plan**，請選擇 **Z.AI Coding Plan**。

3. 輸入您的 Z.AI API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 執行 `/models` 指令選擇模型，例如 _GLM-4.7_。

   ```txt
   /models
   ```

---

### ZenMux

1. 前往 [ZenMux 儀表板](https://zenmux.ai/settings/keys)，點擊 **Create API Key** 並複製金鑰。

2. 執行 `/connect` 指令並搜尋 ZenMux。

   ```txt
   /connect
   ```

3. 輸入該提供商的 API 金鑰。

   ```txt
   ┌ API key
   │
   │
   └ enter
   ```

4. 預設已預先載入了許多 ZenMux 模型，執行 `/models` 指令選擇您想要的模型。

   ```txt
   /models
   ```

   您也可以透過 OpenCode 設定新增更多模型。

   ```json title="opencode.json" {6}
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "zenmux": {
         "models": {
           "somecoolnewmodel": {}
         }
       }
     }
   }
   ```

---

## 自訂提供商

要新增 `/connect` 指令中未列出的任何 **OpenAI 相容**提供商：

:::tip
您可以在 OpenCode 中使用任何 OpenAI 相容的提供商。大多數現代 AI 提供商都提供 OpenAI 相容的 API。
:::

1. 執行 `/connect` 指令，向下捲動到 **Other**。

   ```bash
   $ /connect

   ┌  Add credential
   │
   ◆  Select provider
   │  ...
   │  ● Other
   └
   ```

2. 輸入該提供商的唯一 ID。

   ```bash
   $ /connect

   ┌  Add credential
   │
   ◇  Enter provider id
   │  myprovider
   └
   ```

   :::note
   請選擇一個容易記住的 ID，您將在設定檔中使用它。
   :::

3. 輸入該提供商的 API 金鑰。

   ```bash
   $ /connect

   ┌  Add credential
   │
   ▲  This only stores a credential for myprovider - you will need to configure it in opencode.json, check the docs for examples.
   │
   ◇  Enter your API key
   │  sk-...
   └
   ```

4. 在專案目錄中建立或更新 `opencode.json` 檔案：

   ```json title="opencode.json" ""myprovider"" {5-15}
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "myprovider": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "My AI ProviderDisplay Name",
         "options": {
           "baseURL": "https://api.myprovider.com/v1"
         },
         "models": {
           "my-model-name": {
             "name": "My Model Display Name"
           }
         }
       }
     }
   }
   ```

   以下是設定選項說明：
   - **npm**：要使用的 AI SDK 套件，對於 OpenAI 相容的提供商使用 `@ai-sdk/openai-compatible`
   - **name**：在 UI 中顯示的名稱。
   - **models**：可用模型。
   - **options.baseURL**：API 端點 URL。
   - **options.apiKey**：可選，如果不使用 auth 認證，可直接設定 API 金鑰。
   - **options.headers**：可選，設定自訂請求標頭。

   更多進階選項請參見下面的範例。

5. 執行 `/models` 指令，您自訂的提供商和模型將出現在選擇列表中。

---

##### 範例

以下是設定 `apiKey`、`headers` 和模型 `limit` 選項的範例。

```json title="opencode.json" {9,11,17-20}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "headers": {
          "Authorization": "Bearer custom-token"
        }
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}
```

設定詳情：

- **apiKey**：使用 `env` 變數語法設定，[了解更多](/docs/config#env-vars)。
- **headers**：隨每個請求傳送的自訂請求標頭。
- **limit.context**：模型接受的最大輸入 Token 數。
- **limit.output**：模型可產生的最大 Token 數。

`limit` 欄位讓 OpenCode 了解您還剩餘多少上下文空間。標準提供商會自動從 models.dev 拉取這些資訊。

---

## 疑難排解

如果您在設定提供商時遇到問題，請檢查以下幾點：

1. **檢查認證設定**：執行 `opencode auth list` 查看該提供商的憑證是否已新增到設定中。

   這不適用於 Amazon Bedrock 等依賴環境變數進行認證的提供商。

2. 對於自訂提供商，請檢查 OpenCode 設定並確認：
   - `/connect` 指令中使用的提供商 ID 與 OpenCode 設定中的 ID 一致。
   - 使用了正確的 npm 套件。例如，Cerebras 應使用 `@ai-sdk/cerebras`。對於其他所有 OpenAI 相容的提供商，使用 `@ai-sdk/openai-compatible`。
   - `options.baseURL` 欄位中的 API 端點位址正確。
