# Droid（Factory）接入

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

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（`provider: "anthropic"`）· GPT ✅ · 国产 ✅（`provider: "generic-chat-completion-api"`）· Gemini ❌（官方无该 provider） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI Chat：`https://api.qcode.cc/openai/v1` |
| 配置位置 | `~/.factory/settings.json`（首次运行 `droid` 时自动创建） |
| 官方文档 | [BYOK](https://docs.factory.ai/model-independence/byok) · [settings](https://docs.factory.ai/droid-cli/settings) |

[Droid](https://docs.factory.ai/droid-cli/overview) 是 Factory 出品的终端 AI 编程 Agent，支持 **BYOK（自带密钥）自定义模型**，可以把 QCode.cc 配成上游。

## 走哪条腿

Droid 的自定义模型用 `provider` 字段区分协议。**要用 Claude 就填 `anthropic`**——QCode 的 OpenAI 端点不接受 Claude 模型（见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）。

| 你想用的模型 | `provider` | `baseUrl` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT 系 / 国产四家族 | `generic-chat-completion-api`（Chat Completions 兼容） | `https://api.qcode.cc/openai/v1` |

> 🔴 别填 `"provider": "openai"`——官方语义里它**专指 OpenAI Responses API**（“Use provider: `"generic-chat-completion-api"` unless you are calling OpenAI's or Anthropic's official API”，[BYOK 文档](https://docs.factory.ai/model-independence/byok)）。QCode 的 GPT / 国产模型走 Chat Completions 腿，必须用 `generic-chat-completion-api`。

## 安装

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

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

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

```bash
droid --version
```

## 配置

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

```json
{
  "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
    }
  ]
}
```

密钥用环境变量注入：

```bash
export QCODE_KEY="cr_你的QCode密钥"
```

| 字段 | 说明 |
|------|------|
| `model` | 传给 API 的模型 id，须与 [qcode.cc/models](https://qcode.cc/models) 逐字符一致 |
| `displayName` | 模型选择器里显示的名字，随便起 |
| `baseUrl` | 填到 `/api` 为止，Droid 会自己拼 `/v1/messages` |
| `apiKey` | 支持 `${变量名}` 形式的环境变量引用 |
| `provider` | 三选一：`anthropic`（Claude 用这个）· `openai`（**专指 Responses API**，接 QCode 不用）· `generic-chat-completion-api`（GPT / 国产用这个） |
| `maxOutputTokens` | 单次回复的输出上限 |

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

## 验证

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

返回 `OK` 即接通。

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

## 常用用法

```bash
# 交互模式
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 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [Crush 接入](/docs/ide/crush) — 另一个终端 Agent
- [国产模型接入](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen