Factory Droid CLI 接入 Models Hub:配置 BYOK 自定义模型

在 Droid CLI 的 settings.json 里用 customModels 添加指向 Models Hub 的自定义模型,附安装命令、推荐模型与常见报错排查。

Droid CLI 是 Factory AI 推出的终端 AI 软件工程 Agent,能在项目目录里规划、编码、调试并跑测试。它支持 BYOK(Bring Your Own Key),在配置文件里声明一个 customModels 数组即可接入任意 OpenAI 兼容网关。把其中一项指向 Models Hub 后,droid 的所有会话都会用 Models Hub 的额度调用你指定的模型。本文只讲接入,其它能力见官方文档。

Droid CLI 在终端里的运行效果

三样东西

接入只需要:Models Hub 的 API Key、接入地址 https://modelsok.com/v1、一个模型名。Droid CLI 要求先登录官方账号(免费)才能使用。

准备

已安装 Droid CLI(见下方安装步骤)。官方主页:factory.ai/product/cli。
一个 Models Hub API Key。在控制台的令牌页创建,令牌所在分组要能访问你打算用的模型。

用途	模型名	定价	实时状态
编码首选	`claude-sonnet-4-6`	查看价格	可用率与延迟
复杂推理与长上下文	`gpt-5.5`	查看价格	可用率与延迟
便宜快速,适合小改动	`gpt-5.4-mini`	查看价格	可用率与延迟

配置步骤

1. 安装 Droid CLI

macOS / Linux:

curl -fsSL https://app.factory.ai/cli | sh

macOS 安装 Droid CLI 后的提示,按提示把 .local/bin 加入 PATH

Windows(PowerShell):

irm https://app.factory.ai/cli/windows | iex

Windows 下运行一键安装命令

按安装提示把对应目录加入 PATH(macOS/Linux 一般追加到 ~/.zshrc 或 ~/.bashrc),重开终端后运行 droid 首次启动,登录官方账号(免费)。

2. 编辑配置文件,加入自定义模型

配置文件位置:macOS/Linux 为 ~/.factory/settings.json,Windows 为 %USERPROFILE%\.factory\settings.json(没有就新建)。在文件里加入 customModels 数组:

{
  "customModels": [
    {
      "model": "claude-sonnet-4-6",
      "displayName": "Models Hub - Claude Sonnet",
      "baseUrl": "https://modelsok.com/v1",
      "apiKey": "your-modelsok-api-key",
      "provider": "generic-chat-completion-api"
    }
  ]
}

字段说明:model 是实际发给 API 的模型 ID,需与 Models Hub 控制台一致;baseUrl 填 Models Hub 接入地址;provider 对通用 OpenAI 兼容网关填 generic-chat-completion-api;apiKey 也支持 ${环境变量名} 写法,把密钥放进环境变量而不是明文写进文件。可以在数组里追加多个对象,对应上面推荐表里的其它模型。

验证

在项目目录启动 Droid CLI:

droid

输入 /model,在列表里应该能看到你添加的自定义模型(以 displayName 命名),选中后发一句「用一句话介绍当前项目」。能正常回复即接通。再打开 Models Hub 控制台的用量日志,几秒内会出现一条对应模型名的请求,确认走的是 Models Hub。

常见报错

现象	原因	处理
`/model` 列表里看不到新增的模型	`settings.json` 格式错误,或文件路径不对	用 JSON 校验工具检查格式,确认文件在 `~/.factory/settings.json`
提示未授权 / `401`	`apiKey` 没填对,或令牌被禁用	到令牌页重新复制
提示模型不存在	`model` 字段与 Models Hub 控制台的模型 ID 不一致	对照定价页核对拼写
Windows 安装提示 permission denied	权限不足	以管理员身份运行 PowerShell,或执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
启动时提示需要登录	Droid CLI 要求先登录官方账号	按提示登录(免费),登录与自定义模型接入互不冲突

更多排查见故障排查。

常见问题

计费方式? 按每次请求实际消耗的输入与输出 token 计费,价格看各模型定价页。

登录官方账号后还会用官方额度吗? 不会。选中 customModels 里的自定义模型后,该次会话走的是 baseUrl 指向的 Models Hub,登录只用于 Droid CLI 本身的身份校验。

怎么切换模型? 对话中输入 /model 重新选择,或在 customModels 数组里加更多条目。