OpenCode 串接 AIXHUB

安裝 OpenCode、加入 AIXHUB 供應端、驗證所選模型，並安全復原原本設定。

本指南會透過 OpenAI 相容供應端，將 OpenCode 連到 AIXHUB 模型。API 金鑰只留在環境變數，opencode.json 則存放供應端與模型路由。

OpenCode 平台支援狀態
平台	狀態
Windows	支援
macOS	支援
Linux	支援

完成目標

完成本指南後，你會得到以下結果：

透過 npm 安裝 OpenCode，並確認目前執行的版本。
以不回顯方式提供 OpenCode 專用 AIXHUB API 金鑰，且不把真實值寫入 opencode.json。
加入完整 aixhub 供應端，並選用 aixhub/panel-model-id。
完成一筆唯讀請求，並與 AIXHUB 用量記錄核對。
保留備份，能明確復原原本設定。

系統需求

Windows、macOS 或 Linux，並具備受支援的 Node.js 版本，且 npm 可從 PATH 執行。
能以目前使用者或目前 Node.js 環境安裝全域 npm 套件。
AIXHUB 帳號、一組專用 AIXHUB API 金鑰，以及從模型路由複製的 OpenAI 相容模型 ID。本指南所有模型欄位都使用 panel-model-id。
能維持有效 JSON 語法的文字編輯器。

OpenCode 會從下列位置讀取使用者設定：

Windows：%USERPROFILE%\.config\opencode\opencode.json
macOS 與 Linux：~/.config/opencode/opencode.json

編輯前先備份既有使用者檔案，也要檢查專案根目錄是否有 opencode.json。專案設定可以覆寫使用者設定，包括供應端與所選模型。

安裝

安裝 OpenCode npm 套件：

npm install -g opencode-ai

開啟新的終端機，確認可執行檔與版本：

opencode --version

若遇到 npm 權限或 PATH 錯誤，請先排除安裝問題，再加入 AIXHUB 設定，避免把用戶端安裝與供應端連線混在一起判斷。

AIXHUB 設定

為目前終端機設定金鑰

請使用實際用來啟動 OpenCode 的 Shell 區塊。每種方式都不會回顯金鑰，也不會把真實值寫入 Shell 歷程。

Bash

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

Windows PowerShell

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_API_KEY = $plainKey
Remove-Variable plainKey, secureKey

此變數只存在於目前終端機工作階段及其啟動的程式。測試完成後關閉終端機，即可從目前終端機環境清除金鑰。

儲存供應端設定

將以下完整 JSON 儲存為使用者層級 opencode.json。若檔案已有其他供應端、外掛或選項，請合併 provider.aixhub 物件與最上層 model 屬性，不要取代不相關設定。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aixhub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIXHUB",
      "options": {
        "baseURL": "https://api.aixhub.org/v1",
        "apiKey": "{env:AIXHUB_API_KEY}"
      },
      "models": {
        "panel-model-id": {
          "name": "AIXHUB model"
        }
      }
    }
  },
  "model": "aixhub/panel-model-id"
}

屬性名稱有大小寫之分，必須使用大寫 URL 的 baseURL，並且只包含一個 /v1。apiKey 的值是 OpenCode 環境變數參照，不是真實金鑰。models 下的模型鍵值與最上層 model 路由後半段必須一致。

若專案已有自己的 opencode.json，請先移除本次測試會衝突的供應端與模型值，或讓它們與使用者設定一致。修改任一設定檔後都要重新啟動 OpenCode。

首次使用

在小型測試專案中，使用已設定 AIXHUB_API_KEY 的同一個終端機啟動 OpenCode：

opencode

送出請求前，先開啟 OpenCode 模型選擇器，確認所選項目是 aixhub/panel-model-id。若畫面顯示其他模型，請明確選擇 AIXHUB 模型，並檢查專案層級 opencode.json 是否覆寫使用者設定。

送出以下範圍明確的唯讀工作：

請以唯讀方式檢查目前目錄，不要變更任何檔案，也不要執行會改變狀態的命令。只回覆 OK。

核准任何工具權限前，先檢視要求內容。第一次連線測試不需要寫入檔案，也不需要存取測試專案以外的位置。

驗證

成功時應看到以下輸出：

OK

接著開啟 AIXHUB 用量，尋找使用 panel-model-id 的新 OpenAI 相容請求。核對時間是否與測試一致，並確認所選路由是 aixhub/panel-model-id，而非官方帳號或其他供應端。

OpenCode 對唯讀工作回傳 OK，且 AIXHUB 留下相符的請求與模型記錄。

疑難排解

找不到 AIXHUB 或模型

確認 JSON 位於正確使用者路徑、語法有效，且包含 provider.aixhub。儲存後重新啟動 OpenCode。若離開專案就能看到供應端，進入專案卻看不到，通常是專案 opencode.json 覆寫了使用者檔案。

401 或驗證失敗

請從輸入 AIXHUB_API_KEY 的同一個終端機啟動 OpenCode。JSON 必須完整保留 {env:AIXHUB_API_KEY}，不要改用官方 OpenAI 登入資料或 AIXHUB 控制台密碼。以不回顯方式重新輸入有效的專用金鑰，再啟動新的 OpenCode 工作階段。

404 或端點錯誤

baseURL 必須剛好是 https://api.aixhub.org/v1。缺少 /v1、重複成 /v1/v1，或屬性拼字錯誤，都可能讓請求送到錯誤端點。也要檢查專案設定是否取代 provider.aixhub.options。

model not found

從模型路由重新複製完整模型 ID，同時替換 models.panel-model-id 與 model: "aixhub/panel-model-id" 的後半段。不要只改其中一處，也不要重複加入兩次供應端前綴。

回應成功但用量沒有相符記錄

檢查 OpenCode 實際啟用的供應端與模型。其他使用者設定、專案 opencode.json 或官方帳號路由可能取得較高優先順序。完整關閉 OpenCode，讓兩個設定範圍一致後，再重做小型請求。

若要復原，先關閉 OpenCode，再還原使用者 opencode.json 備份。若沒有備份，請只刪除本指南加入的 provider.aixhub 與最上層 model 屬性，同時保留不相關設定及有效 JSON 語法。專案 opencode.json 若曾配合修改，也要還原或移除衝突內容。關閉暫時終端機即可清除 AIXHUB_API_KEY；再次啟動 OpenCode 後，先確認供應端，再授予工具權限。

安全注意事項

真實 API 金鑰不可出現在使用者或專案 JSON 中；{env:AIXHUB_API_KEY} 只是參照，可以保留在設定裡。
為 OpenCode 建立專用 AIXHUB 金鑰，才能獨立輪替或撤銷，不影響其他用戶端。
不要顯示環境變數、把金鑰貼進提示內容、提交到版本控制，或放進螢幕擷取畫面與支援記錄。
信任專案前先檢視其中的 opencode.json，因為它可以覆寫供應端、模型與其他 OpenCode 行為。
第一次請求保持唯讀；確認網路路由後，仍要逐次檢視工具權限。
若金鑰出現在終端機歷程、儲存庫、修補內容或共用記錄，請立即輪替。

官方資料

最後核對：2026-07-14