ApiFluxAI | 使用 ApiFlux 設定 OpenCode

安裝 OpenCode，新增 ApiFlux Provider 與 API Key，選擇模型並驗證請求。

本指南介紹如何將 OpenCode 連線到 ApiFlux。設定完成後，OpenCode 可以透過 ApiFlux 的 OpenAI-compatible 介面傳送模型請求。

適用場景

適合希望在 OpenCode 中使用 ApiFlux 統一管理模型存取、用量、紀錄和模型切換的使用者。

如果使用者還沒有安裝終端機或 Node.js，建議先閱讀：

ApiFlux 使用前準備：安裝終端機和基礎環境

準備工作

開始前，請準備：

一個 ApiFlux API Key
一個 ApiFlux 支援的模型 ID
ApiFlux Base URL：

https://apiflux.ai/v1

模型 ID 請從 ApiFlux Models 頁面複製。

1. 安裝 OpenCode

Windows

OpenCode 官方文件建議 Windows 使用者優先使用 WSL，以獲得更接近 Linux / macOS 的開發體驗。

如果使用 Windows 原生 PowerShell，可以選擇以下任一方式安裝。

使用 npm：

npm install -g opencode-ai

使用 Chocolatey：

choco install opencode

使用 Scoop：

scoop install opencode

如果使用 WSL，請在 WSL 終端機中按 macOS / Linux 命令安裝。

macOS / Linux

使用官方安裝指令碼：

curl -fsSL https://opencode.ai/install | bash

也可以使用 npm：

npm install -g opencode-ai

macOS 使用者也可以使用 Homebrew：

brew install anomalyco/tap/opencode

安裝完成後，關閉終端機並重新開啟。

2. 確認 OpenCode 已安裝

在終端機中執行：

opencode --version

如果能看到版本號，說明 OpenCode 已安裝成功。

如果提示 command not found 或「不是內部或外部命令」，請重新開啟終端機；如果仍然失敗，請重新執行安裝命令。

3. 使用 /connect 檢視內建 Provider

啟動 OpenCode：

opencode

進入後輸入：

/connect

如果列表中已經包含 ApiFlux，可以按介面提示填寫 API Key。

如果列表中沒有 ApiFlux，可以使用 OpenAI-compatible custom provider 手動設定。

4. 設定 API Key 環境變數

建議透過環境變數提供 API Key，而不是把真實 Key 直接寫入設定檔。

Windows PowerShell

目前視窗暫時生效：

$env:APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

檢查是否生效：

echo $env:APIFLUX_API_KEY

長期生效：

[Environment]::SetEnvironmentVariable("APIFLUX_API_KEY","YOUR_APIFLUX_API_KEY","User")

設定長期環境變數後，請關閉 PowerShell，再重新開啟。

macOS / Linux

目前視窗暫時生效：

export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

檢查是否生效：

echo $APIFLUX_API_KEY

macOS 預設通常是 zsh，長期生效可以寫入 ~/.zshrc：

echo 'export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"' >> ~/.zshrc
source ~/.zshrc

Linux 常見是 bash，長期生效可以寫入 ~/.bashrc：

echo 'export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"' >> ~/.bashrc
source ~/.bashrc

[!WARNING] 不要將真實 API Key 提交到 GitHub，也不要出現在公開影片、公開截圖或團隊共享文件中。

5. 設定 OpenCode Provider

建議先使用專案級設定檔。也就是說，在使用者目前專案資料夾下建立：

opencode.json

這樣 Windows、macOS、Linux 都可以使用同樣的設定檔名。

如果已有 opencode.json，請合併 provider 設定，不要覆蓋原有設定。

加入以下設定：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiflux": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiFlux",
      "options": {
        "baseURL": "https://apiflux.ai/v1",
        "apiKey": "{env:APIFLUX_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {}
      }
    }
  }
}

將 YOUR_MODEL_ID 替換為 ApiFlux Models 頁面中顯示的模型 ID。

示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiflux": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiFlux",
      "options": {
        "baseURL": "https://apiflux.ai/v1",
        "apiKey": "{env:APIFLUX_API_KEY}"
      },
      "models": {
        "deepseek-v4-pro": {}
      }
    }
  }
}

[!NOTE] deepseek-v4-pro 是示例模型。實際可用模型請以 ApiFlux Models 頁面為準。

6. 選擇模型並測試

重新啟動 OpenCode：

opencode

進入後輸入：

/models

選擇剛剛設定的 ApiFlux 模型。

然後傳送測試請求：

用一句話介紹 ApiFlux 是什麼

如果 OpenCode 正常回覆，請回到 ApiFlux 控制台，開啟 Logs 檢視請求紀錄。

常見問題

OpenCode 找不到 ApiFlux Provider

請檢查：

opencode.json 是否放在目前專案資料夾
JSON 格式是否正確
是否在已有設定中正確合併了 provider
啟動 OpenCode 的目錄是否正確

API Key missing

Windows PowerShell 檢查：

echo $env:APIFLUX_API_KEY

macOS / Linux 檢查：

echo $APIFLUX_API_KEY

如果沒有輸出，請重新設定環境變數。

模型不存在

請確認設定中的模型 ID 來自 ApiFlux Models 頁面。

外掛導致 OpenCode 啟動失敗

如果 OpenCode 啟動時報類似錯誤：

fn3 is not a function

通常是本機 OpenCode 外掛異常，不是 ApiFlux 設定錯誤。

可以暫時開啟全域設定。

macOS / Linux / WSL：

~/.config/opencode/opencode.json

Windows 原生環境中，設定路徑可能位於：

C:\Users\你的使用者名稱\.config\opencode\opencode.json

將 plugin 暫時設定為空陣列後再測試：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": []
}

確認 OpenCode 能正常啟動後，再逐個恢復外掛。

function tools 或 reasoning_effort 不支援

如果某個模型不適合 OpenCode 的工具呼叫請求，可以換用更適合編碼場景的模型，例如：

deepseek-v4-pro
qwen3.7-plus
glm-5.2

使用 ApiFlux 設定 OpenCode

目錄