# Подключение 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 ❌ (такого провайдера нет) |
| Протокол и 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) — терминальный AI-агент для программирования от Factory. Он поддерживает **BYOK-модели (со своим ключом)**, поэтому QCode.cc можно указать как источник.

## Какой протокол выбрать

Droid выбирает протокол по полю `provider`. **Для Claude нужен `anthropic`** — точка OpenAI у QCode не принимает модели 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)). GPT / китайские модели QCode говорят на 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; должен совпадать с [qcode.cc/models](https://qcode.cc/models) |
| `displayName` | Подпись в списке моделей; произвольная |
| `baseUrl` | До `/api`; Droid сам добавляет `/v1/messages` |
| `apiKey` | Поддерживает ссылки вида `${ПЕРЕМЕННАЯ}` |
| `provider` | Для Claude — `anthropic` |
| `maxOutputTokens` | Ограничение вывода на один ответ |

> По документации Factory, **ключи остаются локально и не загружаются на серверы 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) — другой терминальный агент
- [Китайские модели](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen