# Crush

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

Language: zh-TW

> 在 Crush 中使用 aicentos —— 透過 crush.json 新增自訂 provider

Crush 是 Charmbracelet 出品的終端機編碼代理，用 Go 撰寫，支援在 `crush.json` 裡宣告任意 OpenAI 相容的自訂 provider。把 base\_url 指向 aicentos，即可在 TUI 裡使用 aicentos 接入的模型。

## 準備工作

先在控制台「API Key」頁面為 Crush 建立一個專用 Key（建議命名 `crush`，方便追蹤用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 建立 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 餘額不足時儲值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

確認已安裝 Crush：

```bash
crush --version
```

## 需要填寫的設定

| 欄位        | 值                            |
| --------- | ---------------------------- |
| 設定檔       | `~/.config/crush/crush.json` |
| type      | `openai-compat`              |
| base\_url | `https://aicentos.com/v1`    |
| api\_key  | `$AICENTOS_API_KEY`          |
| 模型        | 控制台「模型廣場」中的模型名稱              |

## 設定步驟

### 1. 設定 API Key 環境變數

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

需要持久化就寫進 `~/.zshrc` 或 `~/.bashrc`，然後 `source` 一下。

### 2. 編輯 crush.json

全域設定檔位於 `~/.config/crush/crush.json`（Windows 為 `%USERPROFILE%\AppData\Local\crush\crush.json`）；專案根目錄下的 `.crush.json` 或 `crush.json` 會覆蓋全域設定。

寫入：

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "aicentos": {
      "type": "openai-compat",
      "base_url": "https://aicentos.com/v1",
      "api_key": "$AICENTOS_API_KEY",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "context_window": 128000,
          "default_max_tokens": 8192,
          "can_reason": true
        }
      ]
    }
  }
}
```

`models[].id` 必須與端點側的模型 ID 完全一致，請以控制台「模型廣場」為準，可參考 [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list)。

### 3. 選擇模型

啟動 `crush` 後，在 TUI 中按 `Ctrl+L`（或輸入 `/model`），確認能看到 `aicentos` 及其模型。

## 測試

用非互動模式做一次快速驗證：

```bash
crush run "用一句話回答：1+1 等於幾"
```

需要看請求日誌時加 `--debug`。如果出現 404，檢查 `base_url` 是否已帶 `/v1`。

## 注意事項

* **`type` 不要填 `openai`**。`openai` 是給真正走 OpenAI（或 Azure OpenAI）的代理用的；指向第三方相容端點時必須填 `openai-compat`，否則會出現模型識別錯誤或 API 報錯。
* `base_url` 填到 `/v1` 即可，不要帶尾部斜線。
* `api_key` 支援 `$VAR` 與 `$(command)` 展開，建議把金鑰放在環境變數或金鑰檔案裡，不要寫死明文。
* 若接入的是 Anthropic 協定端點（`type` 為 `anthropic`），`base_url` 應止於 `/api`，Crush 會自行追加 `/v1/messages`，且需要額外宣告 `extra_headers` 中的 `anthropic-version`。
* 已知問題：使用自訂 provider 時，TUI 裡的 token 計數與費用統計可能顯示為 0，這不影響實際請求與計費。
* 需要開啟思考輸出時，OpenAI 風格模型用 `"can_reason": true` 搭配 `"reasoning_effort"`；Anthropic 風格模型用 `"think": true`。

## 相關連結

* 自訂 Provider 文件：[https://github.com/charmbracelet/crush](https://github.com/charmbracelet/crush)