Droid（Factory）接入

把 QCode.cc 配成 Factory Droid CLI 的 BYOK 自定义模型：~/.factory/settings.json 里 provider=anthropic + baseUrl

最后核实：2026-09-18 · 📄 依据官方文档（Droid CLI v0.222.0，2026-09-18 发布；发版频繁，以 droid --version 为准）

接入速览¶

Droid 是 Factory 出品的终端 AI 编程 Agent，支持 BYOK（自带密钥）自定义模型，可以把 QCode.cc 配成上游。

走哪条腿¶

Droid 的自定义模型用 provider 字段区分协议。要用 Claude 就填 anthropic——QCode 的 OpenAI 端点不接受 Claude 模型（见 接入点与 API 格式）。

🔴 别填 "provider": "openai"——官方语义里它专指 OpenAI Responses API（“Use provider: "generic-chat-completion-api" unless you are calling OpenAI's or Anthropic's official API”，BYOK 文档）。QCode 的 GPT / 国产模型走 Chat Completions 腿，必须用 generic-chat-completion-api。

安装¶

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

安装到 ~/.local/bin/droid。如提示 PATH 未配置，按脚本给出的命令加进 ~/.zshrc / ~/.bashrc。

验证（以实际输出为准）：

droid --version

配置¶

编辑 ~/.factory/settings.json（首次运行 droid 会自动创建；也可以在项目 .factory/settings.local.json 放覆盖项，会合并生效并记得加入 .gitignore）：

{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "QCode Sonnet 5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    },
    {
      "model": "claude-haiku-4-5",
      "displayName": "QCode Haiku 4.5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 4096
    }
  ]
}

密钥用环境变量注入：

export QCODE_KEY="cr_你的QCode密钥"

Factory 官方说明：API Key 保存在本地，不会上传到 Factory 服务器。 国内用户把域名换成 https://asia.qcode.cc/api（亚洲节点，韩国 / 台湾 / 香港就近）即可。

验证¶

droid exec --model "claude-sonnet-5" "reply with exactly: OK"

返回 OK 即接通。

阴性对照（证明配置真的生效）：把 baseUrl 临时改成一个不存在的路径再跑一次， 应当报错失败。只看到成功不能证明走的是你配的这条腿。

常用用法¶

# 交互模式
droid

# 非交互执行
droid exec "把测试跑一遍，修掉失败的用例"

# 指定工作目录
droid --cwd /path/to/project

# 在 git worktree 里跑（隔离改动）
droid -w feature-x

# 自主程度
droid --auto medium

常见问题¶

model_not_available_on_endpoint¶

provider 写成了 OpenAI 兼容而模型是 Claude。改成 "provider": "anthropic"， baseUrl 填 https://api.qcode.cc/api。

401 / 鉴权失败¶

${QCODE_KEY} 没被展开（环境变量未导出），或密钥带了空格。 echo $QCODE_KEY 确认以 cr_ 开头。 另一个常见坑：把配置写进旧格式 ~/.factory/config.json（snake_case 字段）——官方明确 legacy 文件里的 apiKey 不做环境变量展开，${QCODE_KEY} 会被原样当密钥发出。请用 settings.json。

模型选择器里看不到¶

只有 customModels[] 里列出的模型才会出现。加一条记录再重启。

相关文档¶

• 接入点与 API 格式 — 协议 × 模型家族真源表
• Crush 接入 — 另一个终端 Agent
• 国产模型接入 — GLM / Kimi / DeepSeek / Qwen