如何在 OpenCode 中設定 CometAPI

TL;DR

在 OpenCode 中一次性配置 CometAPI，然後為你的程式任務選擇 Claude、GPT 或 DeepSeek。本指南在擴展 官方 CometAPI OpenCode 整合指南 的基礎上，提供完整的專案設定：一個 CometAPI API 金鑰、包含三個模型範例的設定檔、切換模型的指令，以及一個可重複檢查的小型 JavaScript 任務。

關鍵要點

• OpenCode 的 CometAPI 設定需要 provider ID、API base URL、憑證與 model ID。
• 使用 {env:COMETAPI_KEY} 將實際 API 金鑰排除在 opencode.json 之外。
• 在一個 opencode.json 中註冊 Claude、GPT 與 DeepSeek 範例；三者共用同一組 CometAPI 金鑰與閘道。
• 可在 OpenCode 中切換供應商／模型，而無需分別取得 Anthropic、OpenAI 與 DeepSeek 的金鑰。
• 注意缺失的環境變數、錯配的 API 路徑，以及看起來像卡住的核准提示。

什麼是 OpenCode，為何要搭配 CometAPI 使用？

OpenCode 是一個開源 AI 程式代理工具，提供終端機介面、桌面應用與 IDE 擴充。在專案中，它可解釋既有程式碼、規劃變更、編輯檔案，並在配置的權限下執行指令。本教學使用終端機流程：給代理一個小型程式任務，審閱其擬定的操作，並用本地測試驗證結果檔案。安裝與使用請參考 官方 OpenCode 文件。

CometAPI 提供模型存取層。多模型工作流程原本需要跨供應商管理憑證、計費與連線設定。透過一個 CometAPI 帳戶匯流支援的模型，讓本專案共用同一金鑰與 base URL，而 OpenCode 保留存放庫與任務說明。當你要在相同任務上比較模型或切換選定模型而不重整專案時，這很有用。聚合閘道為可選：直接連供應商可能更適合單一供應商流程或特定合約需求。此處的好處是簡化多供應商存取；但 API 介面、模型行為與工具相容性仍需各自驗證。

CometAPI 支援與 OpenAI 相容的 Chat Completions，也提供其他 API 形式。官方整合會為各種格式選擇對應的配接器。本範例中，Claude Sonnet 5 使用 Messages，GPT-6.1 Sol 使用 Responses，而 DeepSeek V4.1 Flash 使用 Chat Completions，對應下方範例。所有請求仍透過同一 CometAPI 金鑰送達 CometAPI。供應商名稱與 API 格式描述的是不同概念；不可假設單一模型接受所有格式。

配置 CometAPI 與 OpenCode 前需要什麼？

使用終端機、具 npm 的 Node.js、一個可用餘額且有 API 存取的 CometAPI 帳戶，以及一個可丟棄的專案目錄。Bash 範例適用於 macOS、Linux 或 WSL；標註的 PowerShell 範例使用 Windows 語法。稍後的 JavaScript 檢查亦需在同一工作階段中可用的 Node.js。

本教學使用 OpenCode 1 的配置風格。官方文件 區分 OpenCode 1 與 OpenCode 2；兩者皆使用 opencode 指令。開始前先記錄 opencode --version，並參照該主要版本的配置文件。以下的三模型工作流程是整合教學與預期結果，並不聲稱完成端到端測試。

在執行範例時，記錄你的 CLI、Node.js、npm、作業系統與測試日期。API 使用會計入你的 CometAPI 帳戶。下列指令是動手示範與預期結果；不包含模型生成輸出或成功的三模型整合跑通聲明。

node --version
npm --version
opencode --version

如何一步步在 OpenCode 中配置 CometAPI？

第 1 步：安裝 OpenCode

若尚未安裝 OpenCode，請安裝官方 npm 套件。未鎖版的安裝會跟隨當前版本；使用配置前請記錄安裝的版本。若需重現來源指南的環境，其標註的 CLI 版本為 1.18.16。

安裝 OpenCode CLI 並顯示其版本。

npm install -g opencode-ai
opencode --version

若安裝後找不到可執行檔，請開新終端機。接著在可丟棄的專案目錄中作業，以便第一個代理任務有清晰界線。

建立並進入專案目錄。

mkdir cometapi-opencode-demo
cd cometapi-opencode-demo

第 2 步：建立 CometAPI API 金鑰

從你的 CometAPI 帳戶 產生 API 金鑰，並在用來啟動 OpenCode 的同一終端機中設定。請在本機替換占位值。不要提交金鑰、貼入提示或包含在共用日誌中。

該變數作用於目前的 shell 與其啟動的程序。不要截圖真實權杖。以下檢查會回報變數是否存在，但不會輸出其值。

在目前的 Bash 工作階段中設定 CometAPI 金鑰。

export COMETAPI_KEY="YOUR_COMETAPI_KEY"

在目前的 PowerShell 工作階段中設定 CometAPI 金鑰。

$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
test -n "$COMETAPI_KEY" && printf "COMETAPI_KEY is set\n" || printf "COMETAPI_KEY is missing\n"
if ([string]::IsNullOrWhiteSpace($env:COMETAPI_KEY)) {  "COMETAPI_KEY is missing"} else {  "COMETAPI_KEY is set"}

第 3 步：建立 opencode.json

在專案根目錄建立 opencode.json，或使用 ~/.config/opencode/opencode.json 讓設定對所有專案可用。為了讓本教學自成一體，建議使用專案檔。使用單一 provider 物件，包含下列三個條目；若已存在 provider 物件，請合併其條目，而非建立重複的 JSON 鍵。

若欄位衝突，專案配置會覆蓋全域配置；無衝突的欄位將保留。自訂的 OPENCODE_CONFIG 檔在全域與專案之間載入。若還有受管或內嵌設定，請檢查文件化的優先序。

以下完整設定請另存為 opencode.json。每個 provider 皆從環境讀取 COMETAPI_KEY。刻意省略預設模型，以便你明確選擇三個範例之一。

Flash 變體明確指定所需的 DeepSeek V4.1 範例。保持 GPT 使用 Responses 配接器以支援工具；CometAPI DeepSeek 指南 記載了此處使用的 Chat Completions 路由。執行前請重新檢查帳戶中的模型可用性與權限。

{  "$schema": "https://opencode.ai/config.json",  "provider": {    "cometapi-messages": {      "npm": "@ai-sdk/anthropic",      "name": "CometAPI Claude",      "options": {        "baseURL": "https://api.cometapi.com/v1",        "apiKey": "{env:COMETAPI_KEY}"      },      "models": {        "claude-sonnet-5": {          "name": "Claude Sonnet 5"        }      }    },    "cometapi-responses": {      "npm": "@ai-sdk/openai",      "name": "CometAPI GPT",      "options": {        "baseURL": "https://api.cometapi.com/v1",        "apiKey": "{env:COMETAPI_KEY}"      },      "models": {        "gpt-6.1-sol": {          "name": "GPT-6.1 Sol"        }      }    },    "cometapi-chat": {      "npm": "@ai-sdk/openai-compatible",      "name": "CometAPI DeepSeek",      "options": {        "baseURL": "https://api.cometapi.com/v1",        "apiKey": "{env:COMETAPI_KEY}"      },      "models": {        "deepseek-v4.1-flash": {          "name": "DeepSeek V4.1 Flash"        }      }    }  },  "permission": {    "edit": "ask",    "shell": "ask"  }}

正確的 baseURL： https://api.cometapi.com/v1。錯誤的 baseURL： https://api.cometapi.com/v1/chat/completions。配接器會自行加入端點路徑。將範例合併到現有 opencode.json 中，不要移除無關設定。

edit 與 shell 設定會在 目前的 OpenCode 權限規則 下請求對檔案變更與命令的核准。以互動方式運行程式範例並檢視這些請求。OpenCode 也會繼承啟動程序的作業系統權限；請為此練習使用可丟棄目錄。

第 4 步：檢查閘道連線

可選的 Gemini 設定與驗證位於下方三模型連線檢查之後。

下列 HTTP 範例直接檢查 DeepSeek 的 Chat Completions 條目。這有助於將 OpenCode 以外的閘道連線問題獨立出來。Claude 與 GPT 會在下一步使用其配接器選定的路由；僅更改此 HTTP 請求中的 model ID 不會自動變更其協定。

從 Bash 發送最小 Chat Completions 請求。

curl --silent --show-error \  --output response.json \  --write-out "HTTP %{http_code}\n" \  https://api.cometapi.com/v1/chat/completions \  -H "Authorization: Bearer $COMETAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"Reply with a short greeting."}]}'

此指令使用 curl write-out 與 output 選項 分離 HTTP 狀態與 response.json。成功的傳輸仍可能包含 HTTP 錯誤，請同時檢視印出的狀態與 JSON 內文。這可避免依賴 --fail-with-body，該選項需 curl 7.76.0 以上版本。

在 PowerShell 中以非 shell 特定 JSON 引號，發送相同請求。

$body = @{  model = "deepseek-v4.1-flash"  messages = @(@{ role = "user"; content = "Reply with a short greeting." })} | ConvertTo-Json -Depth 4
$response = Invoke-WebRequest -UseBasicParsing -Method Post `  -Uri "https://api.cometapi.com/v1/chat/completions" `  -Headers @{ Authorization = "Bearer $env:COMETAPI_KEY" } `  -ContentType "application/json" `  -Body $body
$response.Content | Set-Content -Encoding UTF8 response.json
"HTTP $($response.StatusCode)"

遇到 HTTP 錯誤時，PowerShell 可能在最後兩行執行前就擲出例外。請擷取該失敗的狀態與已打碼的錯誤細節；不要將其記錄為成功回應。

DeepSeek 請求的預期結果：HTTP 200，且 choices[0].message.content 中有非空文字。請檢視已儲存的 response.json，而非僅接受 HTTP 200。以下補充顯示回應結構，以及如何檢查三個已配置路由。範例僅供說明；本修訂不聲稱有即時 CometAPI 測試結果。純文字請求不驗證串流或工具呼叫。

示意的 DeepSeek 回應結構：問候語、使用量等欄位取決於實際請求。以下 JSON 為刻意縮短的例子，非擷取自 API 的回應。

{"choices":[{"message":{"role":"assistant","content":"Hello!"}}]}

在實際成功的 HTTP 請求後，狀態列應為 HTTP 200，且 response.json 應包含非空的助理文字。請保留你自己的實際狀態與本體；不要複製範例作為測試證據。

第 5 步：在 Claude、GPT 與 DeepSeek 間切換

此步驟的指令應回傳所要求的助理標記。示意助理文字（省略終端橫幅、計時與中繼資料）：

Claude:   CLAUDE_READY
GPT:      GPT_READY
DeepSeek: DEEPSEEK_READY

以上僅顯示預期內容，非終端紀錄。請記錄各 provider 的實際輸出與程序退出狀態；缺少標記或請求失敗需另行調查。

於包含 opencode.json 的目錄開始。列出各 provider 的模型，然後對每個條目發送簡短文字請求。這些指令會切換所選模型與配接器；CometAPI 金鑰與 base URL 保持不變。

使用以下指令確認三個條目皆可見且可回傳文字。

opencode models cometapi-messages
opencode models cometapi-responses
opencode models cometapi-chat
opencode run --model cometapi-messages/claude-sonnet-5 "Reply exactly with: CLAUDE_READY"
opencode run --model cometapi-responses/gpt-6.1-sol "Reply exactly with: GPT_READY"
opencode run --model cometapi-chat/deepseek-v4.1-flash "Reply exactly with: DEEPSEEK_READY"

若要互動式切換，啟動 opencode，輸入 /models，並選擇 CometAPI Claude、CometAPI GPT 或 CometAPI DeepSeek。OpenCode 會使用該條目的 provider/model 組合。你無需三個供應商帳戶或三組 API 金鑰。在此以環境變數支援的配置下，請勿使用 /connect 提供第二組憑證；缺失的 COMETAPI_KEY 應在啟動用的 shell 修正。

預期結果：每個短請求皆回傳其要求的標記。請記錄每個模型的實際結果。可見的模型條目僅確認註冊；成功的文字回應則確認請求路徑。任一者皆不足以證明檔案工具可用。

Gemini 使用獨立的 provider 與協定。保留上述 Claude、GPT 與 DeepSeek 條目；將以下條目合併到現有的 provider 物件中。下方 base URL 依審閱者提供的 CometAPI 設定。使用前請在你的 CometAPI 帳戶確認當前路由與模型存取。

Google 配接器支援自訂 baseURL，並以 x-goog-api-key 傳送 apiKey。參見 官方 AI SDK Google provider 參考。這僅確認配接器設定；不代表特定 Gemini 模型已在 CometAPI 閘道啟用。

{  "provider": {    "cometapi-gemini": {      "npm": "@ai-sdk/google",      "name": "CometAPI Gemini",      "options": {        "baseURL": "https://api.cometapi.com/v1beta",        "apiKey": "{env:COMETAPI_KEY}"      },      "models": {        "YOUR_GEMINI_MODEL_ID": {          "name": "CometAPI Gemini (account-selected model)"        }      }    }  }}

請在 JSON 鍵與下方指令中以你的 CometAPI 帳戶啟用的精確 Gemini 模型 ID 替換 YOUR_GEMINI_MODEL_ID。這是占位符，非真實模型 ID。合併此 provider 條目時不要重複頂層 provider 鍵，並從同一個已設定 COMETAPI_KEY 的 shell 啟動 OpenCode。

opencode models cometapi-gemini
opencode run --model cometapi-gemini/YOUR_GEMINI_MODEL_ID "Reply exactly with: GEMINI_READY"

預期助理文字：GEMINI_READY。列出的模型確認本地註冊；收到標記確認文字請求。若要驗證程式工具，於新可丟棄目錄中啟動 opencode --model cometapi-gemini/YOUR_GEMINI_MODEL_ID，並重複下方的 greet.cjs/check.cjs 任務。僅有文字成功不代表串流、編輯或工具呼叫可用。

如何使用 Claude、GPT 與 DeepSeek 執行程式任務？

對每個模型使用相同的小任務：建立問候函式、加入斷言，並執行。為避免後續模型重用前一模型所建立的檔案，請保留三個全新目錄。這能檢查整合流程，而不將文章變成效能評比。

將 prepare-runs.cjs 與 opencode.json 放在一起，並執行一次。它會建立三個新目錄，且只複製共用設定。若任一目錄已存在，則會停止，以免覆寫先前工作。

const fs = require("node:fs");
const path = require("node:path");
const root = __dirname;
const names = ["claude-demo", "gpt-demo", "deepseek-demo"];
const config = path.join(root, "opencode.json");

if (!fs.existsSync(config)) throw new Error("Missing opencode.json");

for (const name of names) {
  if (fs.existsSync(path.join(root, name))) {
    throw new Error(`Directory already exists: ${name}`);
  }
}

for (const name of names) {
  const dir = path.join(root, name);
  fs.mkdirSync(dir);
  fs.copyFileSync(config, path.join(dir, "opencode.json"));
}

node prepare-runs.cjs
cd claude-demo
opencode --model cometapi-messages/claude-sonnet-5
# After exiting OpenCode:
cd ..
cd gpt-demo
opencode --model cometapi-responses/gpt-6.1-sol
# After exiting OpenCode:
cd ..
cd deepseek-demo
opencode --model cometapi-chat/deepseek-v4.1-flash
# After exiting OpenCode:
cd ..

一次執行以下任一場次，並從父專案目錄開始。每次在進入下一個範例前先退出該場次。於每一場次中提交相同任務並審閱擬議的檔案變更與命令。啟動 OpenCode 的程序需可使用 Node.js。

要求代理建立並驗證一個小型 JavaScript 函式。

Create greet.cjs in this directory.
Export a function named greet(name) that returns "Hello, " + name + "!".
Create check.cjs using node:assert/strict.
Assert that greet("Ada") equals "Hello, Ada!".
Run node check.cjs and report its actual exit status.
Do not modify opencode.json or unrelated files.

預期結果：代理會請求已配置的核准，建立兩個檔案，並以退出狀態 0 完成 node check.cjs。請記錄實際發生情況。檢視檔案並自行重跑檢查；口頭「成功」宣稱不足為憑。若工具呼叫被拒或格式錯誤，請將路由相容性與待核准請求區分開來調查。

參考檔案與本地驗證

以下檔案是所要求任務的參考實作。它們由本指南直接撰寫，並非模型生成產物。其可觀察行為相符即視為代理運行的驗收條件。

function greet(name) {  return "Hello, " + name + "!";}

module.exports = { greet };

const assert = require("node:assert/strict");
const { greet } = require("./greet.cjs");

assert.equal(greet("Ada"), "Hello, Ada!");

node check.cjs
printf "exit=%s\n" "$?"
node check.cjs
"exit=$LASTEXITCODE"

本地參考檢查：Windows、Node.js v24.19.0、2026 年 10 月 22 日；node check.cjs 返回退出狀態 0，標準輸出為空。此檢查僅涵蓋兩個參考檔案；不驗證 OpenCode 安裝、CometAPI 存取、核准提示或模型工具呼叫。

每個模型保留一份結果記錄：選定 provider/model、是否收到回應、是否建立 greet.cjs 與 check.cjs、是否出現核准提示，以及 node check.cjs 的退出碼。失敗即記錄為失敗；不要從參考實作推斷通過。

保護憑證並驗證可靠性

將 COMETAPI_KEY 存於環境變數，而非設定檔或共用日誌。保留檔案編輯與 shell 指令核准啟用，並在可丟棄專案中測試新配置。

分別驗證直接 API 請求、OpenCode 回應與檔案編輯流程。記錄錯誤與測試結果，只重試暫時性失敗，並在重跑中斷任務前檢查工作區。

CometAPI 簡化了模型切換，但 OpenCode 不會透過此配置自動提供跨模型故障移轉。若模型不可用，請手動選擇另一個已驗證的模型並重複驗收檢查。

使用 Opencode 與 CometAPI 的成本是多少？

CometAPI 價格與計費架構

CometAPI 採用即用即付的計費方式，無月費，只針對實際 API 使用量收費。其官方模型費率通常較供應商標準價格低 20%，另有額外的量大折扣。開發者可透過單一帳戶存取 Claude、GPT、DeepSeek 與其他模型，按所選模型的權杖消耗計費。請參考 CometAPI 價格頁 以取得最新費率。

在無快取與額外費用的情況下：

Cost = (Input tokens × Input rate + Output tokens × Output rate) / 1,000,000

例如，在假設的 $1/M 輸入權杖與 $4/M 輸出權杖費率下，使用 20,000 輸入與 2,000 輸出權杖，成本為 $0.028。以上為示意費率，非實際模型價格。

請記錄權杖用量、總 API 費用、執行時間與各任務的測試結果。為降低成本，請限制不必要的上下文、保持精簡提示、避免重複失敗請求，並在能滿足同等品質需求時選擇較低成本的模型。

OpenCode API 成本優化策略

為在不降低程式品質的前提下降低 OpenCode 成本，重點在模型選擇、權杖效率與避免不必要的 API 請求。

• 選對模型：將例行程式任務交給成本較低的模型（如 DeepSeek），而將複雜除錯、重構與推理保留給 Claude 或 GPT。
• 降低權杖消耗：提示保持精簡，只提供相關專案檔案，避免重複傳送大量存放庫上下文。
• 使用提示快取：對重複的上下文（如專案指示與程式碼參考）使用支援的快取功能，以降低輸入成本。
• 避免不必要的重試：先修正配置與驗證錯誤再重試，審閱先前輸出以避免重工。
• 監控實際支出：透過 CometAPI 追蹤權杖用量、API 費用與任務完成情況。比較每個成功任務的成本，而非僅比較權杖單價。

結合 CometAPI 的折扣即用即付定價，以上做法可幫助開發者在維持可靠表現的同時控制支出。

如何擴充 CometAPI 設定？

若要新增另一個模型，將其模型 ID 放在符合其 API 格式的 provider 之下，或新增一個具所需配接器的 provider 條目。然後透過 /models 選擇該 provider/model。憑證仍存於 COMETAPI_KEY，保留既有條目以便切換僅是選擇操作。

官方指南涵蓋四種 API 格式，包含 Gemini。本文使用 Claude、GPT 與 DeepSeek 所需的三個條目。若多個選定模型支援 Chat Completions，它們可共享一個 cometapi-chat 模型映射。不要把僅支援 Responses 或 Messages 的路由移入該映射，只為了減少條目數。

請根據你要呼叫的路由選擇配接器，並根據程式任務選擇模型。更換供應商不需要新的 CometAPI 金鑰；更換 API 格式則需匹配的配接器。

如何在 OpenCode 中疑難排解 CometAPI？

遵循首個失敗的階段：HTTP 請求 → OpenCode provider → 檔案工具。若 HTTP 失敗，檢查憑證、模型存取與端點細節。若 HTTP 成功但 OpenCode 失敗，檢查配置與啟動環境。若兩個文字檢查皆通過但檔案操作失敗，檢查權限與工具呼叫相容性。

分享問題時，請包含 OpenCode 版本、作業系統、模型 ID、端點路徑與打碼的錯誤文字。排除 API 金鑰與私有存放庫內容。保留可重現失敗的最小請求，以便分別調查配置與工具失敗。

常見問題

為什麼在新終端機中 OpenCode 會找不到我的 CometAPI 金鑰？

上述 export 與 PowerShell 指令會在當前工作階段與其子程序中設定環境變數。另開的終端機或已在執行的編輯器可能不會繼承它。請在啟動 OpenCode 的環境中設定金鑰，並重啟該程序。若需長期設定，請使用作業系統的憑證管理，而非將祕密寫入存放庫檔案。

OpenCode 會自動從 .env 載入 COMETAPI_KEY 嗎？

{env:COMETAPI_KEY} 讀取的是程序環境。僅建立 .env 並不代表變數已載入。請在啟動 OpenCode 前，使用你的 shell 或顯式設定的環境載入器。請在啟動程序檢查變數是否為空，而非假定 provider 不可用。

全域 OpenCode 配置會改變本專案設定嗎？

OpenCode 以合併方式處理配置，而非完全替換較早的檔案。專案檔會覆蓋全域檔案中重疊欄位，無關的全域設定會保留。自訂 OPENCODE_CONFIG 在兩者之間載入。若不同存放庫行為不同，請比較這些來源以及任何受管或內嵌設定，而非假定本地檔案是唯一輸入。

刷新 OpenCode 模型清單會啟用 CometAPI 存取嗎？

不會。模型刷新選項會更新 models.dev 快取；它不會授予帳戶存取或證明某端點接受某模型 ID。手動配置的條目在任何成功請求之前即可見。請使用實際請求檢查路由，並在 CometAPI 帳戶查閱存取限制。

為什麼 curl 可行但 OpenCode 無法呼叫 CometAPI？

兩個程序可能載入了不同的憑證、使用不同的模型 ID，或發送了不同的請求形狀。首先在與成功 HTTP 請求相同的終端機中重跑短文字提示。然後比較 provider base URL、配接器與選定模型。若簡單文字可行但代理任務失敗，請分別保留與工具相關的錯誤；HTTP 連通性本身不足以證明工具相容。

結論

你現在擁有一份包含 Claude、GPT 與 DeepSeek 範例的 opencode.json、共用的 CometAPI 憑證，以及切換活躍模型的指令。先用短文字請求檢查存取，再於獨立目錄運行相同的檔案建立任務以驗證程式工作流程。保留觀察到的結果與你的環境細節，然後再將此設定應用到更大的儲存庫。