Factory Droid + JoinGonka Gateway: BYOK на моделях сети Gonka

Шаг 1: поставить Droid. Официальные способы из документации Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

Скрипт кладёт бинарник в ~/.local/bin и подсказывает, как добавить каталог в PATH; на Linux документация просит поставить ещё пакет xdg-utils. Проверка — droid --version.

Шаг 2: получить ключ. Зарегистрируйтесь на gate.joingonka.ai/register, подтвердите адрес и создайте ключ с префиксом jg- в разделе «API-ключи». Один ключ и один баланс действуют для всех моделей сети.

Шаг 3: запустить установщик.

npx @joingonka/setup --tool droid

Установщик спросит ключ — в аргументах командной строки он не передаётся, чтобы не осесть в истории оболочки, — и сделает четыре вещи:

• допишет в массив customModels файла ~/.factory/settings.json (на Windows — %USERPROFILE%\.factory\settings.json) по записи на каждую модель сети: адрес шлюза, тип провайдера generic-chat-completion-api, ключ литералом, настоящие окно контекста и потолок ответа; файл получит права 600;
• поставит модель по умолчанию — sessionDefaultSettings.model — на DeepSeek V4 Flash, но только если она не выбрана или указывает на модель, ушедшую из сети. Модель из каталога Factory или чужую запись BYOK он не перехватывает, а подсказывает, как переключиться;
• сохранит копию прежнего файла, а чужие записи в customModels, остальные настройки и комментарии оставит как были; файл, который не удаётся разобрать, не перезапишет, а скажет, что исправить;
• в конце отправит живой запрос на шлюз и прямо скажет, приняты ли ключ, адрес и модель.

Другую модель по умолчанию задаёт флаг --model с сокращением deepseek, glm или minimax — явно указанная модель записывается всегда. Для дотфайлов и серверов есть режим без вопросов, ключ в нём берётся из переменной окружения:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

Перезапускать Droid не нужно: изменения в settings.json он замечает сам. Строка ! Could not verify right now с ответом 429 в конце означает занятую модель, а не ошибку настройки — конфигурация уже записана.

Всё, что делает установщик, можно написать руками. Пользовательские настройки Droid хранятся в ~/.factory/settings.json; если файла нет, Droid создаёт его при первом запуске. Для сети Gonka нужны массив customModels и модель по умолчанию:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

Модель по умолчанию хранится в sessionDefaultSettings.model и ссылается на запись по её id. Документация Factory упоминает ещё ключ model в корне файла, но в нашем прогоне droid exec без флага -m брал модель именно из sessionDefaultSettings — и после смены значения тоже.

Ключ лежит в файле открытым текстом: закройте файл командой chmod 600 ~/.factory/settings.json и не переносите записи с ключом в .factory/settings.json проекта — он обычно попадает в репозиторий. А если после запуска Droid файл выглядит иначе, это нормально: сохраняя любую настройку, Droid переписывает файл целиком — упорядочивает ключи, добавляет записям поле index и не сохраняет комментарии. Права 600 при этом остаются, а установщик такие записи спокойно обновляет.

Свои записи Droid показывает отдельно от каталога: по документации, в интерактивном режиме команда /model выводит их в разделе Custom models, а Ctrl+N перебирает модели прямо в поле ввода. В разовом режиме модель задаёт флаг -m со значением из поля id, косые черты пишутся как есть: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Ошибётесь в имени — Droid ответит Invalid model и перечислит все модели, которые видит, включая свои в виде custom:… (display name): заодно видно, что записи загрузились. Имя в стиле документации Factory, из подписи и номера (custom:DeepSeek-V4-Flash-(Gonka)-0), при явном id не сработает — в нашем прогоне оно дало тот же Invalid model.

Что требует аккаунта Factory. Свои модели снимают вопрос оплаты токенов, но не входа в сам продукт. Вот что показал прогон Droid 0.225.1 без входа в аккаунт:

Для работы в интерфейсе заведите аккаунт Factory и войдите через браузер — пункт Login или команда /login; на машине без браузера документация предлагает ключ из настроек аккаунта в переменной FACTORY_API_KEY. Работа droid exec без входа удобна для пробы, но официально не описана — в CI на неё не закладывайтесь. По тарифной странице Factory, BYOK входит во все индивидуальные планы с бесплатным лимитом, а сверх лимита использование BYOK тарифицируется по условиям плана; актуальные условия — на factory.ai/pricing. Токены моделей сети при этом оплачиваются отдельно — с баланса JoinGonka.

Какую модель выбрать. Цена у всех моделей сети одна, поэтому выбор — про поведение. Так они отработали в нашем прогоне droid exec на одной задаче — прочитать файл и найти ошибку:

Флаг -r (уровень рассуждений) к моделям BYOK, по документации Factory, не применяется. Почему по умолчанию выбрана DeepSeek V4 Flash, разобрано в обзоре модели.

Положите в пустой каталог файл calc.py с очевидной ошибкой — например, площадь прямоугольника, где стороны складываются вместо умножения, — и попросите Droid её найти:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Без флагов droid exec работает в режиме только для чтения: смотреть файлы можно, менять — нет. Агент сам вызовет инструмент чтения и ответит по существу, с указанием ошибочного выражения. С флагом -o json ответ приходит одним объектом, который удобно разбирать скриптом (вывод сокращён):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

Поле factory_credits: 0 подтверждает, что работа шла на вашей модели, а не в кредитах Factory. Чтобы агент мог править файлы, добавьте уровень автономности: droid exec --auto low "Fix the bug in calc.py and change nothing else." — в нашем прогоне DeepSeek V4 Flash прочитала файл, заменила сложение на умножение и сама запустила скрипт, чтобы убедиться, что выводится 12.

Третья проверка — со стороны шлюза: в кабинете в разделе «Использование» запрос появится в разбивке «По моделям», а в блоке «По ключам» обновится время последнего запроса.

Если что-то пошло не так, учтите особенность Droid: в консоли droid exec печатает только Error during droid execution: Exec failed (в JSON — "result":"Exec failed"), а настоящая причина остаётся в журнале. Достать её можно одной командой:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

Агентный инструмент тратит токены иначе, чем чат: к каждой вашей фразе Droid добавляет системный промпт, описания инструментов и снимок рабочего каталога, а задача занимает несколько ходов. В нашем прогоне каждый ход нёс около 9,5 тысячи входных токенов ещё до вашего вопроса: задача «прочитать файл и найти ошибку» заняла два хода и около 19 тысяч токенов, «исправить и проверить» — четыре хода и около 44 тысяч. Поэтому цена за токен здесь решает.

Через JoinGonka Gateway токены стоят $0.0069 за миллион на входе и $0.021 за миллион на выходе — цена одинакова для всех моделей сети и подставляется на этой странице из живого источника.

Оценки в правой колонке — по ценам на сентябрь 2026. Для сравнения — как вообще можно платить за модели в Droid:

Команда /cost в интерфейсе Droid показывает статистику сессии, а точный расход и остаток для моделей BYOK — в кабинете шлюза, в разделах «Использование» и «Биллинг». Заведите для Droid отдельный ключ — его трафик будет виден отдельной строкой.

Автономность. В разовом режиме Droid по умолчанию только читает, права расширяют уровни: --auto low — правки файлов, --auto medium — ещё установка зависимостей, сборка, тесты и локальные коммиты, --auto high — вплоть до push и деплоя. Флаг --skip-permissions-unsafe снимает все проверки — только для одноразовых контейнеров. В интерактивном режиме уровень переключает Ctrl+L, а стартовый задаёт sessionDefaultSettings.autonomyLevel; по умолчанию там off — всё с подтверждением.

Подпись в коммитах. Настройка includeCoAuthoredByDroid по умолчанию включена: Droid добавляет в сообщения коммитов строку соавторства. Если она не нужна, впишите "includeCoAuthoredByDroid": false в settings.json.

Где хранятся сессии. После входа в аккаунт Droid по умолчанию зеркалирует сессии CLI в веб-версию Factory — за это отвечает cloudSessionSync. Ключи BYOK, по документации, остаются локальными; если и переписка должна оставаться на машине, поставьте "cloudSessionSync": false. Шлюз со своей стороны не хранит содержимое промптов и ответов — в статистике остаются только агрегаты расхода.

Обновления. Установка скриптом обновляется сама; зафиксировать версию можно переменной FACTORY_DROID_AUTO_UPDATE_ENABLED=false или командой droid update --version <version>; сборки из npm сами не обновляются. После обновления одним droid exec проверьте, что модели сети на месте.

Картинки. Модели сети текстовые; для скриншотов держите рядом запись с моделью, которая умеет зрение, у другого провайдера.

Если работа без аккаунта вендора принципиальна. Те же модели сети подключаются к открытым терминальным агентам, которым вход не нужен, — например, к OpenCode тем же установщиком, с флагом --tool opencode.