Factory Droid + JoinGonka Gateway：在 Gonka 网络模型上使用 BYOK

第 1 步：安装 Droid。来自 Factory 官方文档的推荐方式：

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

脚本会把二进制文件放到 ~/.local/bin，并提示如何将该目录加入 PATH；在 Linux 上，文档还要求安装 xdg-utils 软件包。验证方式：droid --version。

第 2 步：获取密钥。在 gate.joingonka.ai/register 注册，验证邮箱地址，然后在「API 密钥」板块创建一个以 jg- 为前缀的密钥。一个密钥、一份余额即可用于网络中的所有模型。

第 3 步：运行安装程序。

npx @joingonka/setup --tool droid

安装程序会询问密钥 —— 密钥不会通过命令行参数传入，以免残留在 shell 历史记录中 —— 然后完成四件事：

• 在 ~/.factory/settings.json（Windows 上为 %USERPROFILE%\.factory\settings.json）的 customModels 数组中为网络中的每个模型写入一条记录：网关地址、提供商类型 generic-chat-completion-api、明文密钥、真实的上下文窗口和响应上限；该文件权限将设为 600；
• 将默认模型 —— sessionDefaultSettings.model —— 设为 DeepSeek V4 Flash，但仅当尚未选择模型，或所选模型已退出网络时才会设置。它不会覆盖 Factory 目录中的模型或他人的 BYOK 记录，而是会提示如何切换；
• 保存原文件的副本，customModels 中的其他记录、其余设置和注释均保持原样；无法解析的文件不会被覆盖，而是会提示需要修正的地方；
• 最后向网关发送一次实时请求，并明确告知密钥、地址和模型是否被接受。

如需指定其他默认模型，可使用 --model 参数，并支持简写 deepseek、glm 或 minimax —— 显式指定的模型总会被写入。针对 dotfiles 和服务器还有免交互模式，密钥从环境变量读取：

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

无需重启 Droid：它会自行检测 settings.json 的更改。结尾出现 ! Could not verify right now 并伴随 429 响应，表示模型正忙，而非配置错误 —— 配置已经写入。

安装脚本所做的每一件事，你都可以手动完成。Droid 的用户设置存放在 ~/.factory/settings.json 中；如果该文件不存在，Droid 会在首次启动时自动创建。要接入 Gonka 网络，需要 customModels 数组和一个默认模型：

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

默认模型保存在 sessionDefaultSettings.model 中，通过条目的 id 引用。Factory 文档还提到文件根部的 model 键，但在我们的实测中，不带 -m 参数的 droid exec 正是从 sessionDefaultSettings 取用模型的——改值之后同样如此。

密钥以明文形式存放在文件中：请用 chmod 600 ~/.factory/settings.json 收紧文件权限，也不要把含密钥的条目挪进项目的 .factory/settings.json——这个文件通常会被提交进仓库。另外，如果 Droid 启动后文件看起来变了样，这很正常：每次保存任何设置，Droid 都会整体重写文件——重排键顺序、给条目补上 index 字段，并且不保留注释。此时 600 权限依然保留，安装脚本也能照常更新这些条目。

Droid 将自己的模型与目录分开显示：根据文档，在交互模式下，/model 命令会在 Custom models 部分列出它们，而 Ctrl+N 可以在输入框中直接切换模型。在单次运行模式下，模型由 -m 标志指定，其值取自 id 字段，斜杠按原样书写：droid exec -m custom:zai-org/GLM-5.3-Flash "…"。

如果名字写错了，Droid 会返回 Invalid model，并列出它能看到的全部模型，包括以 custom:… (display name) 形式呈现的自有模型：顺便也能看到模型已经加载成功。按照 Factory 文档风格构造的名字，即由显示名称加编号组成的名字（custom:DeepSeek-V4-Flash-(Gonka)-0），在明确给出 id 时不会生效——在我们的测试中，它同样返回了 Invalid model。

哪些操作需要 Factory 账户。自有模型解决了 token 付费的问题，但并没有解决登录产品本身的问题。以下是我们未登录账户运行 Droid 0.225.1 的结果：

要在界面中使用，请注册 Factory 账户并通过浏览器登录——即 Login 选项或 /login 命令；在没有浏览器的机器上，文档建议从账户设置中获取密钥并放入 FACTORY_API_KEY 环境变量。不登录就能运行 droid exec 方便试用，但这并未被官方文档说明——不要在 CI 中依赖它。根据 Factory 的定价页面，BYOK 包含在所有个人套餐中并带有免费额度，超出额度后 BYOK 的使用按套餐条款计费；最新条款见 factory.ai/pricing。网络模型的 token 则需单独付费——从 JoinGonka 余额中扣除。

该选哪个模型。网络上所有模型价格相同，所以选择取决于行为表现。以下是在我们的 droid exec 测试中，它们处理同一任务——读取文件并找出错误——的表现：

根据 Factory 的文档，-r 标志（推理级别）不适用于 BYOK 模型。为什么默认选择 DeepSeek V4 Flash，已在模型评测中详细说明。

在一个空目录里放入一个 calc.py 文件，里面藏一个明显的 bug——比如长方形面积计算把边长相加而不是相乘——然后让 Droid 把它找出来：

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

不加任何参数时，droid exec 运行在只读模式：可以查看文件，但不能修改。Agent 会自行调用读取工具并给出实质性的回答，指出出错的那行表达式。加上 -o json 参数后，回复会以单个对象返回，方便用脚本解析（输出有删减）：

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

factory_credits: 0 字段说明任务跑在你自己的模型上，而不是消耗 Factory 的额度。要让 agent 能修改文件，提高自主级别：droid exec --auto low "Fix the bug in calc.py and change nothing else."——在我们的测试中，DeepSeek V4 Flash 读取了文件，将加法替换为乘法，并自行运行脚本确认输出为 12。

第三项检查来自网关侧：在控制台的「使用情况」页面，这个请求会出现在「按模型」明细中，「按密钥」区块里的最后请求时间也会更新。

如果出了问题，请留意 Droid 的一个特点：在控制台里 droid exec 只会打印 Error during droid execution: Exec failed（在 JSON 中为 "result":"Exec failed"），真正的原因留在日志里。用一条命令就能把它挖出来：

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

代理工具消耗 token 的方式与聊天不同：对于你的每一句话，Droid 都会添加系统提示词、工具描述和工作目录快照，而且任务通常需要多轮交互。在我们的运行测试中，每一轮在你的问题发出前就已经消耗了大约 9500 个输入 token：“读取文件并查找错误”任务占用了两轮和约 1.9 万个 token，“修复并验证”则占用四轮和约 4.4 万个 token。因此，这里的 token 价格至关重要。

通过 JoinGonka Gateway，输入 token 价格为每百万 $0.0069，输出 token 价格为每百万 $0.021——所有网络模型价格一致，并从实时源更新至此页面。

右侧栏的估算基于 2026 年 9 月的价格。作为参考，在 Droid 中支付模型费用的一般方式：

Droid 界面中的 /cost 命令显示会话统计信息，而 BYOK 模型的精确消费和余额可在网关后台的“使用情况”和“账单”部分查看。请为 Droid 创建单独的密钥——其流量将显示为单独的一行。

自主性。在单次运行模式下，Droid 默认只读，权限由自主级别逐步放宽：--auto low——修改文件，--auto medium——再加上安装依赖、构建、测试和本地提交，--auto high——一直到 push 和部署。--skip-permissions-unsafe 参数会关闭所有检查——仅用于一次性容器。在交互模式下，Ctrl+L 切换级别，起始级别由 sessionDefaultSettings.autonomyLevel 指定；默认是 off——所有操作都需要确认。

提交签名。includeCoAuthoredByDroid 设置默认开启：Droid 会在提交信息里加上一行协作者署名。如果不需要，在 settings.json 中写入 "includeCoAuthoredByDroid": false。

会话存储在哪里。登录账号后，Droid 默认会把 CLI 会话镜像到 Factory 网页版——由 cloudSessionSync 控制。根据文档，BYOK 密钥保留在本地；如果连对话记录也要留在本机，设置 "cloudSessionSync": false。网关这边不存储提示词和回复的内容——统计里只保留用量汇总。

更新。用脚本安装的版本会自动更新；可以用 FACTORY_DROID_AUTO_UPDATE_ENABLED=false 环境变量固定版本，或用 droid update --version <version> 命令；npm 安装的构建不会自动更新。更新后，用一条 droid exec 检查网络模型是否还在。

图片。网络模型是纯文本的；需要处理截图时，请另外保留一个来自其他厂商、支持视觉的模型条目。

如果必须在不使用厂商账号的情况下工作。同样的网络模型可以接入无需登录的开源终端 agent——例如用同一个安装器加 --tool opencode 参数接入 OpenCode。