Factory Droid + JoinGonka Gateway: BYOK mit Gonka Netzwerkmodellen

Schritt 1: Droid installieren. Die offiziellen Wege aus der Factory-Dokumentation:

# 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

Das Skript legt das Binary in ~/.local/bin ab und zeigt an, wie man das Verzeichnis zu PATH hinzufügt; unter Linux bittet die Dokumentation darum, zusätzlich das Paket xdg-utils zu installieren. Prüfung — droid --version.

Schritt 2: Schlüssel holen. Registriere dich auf gate.joingonka.ai/register, bestätige deine Adresse und erstelle im Bereich «API-Schlüssel» einen Schlüssel mit dem Präfix jg-. Ein Schlüssel und ein Guthaben gelten für alle Modelle im Netzwerk.

Schritt 3: Installer starten.

npx @joingonka/setup --tool droid

Der Installer fragt nach dem Schlüssel — der wird nicht als Kommandozeilenargument übergeben, damit er nicht in der Shell-Historie landet — und erledigt vier Dinge:

• Er hängt an das Array customModels in ~/.factory/settings.json (unter Windows — %USERPROFILE%\.factory\settings.json) je einen Eintrag für jedes Modell im Netzwerk: Gateway-Adresse, Provider-Typ generic-chat-completion-api, Schlüssel als Literal, echtes Kontextfenster und Antwort-Limit; die Datei erhält die Rechte 600;
• Er setzt das Standardmodell — sessionDefaultSettings.model — auf DeepSeek V4 Flash, aber nur, wenn kein Modell gewählt wurde oder die Auswahl auf ein Modell zeigt, das nicht mehr im Netzwerk ist. Ein Modell aus dem Factory-Katalog oder einen fremden BYOK-Eintrag überschreibt er nicht, sondern zeigt nur, wie man umschaltet;
• Er speichert eine Kopie der vorherigen Datei, lässt fremde Einträge in customModels, übrige Einstellungen und Kommentare unangetastet; eine Datei, die sich nicht parsen lässt, wird nicht überschrieben, stattdessen wird gesagt, was zu korrigieren ist;
• Zum Schluss sendet er eine echte Anfrage an das Gateway und sagt klar, ob Schlüssel, Adresse und Modell akzeptiert wurden.

Ein anderes Standardmodell legt das Flag --model mit der Kurzform deepseek, glm oder minimax fest — ein explizit angegebenes Modell wird immer geschrieben. Für Dotfiles und Server gibt es einen Modus ohne Rückfragen, in dem der Schlüssel aus einer Umgebungsvariable kommt:

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

Droid muss nicht neu gestartet werden: Änderungen an settings.json bemerkt es von selbst. Die Zeile ! Could not verify right now mit Antwort 429 am Ende bedeutet ein belegtes Modell, keinen Konfigurationsfehler — die Konfiguration ist bereits geschrieben.

Alles, was der Installer macht, lässt sich auch manuell erledigen. Die Benutzereinstellungen von Droid liegen in ~/.factory/settings.json; existiert die Datei nicht, legt Droid sie beim ersten Start an. Für das Gonka-Netzwerk braucht es das Array customModels und ein Standardmodell:

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

Das Standardmodell liegt in sessionDefaultSettings.model und verweist über seine id auf den Eintrag. Die Factory-Dokumentation erwähnt außerdem den Schlüssel model im Wurzelverzeichnis der Datei, doch in unserem Durchlauf bezog droid exec ohne das Flag -m das Modell genau aus sessionDefaultSettings — und das blieb auch nach einer Wertänderung so.

Der Schlüssel steht im Klartext in der Datei: Schützen Sie die Datei mit chmod 600 ~/.factory/settings.json und übernehmen Sie Einträge mit Schlüssel nicht in .factory/settings.json des Projekts — die landet in der Regel im Repository. Und falls die Datei nach dem Start von Droid anders aussieht, ist das normal: Beim Speichern irgendeiner Einstellung schreibt Droid die Datei komplett neu — ordnet die Schlüssel, ergänzt bei Einträgen das Feld index und behält keine Kommentare. Die Rechte 600 bleiben dabei erhalten, und der Installer aktualisiert solche Einträge problemlos.

Droid zeigt eigene Einträge getrennt vom Katalog an: Laut Dokumentation listet der Befehl /model sie im interaktiven Modus im Bereich Custom models auf, und Ctrl+N wechselt die Modelle direkt im Eingabefeld durch. Im Einmalmodus wird das Modell über das Flag -m mit dem Wert aus dem Feld id festgelegt, Schrägstriche werden unverändert geschrieben: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Bei einem Tippfehler im Namen antwortet Droid mit Invalid model und listet alle Modelle auf, die es sieht – einschließlich der eigenen in der Form custom:… (display name): so sieht man gleich, dass die Einträge geladen wurden. Ein Name im Stil der Factory-Dokumentation, aus Bezeichnung und Nummer (custom:DeepSeek-V4-Flash-(Gonka)-0), funktioniert bei explizitem id nicht – in unserem Durchlauf lieferte er dasselbe Invalid model.

Wofür ein Factory-Konto nötig ist. Eigene Modelle lösen die Frage der Token-Bezahlung, aber nicht die Anmeldung im Produkt selbst. Das zeigte unser Durchlauf mit Droid 0.225.1 ohne Konto-Login:

Für die Arbeit in der Oberfläche lege ein Factory-Konto an und melde dich über den Browser an – Menüpunkt Login oder Befehl /login; auf einer Maschine ohne Browser empfiehlt die Dokumentation einen Schlüssel aus den Kontoeinstellungen in der Variable FACTORY_API_KEY. Der Betrieb von droid exec ohne Login ist praktisch zum Ausprobieren, aber offiziell nicht dokumentiert – verlass dich in CI nicht darauf. Laut Factory-Tarifseite ist BYOK in allen individuellen Plänen mit kostenlosem Limit enthalten, und über das Limit hinaus wird die BYOK-Nutzung zu den Bedingungen des Plans abgerechnet; aktuelle Konditionen unter factory.ai/pricing. Die Tokens der Netzwerk-Modelle werden dabei separat abgerechnet – vom JoinGonka-Guthaben.

Welches Modell wählen. Der Preis ist bei allen Netzwerk-Modellen gleich, die Wahl dreht sich also ums Verhalten. So schnitten sie in unserem Durchlauf mit droid exec bei einer Aufgabe ab – eine Datei lesen und einen Fehler finden:

Das Flag -r (Reasoning-Level) wird laut Factory-Dokumentation auf BYOK-Modelle nicht angewendet. Warum standardmäßig DeepSeek V4 Flash gewählt wird, ist im Modell-Überblick erklärt.

Legen Sie in ein leeres Verzeichnis die Datei calc.py mit einem offensichtlichen Fehler — zum Beispiel die Fläche eines Rechtecks, bei der die Seiten addiert statt multipliziert werden — und bitten Sie Droid, ihn zu finden:

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

Ohne Flags arbeitet droid exec im Nur-Lese-Modus: Dateien ansehen ja, ändern nein. Der Agent ruft selbst das Lesewerkzeug auf und antwortet sachlich, mit Angabe des fehlerhaften Ausdrucks. Mit dem Flag -o json kommt die Antwort als ein einzelnes Objekt, das sich bequem per Skript auswerten lässt (Ausgabe gekürzt):

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

Das Feld factory_credits: 0 bestätigt, dass die Arbeit auf Ihrem Modell lief und nicht über Factory-Credits. Damit der Agent Dateien bearbeiten darf, ergänzen Sie eine Autonomiestufe: droid exec --auto low "Fix the bug in calc.py and change nothing else." — in unserem Durchlauf hat DeepSeek V4 Flash die Datei gelesen, die Addition durch eine Multiplikation ersetzt und das Skript selbst ausgeführt, um zu prüfen, dass 12 ausgegeben wird.

Die dritte Prüfung erfolgt seitens des Gateways: Im Konto erscheint die Anfrage im Bereich „Nutzung" in der Aufschlüsselung „Nach Modellen", und im Block „Nach Schlüsseln" wird der Zeitpunkt der letzten Anfrage aktualisiert.

Falls etwas schiefgelaufen ist, beachten Sie die Besonderheit von Droid: In der Konsole gibt droid exec nur Error during droid execution: Exec failed aus (im JSON — "result":"Exec failed"), während die eigentliche Ursache im Log bleibt. Sie lässt sich mit einem einzigen Befehl herausziehen:

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

Ein Agenten-Tool verbraucht Token anders als ein Chat: Droid fügt jedem Ihrer Sätze einen System-Prompt, Tool-Beschreibungen und einen Schnappschuss des Arbeitsverzeichnisses hinzu, und die Aufgabe erfordert mehrere Schritte. In unserem Durchlauf verursachte jeder Schritt etwa 9,5 Tausend Eingabe-Token noch vor Ihrer eigentlichen Frage: Die Aufgabe „Datei lesen und Fehler finden“ beanspruchte zwei Schritte und etwa 19 Tausend Token, „korrigieren und prüfen“ vier Schritte und etwa 44 Tausend. Daher ist der Preis pro Token hier entscheidend.

Über das JoinGonka Gateway kosten Token $0.0069 pro Million beim Input und $0.021 pro Million beim Output — der Preis ist für alle Netzwerkmodelle gleich und wird auf dieser Seite aus einer Live-Quelle geladen.

Die Schätzungen in der rechten Spalte basieren auf den Preisen vom September 2026. Zum Vergleich — wie man generell für Modelle in Droid bezahlen kann:

Der Befehl /cost in der Droid-Oberfläche zeigt die Sitzungsstatistik an, der genaue Verbrauch und das Guthaben für BYOK-Modelle sind im Gateway-Dashboard in den Bereichen „Nutzung“ und „Abrechnung“ einsehbar. Erstellen Sie für Droid einen separaten Schlüssel — dessen Datenverkehr wird als separate Zeile angezeigt.

Autonomie. Im Einmalmodus liest Droid standardmäßig nur; die Rechte erweitern die Stufen: --auto low — Dateiänderungen, --auto medium — zusätzlich Installation von Abhängigkeiten, Build, Tests und lokale Commits, --auto high — bis hin zu Push und Deploy. Das Flag --skip-permissions-unsafe hebt alle Prüfungen auf — nur für Einweg-Container. Im interaktiven Modus schaltet Ctrl+L die Stufe um, und die Startstufe setzt sessionDefaultSettings.autonomyLevel; standardmäßig steht dort off — alles mit Bestätigung.

Signatur in Commits. Die Einstellung includeCoAuthoredByDroid ist standardmäßig aktiviert: Droid fügt den Commit-Nachrichten eine Co-Autoren-Zeile hinzu. Wenn sie nicht gewünscht ist, schreiben Sie "includeCoAuthoredByDroid": false in settings.json.

Wo Sitzungen gespeichert werden. Nach der Anmeldung am Konto spiegelt Droid die CLI-Sitzungen standardmäßig in die Web-Version von Factory — dafür ist cloudSessionSync zuständig. BYOK-Schlüssel bleiben laut Dokumentation lokal; wenn auch die Korrespondenz auf dem Rechner bleiben soll, setzen Sie "cloudSessionSync": false. Das Gateway seinerseits speichert keine Prompt- und Antwortinhalte — in der Statistik bleiben nur Verbrauchsaggregate.

Updates. Die Skript-Installation aktualisiert sich selbst; die Version lässt sich über die Variable FACTORY_DROID_AUTO_UPDATE_ENABLED=false oder den Befehl droid update --version <version> festlegen; npm-Builds aktualisieren sich nicht selbst. Prüfen Sie nach dem Update mit einem droid exec, dass die Modelle des Netzwerks vorhanden sind.

Bilder. Die Modelle des Netzwerks sind textbasiert; für Screenshots halten Sie einen Eintrag mit einem vision-fähigen Modell bei einem anderen Anbieter bereit.

Wenn die Arbeit ohne Vendor-Konto entscheidend ist. Dieselben Netzwerk-Modelle lassen sich an offene Terminal-Agenten anbinden, die keine Anmeldung benötigen — etwa an OpenCode mit demselben Installer und dem Flag --tool opencode.