Goose + JoinGonka Gateway: il tuo provider e chiave nel keyring

Passo 1: installa Goose. I metodi ufficiali per la CLI dalla documentazione del progetto:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

La variabile CONFIGURE=false disattiva il wizard goose configure, che altrimenti lo script avvia subito dopo l'installazione: il provider lo configurerà l'installer. Se la directory ~/.local/bin non è nel PATH, lo script te lo dirà. Per Windows nello stesso repository c'è lo script download_cli.ps1, mentre l'app desktop si scarica dalla pagina della documentazione; sia l'app che la CLI leggono le stesse impostazioni, quindi tutto quanto segue vale per entrambi. Verifica con goose --version.

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

Passo 3: avvia l'installer.

npx @joingonka/setup --tool goose

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

• creerà il file del provider custom_providers/custom_joingonka.json con l'indirizzo del gateway e i tre modelli della rete con le finestre di contesto reali, con permessi 600. I nomi custom_joingonka e CUSTOM_JOINGONKA_API_KEY sono gli stessi che Goose ricava da solo dal nome "JoinGonka", quindi la chiave inserita nel wizard finirà al posto giusto;
• imposterà JoinGonka come provider predefinito con il modello DeepSeek V4 Flash — ma solo se il provider non è ancora stato scelto oppure è stato scelto il nostro con un modello vuoto o non più disponibile sulla rete. Non toccherà la scelta altrui, ma stamperà il comando per provare: goose session --provider custom_joingonka --model …;
• metterà la chiave in secrets.yaml, solo se l'archivio dei segreti di Goose è sicuramente basato su file; altrimenti dirà chiaramente che resta un ultimo passaggio — i dettagli sono nella sezione sulla chiave;
• creerà copie di backup dei file modificati e alla fine invierà una richiesta reale al gateway per verificare subito chiave, indirizzo e modello.

L'installer individua la directory delle impostazioni allo stesso modo di Goose: ~/.config/goose su Linux e macOS, %APPDATA%\Block\goose\config su Windows, <root>/config quando è impostato GOOSE_PATH_ROOT. Un altro modello si specifica con il flag --model e le abbreviazioni deepseek, glm o minimax; il modello specificato esplicitamente viene sempre salvato. La modalità senza domande prende la chiave dalla variabile d'ambiente:

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

Tutto ciò che fa l'installer può essere scritto manualmente. Il provider è un file JSON separato ~/.config/goose/custom_providers/custom_joingonka.json; il nome del file coincide con il campo name:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Non è previsto un limite di risposta separato per la voce del modello in Goose. Per tali modelli non trasmette affatto il limite nella richiesta — abbiamo verificato ciò dal suo log delle richieste — e in modalità streaming il gateway stesso limita la risposta al limite del modello: 32.768 token per DeepSeek V4 Flash, 8.192 per GLM-5.3 Flash e MiniMax M2.7. Non è necessario impostare la variabile globale GOOSE_MAX_TOKENS per questo: è unica per tutti i provider contemporaneamente.

Goose legge il file del provider tramite un parser JSON rigoroso: un commento o una virgola finale e il provider scompare dall'elenco. Puoi crearlo anche tramite procedura guidata (goose configure → Custom Providers), ma la procedura non chiede la finestra di contesto — dovrai aggiungerla manualmente.

Il provider e il modello predefiniti vivono in ~/.config/goose/config.yaml. Ecco come li scrive Goose stesso:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

Anche il vecchio layout — chiavi piatte GOOSE_PROVIDER e GOOSE_MODEL alla radice del file — funziona: Goose lo legge e lo converte automaticamente nel nuovo al primo salvataggio delle impostazioni, come abbiamo fatto noi dopo goose configure. L'installer su un file vuoto scrive proprio le chiavi piatte — ogni versione le comprende. Le variabili d'ambiente con lo stesso nome sono più importanti del file: se sono impostate nella shell, la scelta dal config.yaml non avrà effetto, e l'installer ti avviserà di questo.

Nel file del provider di Goose c'è solo il nome del secret — CUSTOM_JOINGONKA_API_KEY. Il valore viene cercato in quest'ordine: nella variabile d'ambiente con quel nome, poi nel keyring di sistema (su macOS il Keychain), infine nel file secrets.yaml accanto alla config. I secret finiscono nel file quando lo storage di Goose è di tipo file, e lì restano in chiaro, con permessi 600. In config.yaml, invece, Goose non cerca affatto le chiavi (documentazione).

Lo storage diventa di tipo file se il keyring è disattivato — tramite la variabile GOOSE_DISABLE_KEYRING con qualsiasi valore o la riga GOOSE_DISABLE_KEYRING: true in config.yaml — oppure non è disponibile: server senza sessione grafica, container, CI. Nel secondo caso Goose scrive nel log «Keyring unavailable. Using file storage for secrets.» e passa da solo al file — esattamente ciò che abbiamo visto nel container. L'installer non è in grado di scrivere nel keyring e non lo disattiverà al posto tuo: Goose smetterebbe di vedere i secret che già vi si trovano. Da qui gli scenari:

Il passo rimanente. Avvia goose configure e rispondi alle domande del wizard — ecco come apparivano nella nostra esecuzione:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (da noi era il primo);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, poi su Enter value for CUSTOM_JOINGONKA_API_KEY incolla la chiave — al posto dei caratteri appariranno dei quadratini. La chiave viene salvata subito;
• Would you like to configure advanced settings? → No;
• Select a model — Goose riceve la lista dal gateway: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. Il cursore è sulla prima riga — per mantenere il modello scelto dall'installer, seleziona con le frecce DeepSeek V4 Flash. Dopo la richiesta di verifica il wizard terminerà con la riga «Configuration saved successfully».

In Goose Desktop il percorso è questo: Settings → Models → Configure providers → JoinGonka → chiave → Submit. Se non vuoi incollare la chiave a mano, mettila in una variabile e avvia il wizard dalla stessa shell: Goose scriverà «CUSTOM_JOINGONKA_API_KEY is set via environment variable» e proporrà di salvare il valore:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

E per una singola esecuzione puoi passare la chiave senza salvarla affatto: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session, in PowerShell $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. La variabile d'ambiente ha la precedenza sul valore salvato, ma vive solo fino alla chiusura della shell.

Per prima cosa, vediamo quali impostazioni Goose vede davvero:

goose info -v

Nel blocco «goose Configuration» devono comparire le righe GOOSE_PROVIDER: custom_joingonka e GOOSE_MODEL con l'identificativo del modello. Poi un'esecuzione singola senza sessione interattiva: mettete in una cartella vuota un file con un bug evidente e chiedete di trovarlo.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

Il flag --no-session non salva l'esecuzione nello storico. Nell'intestazione comparirà una riga del tipo ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731, poi la chiamata allo strumento — ▸ shell con il comando cat calc.py — e la risposta con il bug trovato. Un altro modello per una singola esecuzione si specifica con --model: zai-org/GLM-5.3-Flash oppure MiniMaxAI/MiniMax-M2.7. Nella nostra esecuzione del 23 settembre 2026 tutti e tre i modelli della rete hanno completato il ciclo «richiesta → strumento → risultato → risposta». Il CLI di Goose nasconde di default il ragionamento dei modelli — per mostrarlo basta la variabile GOOSE_CLI_SHOW_THINKING=1, se l'output va al terminale. Lato gateway la richiesta è visibile nella dashboard: sezione «Utilizzo», suddivisa in «Per modello» e «Per chiave».

Se qualcosa va storto, la diagnosi di solito si legge direttamente dal messaggio:

Un agente consuma token diversamente da una chat. Già nella configurazione standard, Goose invia al modello le descrizioni di diciotto strumenti integrati e, nella nostra esecuzione, ogni mossa comportava circa 4.600 token in ingresso prima ancora della tua domanda. Il compito “leggere il file e trovare l'errore” ha richiesto due o tre passaggi e 10-15 mila token, quasi tutti in ingresso; Goose effettua da solo un'altra breve richiesta per assegnare un nome alla sessione. Le estensioni non necessarie si disattivano in goose configure → Toggle Extensions — questo è il modo più semplice per ridurre l'input.

Tramite JoinGonka Gateway i token costano $0.0069 per milione in ingresso e $0.021 per milione in uscita — il prezzo è uguale per tutti i modelli della rete e viene prelevato in tempo reale su questa pagina.

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

Il consumo esatto e il saldo sono visibili nell'area personale, nelle sezioni “Utilizzo” e “Fatturazione”. Il motivo per cui DeepSeek V4 Flash è impostato di default — avendo il soffitto di risposta più alto della rete — è spiegato in dettaglio nella panoramica del modello.

Modalità di conferma. Di default Goose lavora in modalità auto — completamente autonomo: modifica ed elimina file, esegue comandi e usa le estensioni senza chiedere nulla. Sul tuo progetto va benissimo, ma su codice altrui è meglio irrigidire la modalità:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

È una proprietà di Goose stesso, non dipende dal provider del modello.

Cambio di modello. Dentro una sessione — il comando /model con l'identificatore, ad esempio /model zai-org/GLM-5.3-Flash; per una sola esecuzione — il flag --model di goose run e goose session; in modo permanente — goose configure oppure la riga model in config.yaml. Il provider resta invariato. GLM-5.3 Flash, che ragiona, è ottima per logiche intricate, ma il tetto della sua risposta è di 8192 token, e una parte se ne va nel ragionamento — i dettagli nella scheda del modello.

Esecuzioni senza supervisione. goose run è adatto a script e CI: il flag -q lascia nell'output solo la risposta del modello, --output-format json restituisce il risultato in formato elaborabile. I limiti --max-turns (quanti passi compie l'agente senza intervento umano) e --max-tool-repetitions (quante volte di fila si può chiamare lo stesso strumento con gli stessi argomenti) proteggono dai loop.

Privacy. Le statistiche d'uso anonime in Goose sono disattivate di default (GOOSE_TELEMETRY_ENABLED). Il gateway non conserva il contenuto dei prompt né delle risposte — nelle statistiche restano solo i dati aggregati di consumo.