OpenCode 搭配 OpenAI 相容 API：設定

開始前你需要準備的事項

OpenCode 是一個在您終端機中執行的開放原始碼程式碼代理程式。它可以與許多模型提供者通訊，並且如果端點遵循 OpenAI 聊天格式，它允許你新增自己的提供者。此端點符合該格式，因此設定只需填入幾個欄位。

首先收集這三個數值：

• Base URL： https://api.kimicode.top/v1
• 模型 ID： uncensored
• API 金鑰：在 API 金鑰頁面建立一個。新帳戶可以一鍵領取 $0.50 試用額度，這足以進行以下測試。試用金鑰允許 2 個並行請求和每分鐘 60 個請求。

將金鑰保留在環境變數中，而不是將其貼入您會提交的檔案：

Copyexport KIMICODE_API_KEY="your-key-here"

步驟 1：使用 curl 測試端點

在設定任何工具之前先執行此步驟。如果 curl 運作正常但 OpenCode 不行，你就知道問題出在設定。如果 curl 失敗，你只需修正一次金鑰或 URL，而不是在兩個地方都改。

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

你應該會收到一個包含 choices 陣列與 usage 區塊的 JSON 物件。401 代表金鑰錯誤或缺少 Bearer 前綴。404 通常代表 URL 輸入錯誤或已包含 /chat/completions。

程式碼代理程式會串流輸出答案並呼叫工具，因此也請檢查這兩項功能：

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

你應該會看到一系列 data: 行，每行都包含一個小型 JSON 資料片段，最後是用量數據和最終標記。-N 旗標會關閉 curl 的緩衝區，讓資料區塊在到達時顯示。

步驟 2：將自訂提供者新增至 OpenCode

OpenCode 會從專案資料夾或全域設定目錄讀取 JSON 設定檔 opencode.json。自訂 OpenAI 風格的提供者需使用 AI SDK 的 OpenAI 相容套件進行宣告，並設定 Base URL 與模型清單。以下結構參考撰寫時 OpenCode 的公開文件。欄位名稱可能會隨版本更動，若遇到拒絕，請對照當前 OpenCode 文件中提供者的章節。

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

models 下的金鑰是傳送至伺服器的確切模型 ID，因此必須讀取為 uncensored。最後一行選擇提供者與模型作為預設值，寫法為提供者名稱、斜線，然後是模型 ID。

{env:KIMICODE_API_KEY} 形式告訴 OpenCode 從你的 Shell 讀取變數。如果你的版本透過其自己的登入指令處理憑證，則使用該方式並將金鑰排除在檔案之外。無論哪種方式，都不要提交真實的金鑰。

專案設定或全域設定

你可以將提供者區塊保留在兩個位置。專案根目錄中的檔案僅適用於該儲存庫，適合共享一套設定的團隊。你使用者設定目錄中的檔案適用於所有地方，適合個人預設值。當兩者都存在時，專案檔案會新增或覆蓋全域檔案。

偏好使用全域檔案進行提供者定義，並使用環境變數作為金鑰。這樣每個儲存庫都可以使用端點，且沒有秘密資料與你的原始碼鄰近存放。如果多人在一個專案中工作，只提交不含金鑰的提供者區塊，並讓每個人設定自己的變數。這也使旋轉金鑰變得簡單：更改變數、重新啟動終端機，設定檔就會保持不變。

步驟 3：選擇模型並執行任務

在專案資料夾中啟動 OpenCode 並開啟其模型選擇器。你的自訂提供者應以你設定的顯示名稱出現在清單中。選取它，然後給代理程式一個小型、可檢查的工作，例如解釋函式或為短檔案撰寫單元測試。

從小處著手有兩個原因。首先，你可以看到工具呼叫是否運作：當 OpenCode 要求模型讀取或編輯檔案時，它是透過工具呼叫介面進行的。其次，程式碼代理程式每輪會發送大量文字，包括檔案內容和歷史記錄，因此長時間的會話會快速消耗 token。下一節將用數字來說明這一點。

如果模型沒有出現，請檢查檔案是否為有效的 JSON，它是否位於 OpenCode 尋找設定的位置，以及提供者名稱是否與你在 model 欄位中輸入的一致。

直接測試函式呼叫與 JSON 模式

OpenCode 依賴工具呼叫來讀取檔案、執行指令與編輯程式碼，因此在歸咎代理程式導致失敗之前，確認端點能處理工具定義是值得的。此請求提供一個工具，並提出需要該工具的問題。

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

良好的回應應包含一個 tool_calls 項目，命名為 read_file 並帶有 JSON 參數字串。代理程式執行工具，然後以 role 設為 tool 的訊息將結果傳回，模型接著繼續執行。如果您只看到純文字，請嘗試更直接的提示詞，因為模型是否決定呼叫工具是其行為的一部分。

JSON 模式是獨立的開關。加入 "response_format": {"type": "json_object"} 會要求輸出有效的 JSON，有助於其他腳本解析回傳內容。請在提示詞中也提及 JSON，讓模型知道預期的格式。

上下文視窗大小與工作階段成本

上下文視窗為 100,000 token，計算提示詞與補完的總和。將 limit.context 設定為 100000 可讓代理程式知道實際上限，以便在伺服器必須拒絕請求之前修剪或摘要歷史記錄。補完可以使用剩餘的任何空間，且 max_tokens 是選填的。

計費為每 1M 輸入 token $0.15，每 1M 輸出 token $0.50。代理程式是輸入密集的，因為每輪都會重新傳送對話。以下是中等工作階段的計算範例：

• 40 輪，每輪傳送約 30,000 輸入 token：1,200,000 輸入 token，即 1.2 x $0.15 = $0.18。
• 每輪回傳約 800 輸出 token：32,000 輸出 token，即 0.032 x $0.50 = $0.016。
• 總計：$0.196，因此整個工作階段約需二十美分。

你的數字會有所不同。請讀取回應中的 usage 值，或觀察 X-Balance-USD 標頭，它會在每個回應中顯示你的剩餘餘額。信用額度是預付的且永不過期，失敗或被拒絕的請求不會收費。詳細資訊請見 定價頁面。

對程式碼代理程式的誠實期望

這是一個針對合法成人用途調整的通用文字模型，能夠在不拒絕內容的情況下回答。它不是專門為程式碼構建的模型，本頁也不作基準測試聲明。它是否能可靠地編輯你的儲存庫，是你應該在開啟版本控制的情況下，在自己的任務上測試的，然後才將重要內容交給它。

它處理代理程式所需的底層機制：帶有串流 tool_calls 的工具呼叫、以 role: "tool" 訊息傳回的工具結果，以及透過 response_format 的 JSON 模式。它僅限文字，沒有影像，因此會附加螢幕截圖的功能將無法運作。

兩個限制對代理程式很重要。完整金鑰允許 8 個並行請求和每分鐘 300 個請求。同時觸發許多呼叫的子代理程式或並行工具執行可能會達到並行限制，且串流請求會保留其槽位直到串流結束。發生此情況時，您會收到 HTTP 429 錯誤，錯誤碼為 concurrency。錯誤碼 rate_limited 表示每分鐘請求過多。在暫時過載時，您也可能看到帶有 Retry-After: 5 的 429。請降低並行度或等待後重試。

故障排除

症狀	可能原因	修復方法
401 未授權	金鑰為空或錯誤；啟動 OpenCode 的殼層中未設定環境變數	在相同的終端機中執行 echo $KIMICODE_API_KEY，然後重新啟動 OpenCode
404 找不到	Base URL 包含 /chat/completions 或缺少 /v1	請使用確切的 https://api.kimicode.top/v1
找不到模型	模型金鑰與 uncensored 不同	將 models 中的金鑰與 GET /v1/models 返回的 ID 配對
429 錯誤與 concurrency 相關	同時請求過多	減少並行函式呼叫，或等待串流輸出完成
請求過大	內文超過 8 MB 或歷史記錄接近上下文視窗限制	開始新工作階段或摘要歷史記錄

對於此處未涵蓋的任何內容，文件頁面 有完整的請求參考，而 整合指南 則從其他 OpenAI 風格用戶端的角度涵蓋相同的端點。

更多指南

• 對 API 而言，OpenAI 相容意味著什麼？
• Kimicode 替代方案：無審查託管 LLM API
• 無審查 LLM API：OpenAI 相容整合與定價