Factory Droid

在 ~/.factory/settings.json 中添加 customModels 条目 — model、baseUrl 和 provider — 让 Droid 使用任何支持 Anthropic Messages 或 OpenAI Chat Completions 的端点。

// ~/.factory/settings.json  (Windows: %USERPROFILE%\.factory\settings.json)
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "Sonnet 5 [Kunavo]",
      "baseUrl": "https://api.kunavo.com",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "anthropic"
    },
    {
      "model": "gpt-5-6-sol",
      "displayName": "GPT-5.6 Sol [Kunavo]",
      "baseUrl": "https://api.kunavo.com/v1",
      "apiKey": "${KUNAVO_API_KEY}",
      "provider": "generic-chat-completion-api"
    }
  ]
}

// Then, in the shell Droid starts from:
//   export KUNAVO_API_KEY=sk-kn-...
// ${VAR_NAME} expansion is a settings.json feature. It does NOT apply to the
// legacy ~/.factory/config.json, which Factory still loads and merges.

分步操作

1. 在 /app/keys 创建密钥并复制；密钥只会显示一次。在启动 Droid 的 shell 中将其导出为 KUNAVO_API_KEY，这样密钥本身就不会写入设置文件。
2. 打开 ~/.factory/settings.json（如果文件不存在就创建），并添加上方的 customModels 数组。Factory 明确要求三个字段：model、baseUrl 和 provider；displayName 是在选择器中显示的标签。
3. 检查 provider 的拼写。它必须与 anthropic、openai 或 generic-chat-completion-api 中的一项完全一致；Factory 的故障排查部分指出，拼写错误会导致其 "Invalid provider" 错误。
4. 在 CLI 中运行 /model。你的条目会显示在 Factory 自有模型下方的单独 Custom models 区域中，并以你设置的 displayName 为标签。Factory 会监视设置文件，因此保存即可，无需重启。
5. 给它一个需要读取并编辑文件的任务，而不是打招呼。Droid 几乎所有操作都依赖工具调用，而普通聊天轮次无法检验这一点。然后运行 /cost，Factory 会在此处报告缓存命中率——Kunavo 原生提供 Anthropic 的 cache_control 标记；Factory 自己也指出，在通用 Chat Completions 服务商中，缓存“因服务商而异，无法保证”。

已于 2026年9月21日 对照 Factory 的自定义模型（BYOK）页面 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 Factory Droid 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

Droid 中的自定义模型无法覆盖哪些场景

有三项限制来自 Factory 自己的页面，每一项都会影响你对上述配置的预期，但不影响它是否可用。

• 仅适用于本地界面。 Factory 的 BYOK 页面说明，自定义模型可用于 Droid CLI 和桌面应用，它们会读取本地 settings.json；并且这些模型“不会出现在 Factory 托管的网页或移动平台上”。通过托管产品委派的工作仍会使用由 Factory 计费的推理服务，无论你在此处配置了什么密钥。
• 管理员可以将其关闭。Factory 的企业控件文档介绍了 modelPolicy.allowCustomModels 和 allowedBaseUrls，它们可以彻底禁用用户 BYOK，或将所有自定义模型限定到一个获准的主机。在受管理的设备上，调试文件之前先检查这一点。
• 套餐费用仍然存在。此处的密钥是额外选项，而非替代方案——Factory 在 BYOK 额度之外收取的费用，以及该额度的具体内容，详见 费用指南；本页面不会重新推算这些信息。

复制其他地方的配置之前，有个容易踩的坑值得了解：Factory 仍会加载旧版 ~/.factory/config.json，其中使用 snake_case 的 custom_models 和 base_url，并将其合并到 settings.json 之下；文档说明，${VAR_NAME} 展开功能在此处不适用。写在该文件中的占位密钥会按字面内容发送。请使用 settings.json。