OpenCode 接入自定義 OpenAI 兼容 API：Provider 配置、模型限制與網關回退

OpenCode 同時出現在 “AI coding”“vibe coding”“open source AI” 與 “coding agent” 的上升查詢中。

最常見的接入錯誤不是 API key，而是協議、provider ID 和模型名沒有對齊。

先確認上游使用哪種協議

/v1/chat/completions 通常使用 @ai-sdk/openai-compatible。

/v1/responses 使用 @ai-sdk/openai。

“OpenAI 兼容”不代表兩個端點都實現。

先用上游文檔和最小 curl 請求確認。

1
2


curl -sS https://gateway.example.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

不要把 key 直接寫進 shell history。

憑據與配置分開

在 OpenCode 運行 /connect，選擇 Other。

輸入唯一 provider ID，例如 corp-gateway。

這個 ID 必須與 opencode.json 完全一致。

只執行 /connect 只會存憑據，不會自動生成完整 provider 配置。

一個最小配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "corp-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Corporate Gateway",
      "options": {
        "baseURL": "https://gateway.example.com/v1"
      },
      "models": {
        "coding-model": {
          "name": "Coding Model"
        }
      }
    }
  }
}

模型鍵必須是網關實際接受的 model ID。

顯示名稱可以自定義，但不能代替真實 ID。

給未知模型補上下文限制

1
2
3
4


"limit": {
  "context": 200000,
  "output": 32768
}

OpenCode 用這些值估算剩餘上下文。

不要把供應商宣傳的總 token 直接同時填到 input 和 output。

輸出上限過大可能導致請求被上游拒絕。

租戶或網關路由可能要求額外 Header。

靜態非敏感值可以放配置。

密鑰應引用環境變量。

不要把用戶身份 Header 交給 Agent 自由修改。

網關應從可信認證信息派生租戶，而不是相信客戶端自報。

Vercel AI Gateway 路由

官方示例支持 order、only 和 zeroDataRetention 等選項。

order 表示供應商嘗試順序。

only 限制可用供應商。

zeroDataRetention 用於篩選符合數據保留要求的路由。

回退不能只看 HTTP 狀態碼。

認證失敗、餘額不足和內容策略拒絕通常不應盲目換供應商重試。

用三個請求驗收

先發送純文本問答。

再發送需要工具調用的任務。

最後發送接近上下文上限的長輸入。

記錄模型名、請求 ID、首 token 延遲和總 token。

如果網關重寫模型名，日誌中要同時保留請求值與實際路由值。

常見錯誤

401：憑據未保存、環境變量沒進入當前進程或 Header 名不對。

404：baseURL 多寫或少寫 /v1，也可能選錯協議。

400 unknown model：配置鍵與上游 model ID 不一致。

工具不工作：上游只兼容文本格式，沒有完整實現 tool calls。

上下文提前溢出：limit.context 與真實模型不符。

排查命令

1

opencode auth list

確認憑據條目存在，但不要打印實際 key。

然後用 /models 檢查模型是否出現。

同一請求直接調用網關與通過 OpenCode 各執行一次。

直接請求成功、OpenCode 失敗，重點檢查配置與 SDK 協議。

兩邊都失敗，優先檢查網關和賬號。

多環境配置

開發、測試和生產網關使用不同 provider ID。

例如 corp-dev 與 corp-prod。

生產 ID 默認不出現在個人開發配置裏。

CI 使用短期憑據，不復用開發者本地 token。

切換環境後先運行只讀任務，確認沒有誤連生產。

安全與成本控制

在網關側設置每個 key 的預算和速率。

按 provider、模型、倉庫和用戶記錄費用。

日誌脫敏 Authorization 與提示中的憑據。

限制 Agent 能訪問的文件和命令。

API 路由成功不代表本地工具執行安全。

驗收清單

確認 Chat Completions 或 Responses 協議。
/connect ID 與配置完全一致。
baseURL 只包含一次 /v1。
模型 ID 與網關一致。
context/output 限制來自真實文檔。
回退策略區分可重試和不可重試錯誤。
憑據不在 JSON 與 Git 中。
三類請求均保存請求 ID 和真實路由。

Provider 配置文檔

先用獨立腳本驗證網關協議

在接入 OpenCode 前，用最小請求確認網關的認證、模型名和響應格式。下面是 Chat Completions 端點示意：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


$headers = @{
  Authorization = "Bearer $env:AI_GATEWAY_KEY"
  "Content-Type" = "application/json"
}
$body = @{
  model = "coding-model"
  messages = @(
    @{ role = "user"; content = "Reply with OK" }
  )
  max_tokens = 16
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
  -Uri "https://gateway.example.com/v1/chat/completions" `
  -Method Post `
  -Headers $headers `
  -Body $body

如果這個請求失敗，先解決網關問題。它成功而 OpenCode 失敗，才檢查 provider 配置和 AI SDK 包。

Responses API 不能只替換 URL

Responses API 的輸入、工具定義和流式事件與 Chat Completions 不完全相同。上游只提供 /v1/responses 時，把 provider 的 npm 包換成 @ai-sdk/openai，同時覈對網關是否透傳該協議。

不要在反向代理中把兩個請求體直接轉發到同一處理器。看似簡單的文本請求可能成功，工具調用和多模態請求卻會在運行中損壞。

用環境變量引用 API key

項目配置提交到 Git 前，搜索是否包含真實憑據：

1

git grep -n -E "sk-[A-Za-z0-9]|Bearer [A-Za-z0-9]"

本地環境變量名稱要體現用途，例如 CORP_GATEWAY_KEY，不要複用含義模糊的 API_KEY。CI、個人電腦和 VPS 分別使用不同 key。

校驗流式輸出

普通響應成功後，再測試較長回答和工具調用。檢查首個事件、增量文本、結束原因和最終 usage 是否齊全。

代理服務器需要關閉不必要的響應緩衝，並把讀取超時設置得比模型任務時限長。否則 OpenCode 會在模型仍運行時顯示連接中斷。

上下文上限寫錯會出現什麼

配置值高於真實上限時，OpenCode 以爲還有空間，上游卻返回上下文過長。配置值過低時，客戶端過早壓縮或丟棄有用內容。

用固定 token 樣本逐級增加輸入，記錄網關實際拒絕點。還要扣除系統提示、工具定義和預留輸出，而不是隻計算用戶文件。

模型別名需要版本治理

網關常把 coding-model 指向不斷更新的後端。這樣方便切換，卻會讓同一個配置產生不同結果。

生產工作流使用帶版本的別名，例如 coding-model-2026-07。升級時建立新別名，在測試倉庫跑完迴歸後再切默認路由。

回退時保持能力兼容

主模型支持工具調用和長上下文，回退模型也必須滿足任務最低能力。如果回退模型只支持文本，就應該明確失敗，不能把工具 JSON 當普通文字返回給 Agent。

爲每條路由記錄 supports_tools、supports_vision、context、output 和數據保留策略。選擇回退時按能力過濾，再按順序嘗試。

代理日誌的脫敏規則

保留請求 ID、租戶、模型、狀態碼、token 和耗時。刪除 Authorization，提示正文默認不入集中日誌。

調試時若必須採樣正文，使用專門測試賬號、短保留期和受限存儲。結束排錯後關閉採樣，並刪除臨時數據。

關閉連接與重試策略

連接超時可以有限重試；認證失敗、參數錯誤和內容策略拒絕不重試。429 根據 Retry-After 與預算決定是否等待。

寫工具已經執行而模型響應中斷時，不重新運行整個任務。先恢復 interaction 或檢查工作樹，避免重複修改。

配置變更後的五分鐘冒煙測試

依次運行 /models、短文本問答、只讀文件任務和一個需要工具調用的小任務。確認界面顯示的模型與網關日誌中的實際模型一致。

隨後故意輸入一個不存在的模型名。系統應返回明確的配置錯誤，而不是悄悄路由到昂貴的默認模型。

最後打開新的終端重新測試，排除當前會話臨時環境變量造成的假成功。測試結果與配置 diff 一起保存，便於回滾。

如果冒煙測試失敗，恢復上一份 opencode.json 和鎖定的模型別名，不在故障狀態下繼續疊加配置修改。

OpenCode 官方 Provider 文檔