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

在 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、GPT-6.1 Terra 和 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 日核对）。我们的是这样：

{
  "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、两个 接入地址，三个模型就都通了。Claude 走 OmniaKey 的裸域名，另外两个走 /v1 地址。照 OmniaKey 的编程 agent 配置文档 配过的话，同一把 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：

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：

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 的值：

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."

这些是 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 的改动：

-    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 评测 里写得更细。

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 文档，2026 年 10 月 30 日核对
• Factory 设置文档，2026 年 10 月 30 日核对
• Factory droid exec 文档，2026 年 10 月 30 日核对
• Factory 更新日志，2026 年 10 月 30 日核对
• Factory Individual 套餐，2026 年 10 月 30 日核对
• Factory 定价，2026 年 10 月 30 日核对
• Factory-AI issue #40：自定义模型在桌面选择器里消失，2026 年 10 月 30 日核对
• Factory-AI issue #24：图片被剥掉，2026 年 10 月 30 日核对
• Factory-AI pull request #76：config.json 迁移，2026 年 10 月 30 日核对

OmniaKey 自己的文档，2026 年 10 月 30 日核对：API 概览 和 OpenAI 兼容 API。