# Настройка Factory Droid CLI через RouterAI (BYOK / Custom Models) ## Factory Droid Droid — терминальный coding-агент от Factory ([документация](https://docs.factory.com)). Он работает в терминале и десктопном приложении: читает и правит код, запускает команды, подключает MCP-серверы. Droid поддерживает Custom Models (BYOK, Bring Your Own Key): можно подключить любую модель через свой API-ключ. По документации Factory, ключи хранятся локально и не загружаются на серверы Factory. RouterAI подходит для этого как OpenAI-совместимый провайдер: в одном агенте доступны Claude, GPT, DeepSeek и GLM из [каталога моделей](/models), работа из России без VPN и оплата в рублях. ## Требования * macOS, Linux или Windows * Аккаунт Factory: Droid при первом запуске просит войти (подробности в разделе «Ограничения») * API-ключ из [личного кабинета](/settings/keys) * На Linux нужен пакет `xdg-utils` (`sudo apt-get install xdg-utils`), как указано в quickstart Factory ## Установка Команды взяты из [quickstart Droid CLI](https://docs.factory.com/cli/getting-started/quickstart). macOS и Linux: ```bash curl -fsSL https://app.factory.ai/cli | sh ``` Homebrew: ```bash brew install --cask droid ``` Windows (PowerShell): ```powershell irm https://app.factory.ai/cli/windows | iex ``` npm: ```bash npm install -g droid ``` Запустите агент в папке проекта: ```bash cd /path/to/your/project droid ``` На первом запуске Droid показывает экран входа: пункты **Login**, **Sign into a Factory Private deployment** и **Exit**. ![1.00](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/223c6f89c8dbec9a59101d55e3bd98ce.png) ## Подключение к RouterAI Модель можно добавить тремя способами. Все они пишут в один файл `~/.factory/settings.json`, так что результат одинаковый. | Где | Как | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | CLI | `/settings` → **Custom models**, либо `/model` → **Manage custom models**. Выберите **Add model**, провайдера, заполните поля и нажмите **Save changes** | | Десктопное приложение | **Settings** → **Custom Models** → **Add Model**. Поля заполняются в режиме **Form**, либо можно переключиться на **JSON** и править объект модели напрямую | | Файл | Массив `customModels` в `~/.factory/settings.json` | Ниже разобран третий способ: он быстрее всего и хорошо повторяется на нескольких машинах. ### OpenAI-совместимый API (Chat Completions) Подходит для всех моделей каталога. В Factory для этого служит провайдер `generic-chat-completion-api`: по документации, он работает через OpenAI Chat Completions API и предназначен для OpenRouter, Fireworks, Together AI, Ollama, vLLM и большинства других провайдеров. 1. Сохраните ключ в переменную окружения (например, в `~/.zshrc` или `~/.bashrc`): `export ROUTERAI_API_KEY="sk-xxxxxxxxxxxxxxxx"`. 2. Откройте `~/.factory/settings.json` и добавьте массив `customModels`. Пример для четырёх моделей: ```json { "customModels": [ { "model": "deepseek/deepseek-v4.1-flash", "displayName": "DeepSeek V4.1 Flash [RouterAI]", "baseUrl": "https://routerai.ru/api/v1", "apiKey": "${ROUTERAI_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 }, { "model": "z-ai/glm-5.3", "displayName": "GLM 5.3 [RouterAI]", "baseUrl": "https://routerai.ru/api/v1", "apiKey": "${ROUTERAI_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 }, { "model": "anthropic/claude-sonnet-5.5", "displayName": "Sonnet 5.5 [RouterAI]", "baseUrl": "https://routerai.ru/api/v1", "apiKey": "${ROUTERAI_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 }, { "model": "openai/gpt-6.1-terra", "displayName": "GPT-6.1 Terra [RouterAI]", "baseUrl": "https://routerai.ru/api/v1", "apiKey": "${ROUTERAI_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 16384 } ] } ``` Что значат поля (по [документации Factory](https://docs.factory.com/model-independence/byok)): * `model` — id модели, который уходит в запрос. Берите его из [каталога RouterAI](/models) без изменений. * `displayName` — название в списке моделей. * `baseUrl` — для Chat Completions это `https://routerai.ru/api/v1`. * `apiKey` — поддерживает ссылки `${VAR_NAME}`: Droid читает значение из переменной окружения, поэтому ключ не попадает в файл. Не вписывайте в `settings.json` настоящий ключ, если файл хранится в репозитории или синхронизируется. * `provider` — обязательное поле, тип API. * `maxOutputTokens` — максимум токенов в ответе. Значение 16384 взято из примера в документации Factory; подберите своё под модель. Droid отслеживает изменения файла сам, перезапускать его не нужно. ### Anthropic Messages API для моделей Claude Для моделей `anthropic/*` в Factory есть провайдер `anthropic` (Anthropic Messages API). Базовый адрес RouterAI для него — `https://routerai.ru/api` без `/v1`: клиент сам добавляет `/v1/messages`. В официальном примере Factory для Anthropic указан адрес без `/v1` (`https://api.anthropic.com`). ```json { "model": "anthropic/claude-sonnet-5.5", "displayName": "Sonnet 5.5 [RouterAI, Messages]", "baseUrl": "https://routerai.ru/api", "apiKey": "${ROUTERAI_API_KEY}", "provider": "anthropic", "maxOutputTokens": 16384 } ``` Эндпоинт `https://routerai.ru/api/v1/messages` мы проверили запросом curl: он отвечает. Запустить именно эту связку внутри Droid не удалось, потому что для старта агента нужен вход в Factory. Если сомневаетесь, начните с варианта `generic-chat-completion-api`: он работает для всех моделей, включая Claude. ### OpenAI Responses API Провайдер `openai` в Factory использует OpenAI Responses API, и в документации он рекомендован для новейших моделей OpenAI. RouterAI отвечает и на `https://routerai.ru/api/v1/responses` (проверено curl на `openai/gpt-6.1-terra`), поэтому для GPT можно указать `"provider": "openai"` с тем же `baseUrl` `https://routerai.ru/api/v1`. Как и в предыдущем случае, внутри Droid этот вариант не запускали. В документации Factory допустимы четыре значения `provider`: `anthropic`, `openai`, `generic-chat-completion-api` и `bedrock-converse`. Любое другое даёт ошибку «Invalid provider». ## Выбор модели Модели, добавленные в `customModels`, появляются в `/model` в разделе **Custom Models** под значением `displayName`. Выберите нужную стрелками и подтвердите выбор. Идентификаторы проверены по [каталогу RouterAI](/models) на момент написания; цены и актуальный список смотрите там же. | Модель | Для чего | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `anthropic/claude-sonnet-5.5` | Основная модель для кода: фичи, отладка, рефакторинг среднего размера | | `openai/gpt-6.1-terra` | Альтернатива Claude от OpenAI для тех же задач; обзор версий в статье [GPT-6.1 Terra и Sol](/pages/gpt-6-1-terra-sol-routerai) | | `deepseek/deepseek-v4.1-flash` | Дешёвые массовые правки, переименования, быстрые ответы | | `z-ai/glm-5.3` | Альтернатива для кода и агентных задач; цену сравните в каталоге | Factory предупреждает: полностью протестированы только модели Anthropic и OpenAI через их официальные API, а работу остальных моделей «из коробки» компания не гарантирует. Модели меньше 30 млрд параметров заметно хуже справляются с агентными задачами. ## Проверка подключения Сначала убедитесь, что ключ и модель работают, независимо от Droid: ```bash curl https://routerai.ru/api/v1/chat/completions \ -H "Authorization: Bearer $ROUTERAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek/deepseek-v4.1-flash", "messages": [{"role": "user", "content": "ok?"}]}' ``` Ответ с кодом 200 и полем `choices` означает, что ключ принят. После этого: 1. Запустите `droid` в той же сессии терминала, где экспортирована `ROUTERAI_API_KEY`. 2. Выполните `/model` и найдите свои модели в разделе **Custom Models**. 3. Выберите модель и дайте агенту небольшую задачу, например «Объясни одной фразой, что делает этот проект». 4. Команда `/cost` покажет разбивку расходов по сессии. ## Ограничения * **Нужен вход в Factory.** При первом запуске Droid CLI v1.3.0 требует войти в аккаунт Factory (экран выше), без этого интерфейс не открывается. Для запуска в CI и скриптах документация предлагает ключ Factory в переменной `FACTORY_API_KEY` (создаётся в настройках на app.factory.ai). Работает ли BYOK без платной подписки и какие лимиты действуют на бесплатном тарифе, мы не проверяли: перед выпуском сверьтесь с актуальной страницей [тарифов Factory](https://docs.factory.com/pricing). Там сказано, что BYOK бесплатен в пределах квоты на тарифах Individual, а сверх неё тарифицируется по вашему плану. * **Личные модели видны только локально.** Custom Models доступны в Droid CLI и десктопном приложении, которые читают локальный `settings.json`. В веб-версии и мобильной версии Factory их нет. * **Ограничения организации.** Администратор Enterprise может отключить пользовательские модели (`allowCustomModels: false`) или разрешить подключение только к утверждённым адресам (`allowedBaseUrls`). Тогда `https://routerai.ru/api/v1` придётся внести в список разрешённых адресов. Подробнее: [Enterprise Controls](https://docs.factory.com/enterprise/hierarchical-settings-and-org-control). ## Решение проблем ### Модель не появляется в списке Проверьте синтаксис JSON в `~/.factory/settings.json` (лишняя или недостающая запятая) и наличие обязательных полей: `model`, `provider`, а также `baseUrl`, пока нет блока `bedrock`. ### Ошибка «Invalid provider» `provider` должен совпадать с одним из значений ровно: `anthropic`, `openai`, `generic-chat-completion-api`, `bedrock-converse`. Проверьте опечатки и регистр. ### 401 Unauthorized Ключ не передан или неверный. Droid подставляет значение из переменной окружения, поэтому она должна быть экспортирована в том терминале, откуда запущен `droid` (`echo $ROUTERAI_API_KEY`). Если ссылку `${ROUTERAI_API_KEY}` заменить настоящим ключом, убедитесь, что он скопирован из [личного кабинета](/settings/keys) целиком. ### 404 Not Found Обычно ошибка в базовом адресе. Для `generic-chat-completion-api` и `openai` нужен `https://routerai.ru/api/v1`, для `anthropic` — `https://routerai.ru/api` без `/v1`. ### 402 Payment Required Недостаточно средств на балансе. Пополните его в разделе [Биллинг](/settings/billing). ## Что дальше * [Каталог моделей](/models) — подберите модель под задачу * [Аутентификация](/docs/guides/overview/authentication) — управление API-ключами * [Вайб-кодинг в Crush](/pages/vibe-coding-crush) и [Вайб-кодинг в Codex](/pages/vibe-coding-codex) — другие CLI-агенты через RouterAI * [Custom Models (BYOK) в документации Factory](https://docs.factory.com/model-independence/byok)