# CodeBuddy

來源: https://docs.aicentos.com/zh-TW/clients/codebuddy

Language: zh-TW

> 在 CodeBuddy（IDE / CLI）中透過 models.json 接入 aicentos 的 OpenAI 相容端點

CodeBuddy 支援自訂模型，透過使用者層級或專案層級的 `models.json` 就能把請求指向 aicentos 的 OpenAI 相容端點，IDE 和 CodeBuddy Code CLI 共用同一份設定。

## 準備工作

先在控制台「API Key」頁面為 CodeBuddy 建立一個專用 Key（建議命名 `codebuddy`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 建立 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 錢包儲值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填寫的設定

| 欄位                                   | 值                                          |
| ------------------------------------ | ------------------------------------------ |
| Base URL                             | `https://aicentos.com/v1`                  |
| 端點 URL（`url` 欄位）                     | `https://aicentos.com/v1/chat/completions` |
| API Key（`apiKey`）                    | 控制台建立的 Key                                 |
| 模型 ID（`id`）                          | 控制台「模型廣場」中的模型名稱                            |
| `supportsToolCall`                   | `true`                                     |
| `maxInputTokens` / `maxOutputTokens` | 依所選模型填寫                                    |

注意：`models.json` 的 `url` 欄位要求**完整介面路徑**，必須以 `/chat/completions` 結尾。

## 設定步驟

* 打開一次 CodeBuddy，讓它生成設定目錄。
* 新建或編輯使用者層級設定檔：
  * macOS / Linux：`~/.codebuddy/models.json`
  * Windows：`C:\Users\<使用者名稱>\.codebuddy\models.json`
  * 若只想對單一專案生效，可改用專案層級 `<專案根>/.codebuddy/models.json`，優先順序高於使用者層級。
* 寫入以下內容，把 `id` 換成你在控制台確認可用的模型名稱：

```json
{
  "models": [
    {
      "id": "gpt-5",
      "name": "GPT-5 (aicentos)",
      "vendor": "aicentos",
      "apiKey": "${AICENTOS_API_KEY}",
      "url": "https://aicentos.com/v1/chat/completions",
      "maxInputTokens": 128000,
      "maxOutputTokens": 16384,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": false
    }
  ]
}
```

* 設定環境變數（`apiKey` 與 `url` 都支援 `${VAR_NAME}` 參照）：

```bash
export AICENTOS_API_KEY="sk-你的aicentos密钥"
```

* 完全離開 CodeBuddy 後重新打開（IDE 面板重新啟動即可）。
* 在模型選擇器中選中剛設定的模型。

如果不想編輯檔案，也可以在 CodeBuddy IDE 的對話面板下方點擊模型選擇框 → **設定自訂模型** → 供應商選 **Custom**，把 Base URL 填 `https://aicentos.com/v1`、填入 API Key 和模型名稱即可。

## 測試

儲存後新建一個對話或編碼任務，先用一句簡單提示詞輕量測試，確認能正常返回內容再正式使用。

## 注意事項

* 目前只支援 **OpenAI 介面格式**的 API。
* `url` 必須寫成完整的 `/v1/chat/completions` 路徑，寫成 `https://aicentos.com/v1` 不會生效。
* 最外層必須是 `{"models": [...]}` 結構，`models` 是必填的頂層欄位。
* `availableModels` 是白名單：一旦填寫，模型下拉選單只顯示列表裡的模型，內建模型會一起消失。不需要限制時請省略該欄位。
* 檔案請儲存為 **UTF-8 無 BOM**，帶 BOM 的 JSON 會導致讀取本地模型設定失敗。
* 環境變數在啟動時解析；若變數不存在，設定檔裡的 `${AICENTOS_API_KEY}` 會原樣保留並導致呼叫失敗。
* 建議把 `models.json` 權限設為 `600`，不要提交到版本庫。
* 也可以用環境變數方式設定 CLI：`CODEBUDDY_API_KEY`、`CODEBUDDY_BASE_URL`、`CODEBUDDY_MODEL`。直接設定 `CODEBUDDY_BASE_URL` 時不要帶 `/chat/completions`，CLI 會自行追加。
* 更多說明見文件站：[https://docs.aicentos.com](https://docs.aicentos.com)