Theia IDE

在 ai-features.openAiCustom.customOpenAiModels 中新增一個項目 — model、url 與 apiKey — 即可讓 Theia Coder、Architect 與行內完成使用 Kunavo。

{
  "ai-features.openAiCustom.customOpenAiModels": [
    {
      "model": "claude-sonnet-5",
      "url": "https://api.kunavo.com/v1",
      "id": "kunavo-sonnet-5",
      "apiKey": "sk-kn-...",
      "developerMessageSettings": "system"
    },
    {
      "model": "claude-haiku-4-5",
      "url": "https://api.kunavo.com/v1",
      "id": "kunavo-haiku-4-5",
      "apiKey": "sk-kn-...",
      "developerMessageSettings": "system"
    }
  ]
}

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 啟用此功能：Theia 文件指示前往 Preferences，並啟用「AI-features => AI Enable」設定。完成此操作後，下方內容才會顯示。
3. 開啟 AI Configuration 檢視畫面——Alt+A，或在左下角的 Manage（齒輪）選單中，於 Settings 正下方選擇 AI Configuration。其分類包括 General、Providers & Models、Model Aliases、Agents、Prompts & Skills、Variables、Tools、Token Usage 和 MCP Servers。
4. 新增上方的項目。文件說明，這項操作是按一下設定區段中 OpenAI Compatible Models 的連結——此偏好設定是結構化清單，而 Theia 指出，沒有專用編輯器的結構化設定「會交由 settings.json 處理」，也就是你會進入的檔案。每個模型 ID 對應一個物件；url 和 apiKey 都要重複設定。
5. 將某個項目指向它。在 Agents 底下，每個代理程式都有一個 Language Model 選擇器；許多代理程式實際上會解析模型別名，因此只要在 Model Aliases 底下設定 default/code、default/universal、default/code-completion、default/summarize 和 default/fast，就能一次移動多個代理程式。
6. 傳送一則聊天訊息給 Theia Coder，接著提出一個會操作檔案的需求。這個 IDE 中的代理程式會大量使用工具呼叫和工作區內容，因此第一次執行時讀取或編輯某些內容，比打招呼更能讓你了解實際情況；同一個檢視畫面中的 Token Usage 也會顯示這一輪消耗了多少 Token。

已於 2026年9月21日 根據 Theia IDE 的 AI 功能頁面，「OpenAI Compatible Models」區段 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

一個請求就能判斷失敗原因是端點、金鑰還是設定檔。如果這裡回傳 JSON，則相同的基礎 URL 與金鑰在 Theia IDE 中也能運作。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

欄位中應填入哪個模型 ID

每個文字模型都能以模型 ID 存取——即時清單位於 GET /v1/models，帶有價格的目錄位於模型頁面。費率是每 1M 權杖的美元價格，輸入／輸出。

Theia 對此供應商的說明

Theia 自家頁面上的 LLM Providers Overview 表格會從三個面向評估各提供者。這是 Theia 對自家產品的說法，依上述日期從該表格轉錄而來——不是 Kunavo 的測試結果；此處唯一撰寫的表格欄位是標題為「模型 ID 需要符合什麼」的那一欄。

Theia 還在該表格上方兩段加入一項提醒。值得重述，因為這是整頁內容誠實的前提：「有些模型可能無法直接使用，因為它們可能需要特定的自訂或最佳化。」

實際的費用來源

Theia IDE 是開放原始碼軟體，可免費下載，其 AI 功能本身不收費；產生費用的是模型呼叫，帳單由 apiKey 中金鑰的持有人收取。文件中有兩項設定對帳單的影響比模型選擇更大，而且兩者都在文件中：

1. 自動程式碼補全預設為開啟，文件將它描述為「編寫程式碼時持續向底層 LLM 發出請求」。它是一天會執行數千次的代理。請將 default/code-completion 固定為低成本 ID，或在 'AIFeatures'=>'CodeCompletion' 將代理切換為手動模式，並使用 Ctrl+Alt+Space 觸發。
2. 同一組設定中的 Max Context Lines 會限制每次補全請求所包含的周邊檔案內容。每次由按鍵觸發呼叫時，其中每一行都會以輸入內容計費。

聊天代理程式的情況正好相反：呼叫次數較少、上下文大得多，而且每一輪都會重新傳送相同的工作區檔案。提示詞快取正是為這種情況而設 — 請參閱 /docs/caching — 這也就是為什麼上方模型表格的兩部分是依代理程式觸發頻率區分，而非依其聰明程度區分。

無法連線時

1. 404 — url。Kunavo 提供 /v1/chat/completions，因此欄位需要填入 /v1 根路徑；只填來源站台或填入完整的 .../chat/completions 都會無法連線。
2. 401——金鑰問題。Theia 的 Readme 指出，apiKey「會在授權請求中以 Bearer Token 傳送」，這正是 sk-kn- 金鑰預期的方式。請留意文件記載的預設行為：完全沒有 apiKey 時，Theia 會傳送 no-key，因此缺少欄位會看起來像金鑰遭拒，而非欄位缺失。（true 的意思是「使用全域 OpenAI API 金鑰」——此處不適用。）
3. 模型 ID 沒有出現在選擇器中 — 清單來自你自己的 customOpenAiModels 項目，而非端點，因此找不到 ID 表示缺少對應物件。id 欄位是 UI 顯示的名稱；若省略，則會改用模型名稱。
4. 第一則系統訊息遭到拒絕或忽略 — 這是 developerMessageSettings 設定所致。它預設為 developer，這是 OpenAI 格式的角色；Theia 為非 OpenAI 供應商提供的範例會設定 system，因此上方區塊也這樣設定。user、mergeWithFollowingUserMessage 和 skip 是文件記載的其他選項。
5. 任何地方都完全沒有回應 — 請檢查 Workspace Trust。Theia 的所有 AI 功能都受此設定限制；未受信任的工作區會停用聊天輸入和行內補全，並顯示 AI 功能受到限制 訊息。