Factory Droid + JoinGonka Gateway: BYOK na modelach sieci Gonka

Krok 1: zainstaluj Droid. Oficjalne metody z dokumentacji 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

Skrypt umieszcza plik binarny w ~/.local/bin i podpowiada, jak dodać ten katalog do PATH; w Linuksie dokumentacja prosi o doinstalowanie pakietu xdg-utils. Weryfikacja — droid --version.

Krok 2: zdobądź klucz. Zarejestruj się na gate.joingonka.ai/register, potwierdź adres i utwórz klucz z prefiksem jg- w sekcji «Klucze API». Jeden klucz i jedno saldo działają dla wszystkich modeli w sieci.

Krok 3: uruchom instalator.

npx @joingonka/setup --tool droid

Instalator zapyta o klucz — nie przekazuje się go w argumentach wiersza poleceń, żeby nie trafił do historii powłoki — i zrobi cztery rzeczy:

• dopisze do tablicy customModels w pliku ~/.factory/settings.json (w Windows — %USERPROFILE%\.factory\settings.json) po jednym wpisie dla każdego modelu w sieci: adres bramy, typ dostawcy generic-chat-completion-api, klucz jawnym tekstem, prawdziwe okno kontekstu i limit odpowiedzi; plik otrzyma uprawnienia 600;
• ustawi model domyślny — sessionDefaultSettings.model — na DeepSeek V4 Flash, ale tylko jeśli nie jest wybrany lub wskazuje na model, który zniknął z sieci. Modelu z katalogu Factory ani cudzego wpisu BYOK nie przechwytuje, a jedynie podpowiada, jak się przełączyć;
• zachowa kopię poprzedniego pliku, a cudze wpisy w customModels, pozostałe ustawienia i komentarze pozostawi bez zmian; pliku, którego nie da się sparsować, nie nadpisze, tylko powie, co poprawić;
• na końcu wyśle prawdziwe zapytanie do bramy i wprost powie, czy klucz, adres i model zostały przyjęte.

Inny model domyślny ustawia flaga --model ze skrótami deepseek, glm lub minimax — jawnie wskazany model jest zapisywany zawsze. Dla dotfiles i serwerów jest tryb bez pytań, w którym klucz pochodzi ze zmiennej środowiskowej:

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

Nie trzeba restartować Droid: zmiany w settings.json zauważa sam. Wiersz ! Could not verify right now z odpowiedzią 429 na końcu oznacza zajęty model, a nie błąd konfiguracji — konfiguracja jest już zapisana.

Wszystko, co robi instalator, można napisać ręcznie. Ustawienia użytkownika Droid są przechowywane w ~/.factory/settings.json; jeśli plik nie istnieje, Droid tworzy go przy pierwszym uruchomieniu. Dla sieci Gonka potrzebne są tablica customModels i model domyślny:

{
  "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"
  }
}

Model domyślny jest przechowywany w sessionDefaultSettings.model i odwołuje się do wpisu przez jego id. Dokumentacja Factory wspomina jeszcze klucz model w katalogu głównym pliku, ale w naszym przebiegu droid exec bez flagi -m brał model właśnie z sessionDefaultSettings — i po zmianie wartości również.

Klucz leży w pliku otwartym tekstem: zabezpiecz plik poleceniem chmod 600 ~/.factory/settings.json i nie przenoś wpisów z kluczem do .factory/settings.json projektu — ten zwykle trafia do repozytorium. A jeśli po uruchomieniu Droid plik wygląda inaczej, to normalne: zapisując dowolne ustawienie, Droid przepisuje plik w całości — porządkuje klucze, dodaje wpisom pole index i nie zachowuje komentarzy. Prawa 600 przy tym zostają, a instalator takie wpisy spokojnie aktualizuje.

Swoje wpisy Droid pokazuje osobno od katalogu: zgodnie z dokumentacją w trybie interaktywnym komenda /model wyświetla je w sekcji Custom models, a Ctrl+N przełącza modele bezpośrednio w polu wprowadzania. W trybie jednorazowym model określa flaga -m z wartością z pola id, ukośniki zapisuje się tak, jak są: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Pomylisz nazwę — Droid odpowie Invalid model i wypisze wszystkie modele, które widzi, w tym swoje w postaci custom:… (display name): przy okazji widać, że wpisy się załadowały. Nazwa w stylu dokumentacji Factory, z podpisu i numeru (custom:DeepSeek-V4-Flash-(Gonka)-0), przy jawnym id nie zadziała — w naszym przebiegu dała ten sam Invalid model.

Co wymaga konta Factory. Własne modele zdejmują kwestię opłaty za tokeny, ale nie logowania do samego produktu. Oto co pokazał przebieg Droid 0.225.1 bez logowania do konta:

Aby pracować w interfejsie, załóż konto Factory i zaloguj się przez przeglądarkę — opcja Login lub komenda /login; na maszynie bez przeglądarki dokumentacja proponuje klucz z ustawień konta w zmiennej FACTORY_API_KEY. Działanie droid exec bez logowania jest wygodne do wypróbowania, ale oficjalnie nieopisane — nie licz na nie w CI. Według strony cennika Factory BYOK wchodzi we wszystkie plany indywidualne z darmowym limitem, a powyżej limitu korzystanie z BYOK jest rozliczane zgodnie z warunkami planu; aktualne warunki — na factory.ai/pricing. Tokeny modeli sieci są przy tym opłacane osobno — z salda JoinGonka.

Który model wybrać. Cena wszystkich modeli sieci jest taka sama, więc wybór dotyczy zachowania. Oto jak wypadły w naszym przebiegu droid exec na jednym zadaniu — przeczytać plik i znaleźć błąd:

Flaga -r (poziom rozumowania) do modeli BYOK, zgodnie z dokumentacją Factory, nie ma zastosowania. Dlaczego domyślnie wybrano DeepSeek V4 Flash, omówiono w przeglądzie modelu.

Umieść w pustym katalogu plik calc.py z oczywistym błędem — na przykład polem prostokąta, w którym boki są dodawane zamiast mnożone — i poproś Droid, żeby go znalazł:

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

Bez flag droid exec działa w trybie tylko do odczytu: pliki można przeglądać, ale nie można ich zmieniać. Agent sam wywoła narzędzie odczytu i odpowie konkretnie, wskazując błędne wyrażenie. Z flagą -o json odpowiedź przychodzi jako jeden obiekt, który wygodnie parsować skryptem (wynik skrócony):

{"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}}

Pole factory_credits: 0 potwierdza, że praca odbywała się na Twoim modelu, a nie na kredytach Factory. Aby agent mógł edytować pliki, dodaj poziom autonomii: droid exec --auto low "Fix the bug in calc.py and change nothing else." — w naszym przebiegu DeepSeek V4 Flash przeczytała plik, zamieniła dodawanie na mnożenie i sama uruchomiła skrypt, żeby sprawdzić, czy wyświetla się 12.

Trzecia weryfikacja — od strony bramy: w panelu w sekcji „Wykorzystanie” zapytanie pojawi się w podziale „Według modeli”, a w bloku „Według kluczy” zaktualizuje się czas ostatniego zapytania.

Jeśli coś poszło nie tak, pamiętaj o osobliwości Droid: w konsoli droid exec wyświetla tylko Error during droid execution: Exec failed (w JSON — "result":"Exec failed"), a prawdziwa przyczyna pozostaje w dzienniku. Można ją wyciągnąć jedną komendą:

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

Narzędzie agentskie zużywa tokeny inaczej niż czat: do każdej Twojej frazy Droid dodaje systemowy prompt, opisy narzędzi oraz migawkę katalogu roboczego, a zadanie zajmuje kilka tur. W naszym teście każda tura generowała około 9,5 tysiąca tokenów wejściowych jeszcze przed Twoim pytaniem: zadanie „przeczytaj plik i znajdź błąd” zajęło dwie tury i około 19 tysięcy tokenów, „napraw i sprawdź” — cztery tury i około 44 tysiące. Dlatego cena za token ma tutaj kluczowe znaczenie.

Poprzez JoinGonka Gateway tokeny kosztują $0.0069 za milion na wejściu i $0.021 za milion na wyjściu — cena jest taka sama dla wszystkich modeli sieci i jest pobierana na tej stronie z aktywnego źródła.

Szacunki w prawej kolumnie są oparte na cenach z września 2026. Dla porównania — w jaki sposób można płacić za modele w Droid:

Komenda /cost w interfejsie Droid pokazuje statystyki sesji, a dokładne zużycie i saldo dla modeli BYOK — w panelu bramki, w sekcjach „Użycie” (Usage) i „Rozliczenia” (Billing). Załóż dla Droid osobny klucz — jego ruch będzie widoczny w osobnej linii.

Autonomia. W trybie jednorazowym Droid domyślnie tylko czyta, a uprawnienia rozszerzają poziomy: --auto low — edycja plików, --auto medium — dodatkowo instalacja zależności, budowanie, testy i lokalne commity, --auto high — aż po push i deploy. Flaga --skip-permissions-unsafe znosi wszystkie sprawdzenia — tylko dla jednorazowych kontenerów. W trybie interaktywnym poziom przełącza Ctrl+L, a początkowy ustawia sessionDefaultSettings.autonomyLevel; domyślnie jest tam off — wszystko z potwierdzeniem.

Podpis w commitach. Ustawienie includeCoAuthoredByDroid jest domyślnie włączone: Droid dodaje do wiadomości commitów wiersz współautorstwa. Jeśli nie jest potrzebny, wpisz "includeCoAuthoredByDroid": false w settings.json.

Gdzie przechowywane są sesje. Po zalogowaniu na konto Droid domyślnie mirroruje sesje CLI do wersji webowej Factory — odpowiada za to cloudSessionSync. Klucze BYOK, zgodnie z dokumentacją, pozostają lokalne; jeśli i korespondencja ma pozostać na maszynie, ustaw "cloudSessionSync": false. Brama ze swojej strony nie przechowuje treści promptów i odpowiedzi — w statystykach pozostają tylko agregaty zużycia.

Aktualizacje. Instalacja skryptem aktualizuje się sama; wersję można przypiąć zmienną FACTORY_DROID_AUTO_UPDATE_ENABLED=false lub komendą droid update --version <version>; buildy z npm same się nie aktualizują. Po aktualizacji jednym droid exec sprawdź, czy modele sieci są na miejscu.

Obrazki. Modele sieci są tekstowe; do zrzutów ekranu trzymaj obok wpis z modelem, który umie widzieć, u innego dostawcy.

Jeśli praca bez konta dostawcy jest kluczowa. Te same modele sieci podłączają się do otwartych agentów terminalowych, które nie wymagają logowania — na przykład do OpenCode tym samym instalatorem, z flagą --tool opencode.