# Goose

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

Language: zh-TW

> 在 Goose 中使用 aicentos —— 宣告自訂 OpenAI 相容 provider

Goose 是 Block 開源的編碼代理，支援兩種方式指向一個 OpenAI 相容端點：複用內建的 `openai` provider 並改寫 host，或者宣告一個獨立的自訂 provider。推薦後者，端點資訊更集中，也方便同時保留多套設定。

## 準備工作

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

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

## 需要填寫的設定

| 欄位             | 值                                                |
| -------------- | ------------------------------------------------ |
| 自訂 provider 檔案 | `~/.config/goose/custom_providers/aicentos.json` |
| engine         | `openai`                                         |
| base\_url      | `https://aicentos.com/v1/chat/completions`       |
| api\_key\_env  | `AICENTOS_API_KEY`                               |
| 模型             | 控制台「模型廣場」中的模型名稱                                  |

## 設定步驟

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

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

寫進 `~/.zshrc` 或 `~/.bashrc` 可持久化。**不要把金鑰寫進 config.yaml**，官方明確建議用環境變數或系統鑰匙圈。

### 2. 宣告自訂 provider

新建 `~/.config/goose/custom_providers/aicentos.json`（Windows 為 `%APPDATA%\Block\goose\config\custom_providers\`）：

```json
{
  "name": "aicentos",
  "engine": "openai",
  "display_name": "aicentos",
  "description": "aicentos 接入的模型",
  "api_key_env": "AICENTOS_API_KEY",
  "base_url": "https://aicentos.com/v1/chat/completions",
  "models": [
    {
      "name": "gpt-4o",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "dynamic_models": true
}
```

必填欄位為 `name`、`engine`、`display_name`、`base_url`、`models`，其中 `engine` 取 `openai` / `anthropic` / `ollama`。

模型名稱以控制台「模型廣場」為準，可參考 [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list)。

### 3. 在 config.yaml 中設為預設

編輯 `~/.config/goose/config.yaml`：

```yaml
GOOSE_PROVIDER: aicentos
GOOSE_MODEL: gpt-4o
```

Goose 啟動時會掃描 `custom_providers/` 目錄並自動註冊，之後也可以在圖形介面裡切換。

## 測試

先用非互動工作階段驗證：

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

能正常返回即接入成功。

## 注意事項

* **`base_url` 要寫到完整路徑**（這裡帶 `/v1/chat/completions`），與多數用戶端的寫法不同。若需要顯式指定路徑，新版本還支援 `base_path` 欄位，它的優先順序高於 URL 解析。
* **環境變數優先順序高於 config.yaml**。shell 裡若已匯出 `OPENAI_HOST`，會靜默覆蓋檔案裡的設定，排查時先 `env | grep -i openai`。
* 只有選中了 provider，Goose 才會正常啟動。若在 `config.yaml` 裡寫了設定但從未執行 `goose configure`，可能回報 `No provider configured` —— 這是常見誤解，設定項本身是 YAML 格式，不是 `.env`。
* `dynamic_models: true` 時 Goose 會呼叫端點的 `/v1/models` 拉取模型列表；若只想暴露指定模型，刪掉該欄位或設為 `false`。
* 另一種簡易做法是複用內建 provider：在 config.yaml 裡設 `GOOSE_PROVIDER: openai`，再用 `OPENAI_HOST` 加 `OPENAI_BASE_PATH` 串接端點。這種方式更省事，但與環境變數的耦合更強，容易踩到上面的覆蓋問題。
* 排查順序：provider 名稱與 JSON 檔名是否完全一致 → `base_url` 是否含完整路徑 → 環境變數是否可見 → 餘額是否充足。

## 相關連結

* 自訂 Provider 文件：[https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom)