Factory Droid + JoinGonka Gateway: BYOK sui modelli di rete Gonka

Passo 1: installare Droid. I metodi ufficiali dalla documentazione di 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

Lo script mette il binario in ~/.local/bin e ti dice come aggiungere la directory al PATH; su Linux la documentazione chiede di installare anche il pacchetto xdg-utils. Verifica — droid --version.

Passo 2: ottenere la chiave. Registrati su gate.joingonka.ai/register, conferma l'indirizzo e crea una chiave con prefisso jg- nella sezione «Chiavi API». Una sola chiave e un solo saldo valgono per tutti i modelli della rete.

Passo 3: avviare l'installer.

npx @joingonka/setup --tool droid

L'installer chiederà la chiave — non viene passata come argomento della riga di comando, per non finire nella cronologia della shell — e farà quattro cose:

• aggiungerà all'array customModels del file ~/.factory/settings.json (su Windows — %USERPROFILE%\.factory\settings.json) una voce per ogni modello della rete: indirizzo del gateway, tipo di provider generic-chat-completion-api, chiave in chiaro, finestra di contesto reale e limite massimo di risposta; il file riceverà i permessi 600;
• imposterà il modello predefinito — sessionDefaultSettings.model — su DeepSeek V4 Flash, ma solo se non è selezionato o punta a un modello uscito dalla rete. Non intercetta il modello dal catalogo Factory né una voce BYOK altrui, ma ti suggerisce come cambiare;
• salverà una copia del file precedente, lasciando invariate le voci altrui in customModels, le altre impostazioni e i commenti; un file che non riesce a interpretare non lo sovrascriverà, ma ti dirà cosa correggere;
• alla fine invierà una richiesta reale al gateway e ti dirà chiaramente se chiave, indirizzo e modello sono stati accettati.

Un altro modello predefinito si imposta con il flag --model e le abbreviazioni deepseek, glm o minimax — un modello indicato esplicitamente viene sempre scritto. Per i dotfile e i server c'è la modalità senza domande, in cui la chiave viene presa da una variabile d'ambiente:

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

Non serve riavviare Droid: nota da solo le modifiche a settings.json. La riga ! Could not verify right now con risposta 429 alla fine significa modello occupato, non un errore di configurazione — la configurazione è già stata scritta.

Tutto ciò che fa l'installer si può scrivere a mano. Le impostazioni utente di Droid sono salvate in ~/.factory/settings.json; se il file non esiste, Droid lo crea al primo avvio. Per la rete Gonka servono l'array customModels e un modello predefinito:

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

Il modello predefinito è salvato in sessionDefaultSettings.model e punta a una voce tramite il suo id. La documentazione di Factory cita anche una chiave model alla radice del file, ma nella nostra prova droid exec senza flag -m prendeva il modello proprio da sessionDefaultSettings — anche dopo averne cambiato il valore.

La chiave resta nel file in chiaro: proteggi il file con chmod 600 ~/.factory/settings.json e non spostare le voci con la chiave nel .factory/settings.json del progetto, perché di solito finisce nel repository. E se dopo l'avvio di Droid il file sembra diverso, è normale: ogni volta che salva un'impostazione Droid riscrive il file da zero — riordina le chiavi, aggiunge alle voci il campo index e non conserva i commenti. I permessi 600 restano, e l'installer aggiorna quelle voci senza problemi.

Droid mostra i propri modelli separatamente dal catalogo: secondo la documentazione, in modalità interattiva il comando /model li elenca nella sezione Custom models, mentre Ctrl+N permette di scorrere i modelli direttamente nel campo di input. In modalità one-shot il modello si specifica con il flag -m e un valore preso dal campo id, con le barre oblique scritte così come sono: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Se sbagli il nome, Droid risponde Invalid model ed elenca tutti i modelli che vede, inclusi i tuoi nel formato custom:… (display name): così vedi anche che i modelli sono stati caricati. Un nome nello stile della documentazione di Factory, composto da display name e numero (custom:DeepSeek-V4-Flash-(Gonka)-0), non funziona quando si specifica l'id — nella nostra prova ha restituito lo stesso Invalid model.

Cosa richiede un account Factory. I modelli personalizzati eliminano il problema del pagamento dei token, ma non dell'accesso al prodotto stesso. Ecco cosa ha mostrato la prova di Droid 0.225.1 senza effettuare il login:

Per lavorare nell'interfaccia, crea un account Factory e accedi tramite browser — la voce Login o il comando /login; su una macchina senza browser la documentazione suggerisce di usare una chiave dalle impostazioni dell'account nella variabile FACTORY_API_KEY. Usare droid exec senza login è comodo per provare, ma non è documentato ufficialmente — non farci affidamento in CI. Secondo la pagina dei piani di Factory, BYOK è incluso in tutti i piani individuali con un limite gratuito, e oltre il limite l'uso di BYOK viene tariffato secondo le condizioni del piano; le condizioni aggiornate sono su factory.ai/pricing. I token dei modelli della rete, in ogni caso, si pagano separatamente — dal saldo di JoinGonka.

Quale modello scegliere. Il prezzo è lo stesso per tutti i modelli della rete, quindi la scelta riguarda il comportamento. Ecco come si sono comportati nella nostra prova di droid exec su un unico task — leggere un file e trovare l'errore:

Il flag -r (livello di ragionamento) sui modelli BYOK, secondo la documentazione di Factory, non si applica. Il motivo per cui DeepSeek V4 Flash è scelto come predefinito è analizzato nella recensione del modello.

Metti in una cartella vuota il file calc.py con un errore evidente — ad esempio l'area di un rettangolo calcolata sommando i lati invece di moltiplicarli — e chiedi a Droid di trovarlo:

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

Senza flag droid exec funziona in modalità di sola lettura: puoi vedere i file, non modificarli. L'agente chiamerà da solo lo strumento di lettura e risponderà nel merito, indicando l'espressione errata. Con il flag -o json la risposta arriva come un unico oggetto, comodo da elaborare con uno script (output abbreviato):

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

Il campo factory_credits: 0 conferma che il lavoro è stato svolto sul tuo modello, non con i crediti di Factory. Per consentire all'agente di modificare i file, aggiungi un livello di autonomia: droid exec --auto low "Fix the bug in calc.py and change nothing else." — nella nostra prova DeepSeek V4 Flash ha letto il file, sostituito la somma con la moltiplicazione e avviato da sola lo script per verificare che l'output fosse 12.

Terzo controllo, dal lato gateway: nella console, nella sezione «Utilizzo», la richiesta comparirà nella ripartizione «Per modello», e nel blocco «Per chiave» si aggiornerà l'ora dell'ultima richiesta.

Se qualcosa non ha funzionato, tieni presente una particolarità di Droid: nella console droid exec stampa solo Error during droid execution: Exec failed (in JSON — "result":"Exec failed"), mentre la causa reale resta nel log. Puoi recuperarla con un solo comando:

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

Lo strumento agente consuma i token in modo diverso rispetto a una chat: per ogni tua frase, Droid aggiunge un prompt di sistema, le descrizioni degli strumenti e un'istantanea della directory di lavoro, e il compito richiede diversi passaggi. Nel nostro test, ogni passaggio conteneva circa 9.500 token in ingresso prima ancora della tua domanda: il compito "leggi il file e trova l'errore" ha richiesto due passaggi e circa 19.000 token, "correggi e verifica" quattro passaggi e circa 44.000. Pertanto, il prezzo per token qui è determinante.

Tramite JoinGonka Gateway, i token costano $0.0069 per milione in ingresso e $0.021 per milione in uscita: il prezzo è identico per tutti i modelli della rete e viene aggiornato in questa pagina da una fonte in tempo reale.

Le stime nella colonna di destra si basano sui prezzi di settembre 2026. Per confronto, ecco come si può pagare per i modelli in Droid:

Il comando /cost nell'interfaccia Droid mostra le statistiche della sessione, mentre il consumo esatto e il saldo residuo per i modelli BYOK sono visibili nel pannello del gateway, nelle sezioni «Utilizzo» e «Fatturazione». Crea una chiave separata per Droid: il suo traffico sarà visibile come riga distinta.

Autonomia. In modalità singola Droid di default legge soltanto; i livelli ampliano i permessi: --auto low — modifiche ai file, --auto medium — anche installazione di dipendenze, build, test e commit locali, --auto high — fino a push e deploy. Il flag --skip-permissions-unsafe rimuove tutti i controlli — solo per container usa e getta. In modalità interattiva il livello si cambia con Ctrl+L, mentre quello iniziale si imposta con sessionDefaultSettings.autonomyLevel; di default è off — tutto con conferma.

Firma nei commit. L'impostazione includeCoAuthoredByDroid è attiva di default: Droid aggiunge ai messaggi di commit una riga di co-autoria. Se non la vuoi, inserisci "includeCoAuthoredByDroid": false in settings.json.

Dove vengono salvate le sessioni. Dopo l'accesso all'account, Droid di default rispecchia le sessioni CLI nella versione web di Factory — se ne occupa cloudSessionSync. Le chiavi BYOK, secondo la documentazione, restano locali; se anche la conversazione deve restare sulla macchina, imposta "cloudSessionSync": false. Il gateway, da parte sua, non conserva il contenuto dei prompt e delle risposte — nelle statistiche restano solo i dati aggregati di consumo.

Aggiornamenti. L'installazione tramite script si aggiorna da sola; puoi bloccare la versione con la variabile FACTORY_DROID_AUTO_UPDATE_ENABLED=false o con il comando droid update --version <version>; le build da npm non si aggiornano da sole. Dopo l'aggiornamento, verifica con un solo droid exec che i modelli della rete siano al loro posto.

Immagini. I modelli della rete sono testuali; per gli screenshot tieni a portata di mano una voce con un modello che supporta la visione, presso un altro provider.

Se lavorare senza account del vendor è irrinunciabile. Gli stessi modelli della rete si collegano ad agenti terminali aperti, che non richiedono login — ad esempio a OpenCode con lo stesso installer, con il flag --tool opencode.