# Droid

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

Language: zh-TW

> 在 Factory Droid 中使用 aicentos —— 透過 settings.json 註冊自訂模型（BYOK）

Droid 是 Factory 推出的命令列編碼代理，支援 BYOK：在 `~/.factory/settings.json` 裡登記自訂模型，把 `baseUrl` 指向 aicentos 即可。Droid 要求模型上下文視窗至少 64k，選型時留意。

## 準備工作

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

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

## 需要填寫的設定

| 欄位       | 值                             |
| -------- | ----------------------------- |
| 設定檔      | `~/.factory/settings.json`    |
| provider | `generic-chat-completion-api` |
| baseUrl  | `https://aicentos.com/v1`     |
| apiKey   | `${AICENTOS_API_KEY}`         |
| 模型       | 控制台「模型廣場」中的模型名稱               |

## 設定步驟

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

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

寫進 `~/.zshrc` 或 `~/.bashrc` 可持久化。

### 2. 編輯 settings.json

編輯 `~/.factory/settings.json`，新增 `customModels` 陣列：

```json
{
  "customModels": [
    {
      "model": "gpt-4o",
      "displayName": "GPT-4o (aicentos)",
      "baseUrl": "https://aicentos.com/v1",
      "apiKey": "${AICENTOS_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192
    }
  ]
}
```

關鍵欄位：

| 欄位            | 說明                                                     |
| ------------- | ------------------------------------------------------ |
| `model`       | 實際發往端點的模型 ID，需與控制台「模型廣場」一致                             |
| `displayName` | 模型選擇器中的顯示名稱，可自訂                                        |
| `baseUrl`     | API 位址，建議帶 `/v1`                                       |
| `apiKey`      | 支援 `${VAR_NAME}` 展開                                    |
| `provider`    | `anthropic` / `openai` / `generic-chat-completion-api` |

### 3. 選擇模型

啟動 `droid` 後執行 `/model`，選中剛才註冊的模型。**修改設定後需要在新的終端機裡重新啟動 `droid`** 才會重新讀取檔案。

## 測試

選中模型後發一條簡單請求：

```
用一句話回答：1+1 等於幾
```

能正常返回即接入成功。

## 注意事項

* **`provider` 建議填 `generic-chat-completion-api`**，它走 OpenAI Chat Completions 協定，也是大多數 BYOK 場景的正確選擇。填 `openai` 會走 Responses API，且部分閘道下該取值會忽略 `base_url` 直接指向 `api.openai.com`；填 `anthropic` 則走 `/v1/messages`。
* **先清理環境變數**。如果 shell 裡匯出了 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 或 `ANTHROPIC_API_KEY`，它們會覆蓋設定檔，導致請求繞過你設定的閘道。接入前建議 `unset` 這幾個變數。
* Droid 同時讀取 `~/.factory/settings.json` 與舊版 `~/.factory/config.json`，前者優先。舊版的欄位名稱是蛇形的 `custom_models` / `model_display_name` / `base_url` / `api_key`，且**不支援** `${VAR_NAME}` 展開，建議統一用 `settings.json`。
* 模型上下文視窗至少 64k，過小的本地模型表現可能異常。
* Factory 只對官方 Anthropic / OpenAI 介面做基準測試，自訂模型的相容性不作保證；已知子代理（subagent）有時會回落到 Anthropic 官方介面。
* 排查順序：`/model` 裡能否看到模型 → 環境變數是否被 ANTHROPIC\_\* 覆蓋 → baseUrl 是否帶 `/v1` → 餘額是否充足。

## 相關連結

* BYOK 官方文件：[https://docs.factory.ai/model-independence/byok](https://docs.factory.ai/model-independence/byok)