# Factory Droid 自定义模型教程：用自己的 API Key 接 Claude 和 GPT

> 在 settings.json 的 customModels 里给 Factory Droid 加 Claude 和 GPT：provider 怎么选、我们跑通的配置和踩到的报错。

- Canonical HTML: https://omniakey.com/zh/blog/factory-droid-custom-models
- Markdown: https://omniakey.com/zh/blog/factory-droid-custom-models.md
- Published: 2026-10-30 (updated 2026-10-30)
- Author: Kiki, COO at OmniaKey
- Language: zh
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

在 Droid 1.0.0 里，自定义模型写在 `~/.factory/settings.json` 的 `customModels` 里。每一项填 `model`、`baseUrl`、`apiKey` 和 `provider` 四个字段。Claude 用 `anthropic`，地址填裸域名；GPT 用 `openai`；其他模型用 `generic-chat-completion-api`。Claude Sonnet 5.5、GPT-6.1 Terra 和 MiniMax M3.1 Flash 跑同一个 bug，分别在 33.7 秒、77.4 秒和 30.7 秒修好。

三次运行都走 OmniaKey，用的是同一把 key，这样一次就用上了 [Claude Sonnet 5.5](https://omniakey.com/zh/claude-sonnet-5-5)、[GPT-6.1 Terra](https://omniakey.com/zh/gpt-6-1-terra) 和 [MiniMax M3.1 Flash](https://omniakey.com/zh/minimax-m3-1-flash)。给它们的都是同一段写坏的 `median()` 函数，三个都修好了。

## 快速答案

- **写在哪里。** 写进 `~/.factory/settings.json` 的 `customModels`，一共四个字段：`model`、`baseUrl`、`apiKey` 和 `provider`（Factory 设置文档，2026 年 10 月 30 日核对）。
- **provider 选哪个。** Claude 用 `anthropic`，GPT 模型用 `openai`，其他支持 Chat Completions 的模型用 `generic-chat-completion-api`。
- **`/v1` 加不加。** `anthropic` 填裸域名，Droid 自己补 `/v1/messages`。`openai` 和 `generic-chat-completion-api` 填以 `/v1` 结尾的地址。
- **`droid exec` 用的 id。** `custom:` 开头，接上把空格换成短横线的显示名，再接从 0 开始的位置：`custom:Claude-Sonnet-5.5-[OmniaKey]-0`。
- **我们跑出来的结果。** 三个模型都修好了。Flash 30.7 秒，Claude 33.7 秒，GPT-6.1 Terra 77.4 秒。

## provider 该填哪个值？

按你的接口支持哪种 API 来选，别按模型名选。

- `anthropic` 发的是 Anthropic Messages API 请求，给 Claude 用。Anthropic 的地址是 `https://api.anthropic.com`。
- `openai` 发的是 OpenAI Responses API 请求，给 GPT 模型用。OpenAI 的地址是 `https://api.openai.com/v1`。
- `generic-chat-completion-api` 发的是 OpenAI Chat Completions 请求，给大多数其他模型、网关和本地服务用。地址填服务商自己的 `/v1`。

Factory 把 `generic-chat-completion-api` 列给 OpenRouter、Fireworks、Together AI、Ollama 和 vLLM。多数开源模型服务商也用它。调 OpenAI 或 Anthropic 官方接口时另说，其他情况 Factory 都建议用这个值（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。

网关只要也支持 Messages API 或 Responses API，就可以填 `anthropic` 或 `openai`。我们通过 OmniaKey 配的 Claude 和 GPT-6.1 Terra 条目就是这样，两个都跑起来了。OmniaKey 的 GPT 模型走 `POST /v1/responses`，这一点写在 OmniaKey 的 OpenAI 兼容文档里（2026 年 10 月 30 日核对）。

第四个值 `bedrock-converse` 给 AWS Bedrock Converse API 上的模型用。Factory 提醒，只有走官方接口的 Anthropic 和 OpenAI 模型做过完整测试和跑分。参数量低于 300 亿的模型，在 agent 编程上明显更差（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。

## 我们用的 settings.json

Droid 第一次启动就会生成 `~/.factory/settings.json`。往已有的文件里加 `customModels` 就行（Factory 设置文档，2026 年 10 月 30 日核对）。我们的是这样：

```json
{
  "customModels": [
    {
      "model": "claude-sonnet-5-5",
      "displayName": "Claude Sonnet 5.5 [OmniaKey]",
      "baseUrl": "https://api.omniakey.com",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 16000
    },
    {
      "model": "gpt-6.1-terra",
      "displayName": "GPT-6.1 Terra [OmniaKey]",
      "baseUrl": "https://api.omniakey.com/v1",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "openai",
      "maxOutputTokens": 16000
    },
    {
      "model": "minimax-m3.1-flash",
      "displayName": "MiniMax M3.1 Flash [OmniaKey]",
      "baseUrl": "https://api.omniakey.com/v1",
      "apiKey": "${OMNIAKEY_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16000
    }
  ]
}
```

- `model` 是发给接口的 id，从服务商的模型列表里原样复制。`displayName` 是你自己起的名字，它显示在 `/model` 里，也用来拼 `custom:` id。
- `baseUrl` 对 `anthropic` 填裸域名，另外两个以 `/v1` 结尾。
- `apiKey: "${OMNIAKEY_API_KEY}"` 从环境变量读 key，不写进文件（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。
- `provider` 决定用哪套接口。这里拼错，就会撞上后面的 "Invalid provider" 报错。
- `maxOutputTokens: 16000` 限制每次回答的长度。

一把 key、两个 [接入地址](https://docs.omniakey.com/cn/api/overview)，三个模型就都通了。Claude 走 OmniaKey 的裸域名，另外两个走 `/v1` 地址。照 [OmniaKey 的编程 agent 配置文档](https://docs.omniakey.com/cn/coding) 配过的话，同一把 key 直接能用。

Factory 说 key 只留在本地。它不会上传到 Factory 服务器（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。旧教程把模型写在 `~/.factory/config.json`，Factory 的 BYOK 文档还说 Droid 启动时会把这些复制进 `settings.json`。Factory 仓库里的一个 pull request（#76）说，2026 年 10 月 15 日合并的代码去掉了这次复制。新模型直接写进 `settings.json` 就行。

## 在 Droid 里怎么选自定义模型？

在应用里打开 `/model`，看 Custom Models 一栏。命令行里给 `droid exec` 传一个 `custom:` 开头的 id。

Factory 的文档说，存好的模型会带着 `displayName` 显示在那里。也可以在 `/settings` > Custom models 里添加。`/model` > Manage custom models 也能加（2026 年 10 月 30 日核对）。

`droid exec` 的 id 分三段：`custom:`、空格换成短横线的显示名、模型在 `customModels` 里的位置。位置从 0 开始。Factory 的 `droid exec` 文档写了这个拼法（2026 年 10 月 30 日核对）。我们的是 `custom:Claude-Sonnet-5.5-[OmniaKey]-0`、`custom:GPT-6.1-Terra-[OmniaKey]-1` 和 `custom:MiniMax-M3.1-Flash-[OmniaKey]-2`。

序号跟着数组顺序走。在中间插一个模型，后面所有 id 都会变，改完文件记得重新复制 id。

`droid exec` 里的 `-r` / `--reasoning-effort` 对自定义模型不起作用（Factory 的 `droid exec` 文档，2026 年 10 月 30 日核对）。要设就在条目里写 `reasoningEffort`。

## 三个模型跑同一个 bug

同样的两个文件，同样的命令，每个模型跑一次。`stats.py`：

```python
def median(values):
    """Return the median of a non-empty list of numbers."""
    ordered = sorted(values)
    mid = len(ordered) // 2
    return ordered[mid]
```

`test_stats.py`：

```python
from stats import median

assert median([3, 1, 2]) == 2
assert median([4, 1, 3, 2]) == 2.5
assert median([5]) == 5
assert median([1.5, 2.5]) == 2.0
print("all tests passed")
```

命令只换 `--model` 的值：

```bash
droid exec --auto medium -o json --model "custom:Claude-Sonnet-5.5-[OmniaKey]-0" "python3 test_stats.py fails. Fix the bug in stats.py without changing the tests, run python3 test_stats.py again, and tell me in one sentence what you changed."
```

|模型|耗时|轮数|输出 token|
|-|-|-|-|
|Claude Sonnet 5.5|33.7 s|3|702|
|GPT-6.1 Terra|77.4 s|4|451|
|MiniMax M3.1 Flash|30.7 s|4|525|

这些是 Droid 自己报的数（`duration_ms`、`num_turns`、`output_tokens`）。Flash 最快，30.7 秒；Claude 用的轮数最少；GPT-6.1 Terra 最慢，77.4 秒。首 token 时间 Claude 是 8.7 秒，Terra 是 17.8 秒，Flash 是 7.0 秒。三个都没动 `test_stats.py`，测试打印出 `all tests passed`。

Claude 的改动：

```diff
-    return ordered[mid]
+    if len(ordered) % 2:
+        return ordered[mid]
+    return (ordered[mid - 1] + ordered[mid]) / 2
```

GPT-6.1 Terra 在原来那行 return 上面加了同样的分支，MiniMax M3.1 Flash 写成 `% 2 == 1`。三个回答讲的都是这个改法：长度为偶数时，取中间两个值的平均。[MiniMax M3.1 Flash 评测](https://omniakey.com/zh/blog/minimax-m3-1-flash-review) 里写得更细。

Droid 的 JSON 结果每次都会打印 `factory_credits`，尽管我们一直没有登录。三个值分别是 31,534、4,830 和 835，对应上面表格的顺序。Factory 的文档没说明这个数字量的是什么。它和 BYOK 额度怎么算，文档里也没写（2026 年 10 月 30 日核对）。

## 用自定义模型需要 Factory 账号或套餐吗？

我们跑的时候，`droid exec` 配 `custom:` 模型不需要 Factory 账号。Factory 自家的模型和交互式应用都要账号。

Droid CLI 1.0.0 在 2026 年 10 月 29 日发布。这条写在 Factory 的更新日志里（2026 年 10 月 30 日核对）。在一个干净的 home 目录、没有登录 Factory 的环境里，每次用 `custom:` 模型跑 `droid exec` 都走我们自己的 key。同一条命令去掉 `--model` 就立刻停下，报 "Authentication failed. Please log in using /login or set a valid FACTORY\_API\_KEY environment variable."（认证失败，请用 /login 登录，或设置有效的 FACTORY\_API\_KEY。）Factory 的 v0.236.0 更新日志（2026 年 10 月 8 日）讲的是恢复会话："Droid exec now resumes a session on your own model credentials without a Factory sign-in."（Droid exec 现在能用你自己的模型凭据恢复会话，不需要登录 Factory。）

在同一个目录直接启动 `droid`，会停在 "Please login with your Factory account to continue."（请登录 Factory 账号后继续。）没有登录，我们没法在交互式或桌面应用里试自定义模型；图片输入、Bedrock、`apiKeyHelper`、`reasoningEffort` 和思考设置、Windows、跨多个任务的会话，还有旧的 `config.json`，也都没有测。

Factory 的 Individual 套餐每月 $20（Pro）、$100（Plus）和 $200（Max）。定价页上还有 Teams，每队每月 $60，外加每个席位 $40。个人没有免费套餐（Factory 的定价文档和定价页，2026 年 10 月 30 日核对）。

Individual 定价文档写着："BYOK is free up to an allowance on all Individual plans. After that, usage is charged according to your specific plan."（BYOK 在所有 Individual 套餐里免费到一定额度，超出后按你的具体套餐计费。）Factory 没写这个额度有多大，也没写超出以后怎么收。

个人自定义模型在命令行和桌面应用里都能用。Factory 托管的网页版和手机版里没有（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。

## 会撞上哪些报错，怎么修？

每一个都是配置里一个值写错，其余部分正常。环境是 Droid 1.0.0。

1. `anthropic` 的 `baseUrl` 带了 `/v1`。Droid 在 0.9 秒后打印 "Requested model was not found on the API provider"（API 服务商上找不到请求的模型），日志里是 `404` 和 `Invalid URL (POST /v1/v1/messages)`。Droid 自己会补 `/v1/messages`，我们再写一个 `/v1` 就重复了。改法：填裸域名，`https://api.anthropic.com` 或 `https://api.omniakey.com`。

2. `openai` 填了裸域名。1.4 秒后 Droid 打印 `404` 和 nginx 的 "404 Not Found" 页面。Responses API 在 `/v1` 下面。改法：`https://api.openai.com/v1` 或 `https://api.omniakey.com/v1`。

3. 模型 id 用了点号 `claude-sonnet-5.5`，正确写法是 `claude-sonnet-5-5`。接口返回 `503`，错误码 `model_not_found`。消息是 "No available channel for model claude-sonnet-5.5"（没有可用渠道处理这个模型）。Droid 的日志把每次失败都记成 "overloaded"，一共试了 10 次。259.7 秒（约 4 分 20 秒）之后才退出。措辞是网关给的，重试是 Droid 做的。改法：从服务商的模型列表里原样复制 id。

4. 启动 Droid 的 shell 里 `OMNIAKEY_API_KEY` 是空的。2.8 秒后 Droid 收到 `401` 和 "Invalid token"（token 无效）。改法：在启动 `droid` 的那个 shell 里 export key，再开一个新会话。

Factory 的排查文档另外列了两条。"Invalid provider" 表示值拼错或者大小写不对，必须正好是 `anthropic`、`openai`、`generic-chat-completion-api` 或 `bedrock-converse`。模型没出现在选择器里时，文档建议先看 `~/.factory/settings.json` 的 JSON 语法。再确认每个条目字段齐全（2026 年 10 月 30 日核对）。

## 常见问题

### Windows 上 Droid 的设置文件在哪？

`%USERPROFILE%\.factory\settings.json`，和 macOS、Linux 上的 `~/.factory/settings.json` 是同一个文件（Factory 设置文档，2026 年 10 月 30 日核对）。`customModels` 写在这里。

### 自定义模型为什么不出现在 `/model` 里？

先查 `~/.factory/settings.json` 的 JSON 语法，再查 `model`、`baseUrl` 和 `provider` 三个字段。Droid 靠文件监听发现保存的改动（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。有一份反馈说，Desktop 0.184.0 配 CLI 0.227.0，自定义模型在桌面选择器里出现一下就消失了。同一个环境下 `droid exec --help` 还能列出全部 14 个。这个问题现在已经关闭（Factory-AI issue #40，2026 年 10 月 30 日核对）。

### 自定义模型能读图片吗？

`anthropic` 和 `openai` 默认支持图片，`generic-chat-completion-api` 默认不支持，`noImageSupport` 默认为 `true`（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。在 generic 条目里设 `noImageSupport: false` 就能打开。有一份反馈说，CLI v0.205.1 上这样设了，图片还是被剥掉（Factory-AI issue #24，2026 年 10 月 30 日核对）。

### 能给自定义模型设推理强度吗？

`droid exec` 的 `-r` / `--reasoning-effort` 对自定义模型不起作用。在条目里写 `reasoningEffort` 就行。它给 Droid 不认识的模型设默认强度，选择器里会多出 off、low、medium 和 high（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。

### 桌面版 Droid 能用自定义模型吗？

能。个人自定义模型在命令行和桌面应用里都能用，但不会出现在托管的网页版和手机版里。命令行和桌面应用的模型编辑器都存到 `~/.factory/settings.json`（Factory 的 BYOK 文档，2026 年 10 月 30 日核对）。

## 核对过的来源

- [Factory BYOK 文档](https://docs.factory.com/model-independence/byok.md)，2026 年 10 月 30 日核对
- [Factory 设置文档](https://docs.factory.com/droid-cli/settings.md)，2026 年 10 月 30 日核对
- [Factory droid exec 文档](https://docs.factory.com/droid-exec/overview.md)，2026 年 10 月 30 日核对
- [Factory 更新日志](https://docs.factory.com/changelog/release-notes.md)，2026 年 10 月 30 日核对
- [Factory Individual 套餐](https://docs.factory.com/pricing/individuals.md)，2026 年 10 月 30 日核对
- [Factory 定价](https://factory.com/pricing)，2026 年 10 月 30 日核对
- [Factory-AI issue #40：自定义模型在桌面选择器里消失](https://github.com/Factory-AI/factory/issues/40)，2026 年 10 月 30 日核对
- [Factory-AI issue #24：图片被剥掉](https://github.com/Factory-AI/factory/issues/24)，2026 年 10 月 30 日核对
- [Factory-AI pull request #76：config.json 迁移](https://github.com/Factory-AI/factory/pull/76)，2026 年 10 月 30 日核对

OmniaKey 自己的文档，2026 年 10 月 30 日核对：[API 概览](https://docs.omniakey.com/cn/api/overview) 和 [OpenAI 兼容 API](https://docs.omniakey.com/cn/api/openai-compatible)。