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.