# Droid

来源: https://docs.aicentos.com/clients/droid

Language: zh-CN

> 在 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)