Zoo Code + JoinGonka Gateway: migrazione da Roo Code ai modelli Gonka

Passo 1: installare l'estensione. In VS Code apri il pannello delle estensioni (Ctrl+Shift+X, su macOS Cmd+Shift+X), cerca «Zoo Code» e installa l'estensione dell'editore Zoo Code Organization. Lo stesso con un solo comando:

code --install-extension ZooCodeOrganization.zoo-code

Serve VS Code 1.100 o superiore — come indicato nel manifest dell'estensione; per VSCodium, Windsurf e altri editor senza Marketplace l'estensione è pubblicata su Open VSX. Oltre al canale stabile (3.82.2 del 18 settembre 2026) esiste la versione preliminare 3.83.x — build notturne del ramo principale; per lavorare scegli quella stabile. Dopo l'installazione, nella barra delle attività comparirà l'icona di Zoo Code.

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». È comodo creare una chiave separata per Zoo Code: il suo consumo sarà visibile nelle statistiche su una riga dedicata.

Passo 3: avviare l'installer.

npx @joingonka/setup --tool zoo --model deepseek

L'installer chiederà la chiave — non va passata negli argomenti della riga di comando, per non lasciarla nella cronologia della shell. Non ha nulla da scrivere: i profili dei provider insieme alle chiavi Zoo Code li conserva nell'archivio protetto dei segreti di VS Code, non in un file. Per questo l'installer stampa i valori pronti per il modulo e i limiti reali del modello scelto:

Zoo Code is configured in the VS Code extension UI (no file is written).
Open the Zoo Code settings (gear icon) → API Provider, then enter:

  API Provider: OpenAI Compatible
  Base URL:     https://gate.joingonka.ai/v1
  API Key:      jg-your-key
  Model:        deepseek-ai/DeepSeek-V4-Flash-0731

Then set the real limits of this model under Model Configuration
(the defaults do not fit any Gonka model):

  Context Window Size: 380000
  Max Output Tokens:   32768
  Image Support:       off

Zoo Code relies on native tool calling only — all our Gonka models support it.

Subito dopo arriva il risultato di una richiesta dal vivo al gateway — in caso di successo la riga ✓ Verified: the gateway accepted the key, base URL and model. Chiave, indirizzo e modello vengono verificati subito, non al primo task. La chiave nel blocco stampato è completa, per copiarla comodamente — non pubblicare questo output.

Senza il flag --model l'installer inserirà MiniMax M2.7: dove il modello si sceglie manualmente, propone quello con la maggiore capacità della rete. Per Zoo Code consigliamo di iniziare con DeepSeek V4 Flash: nel nostro test ha completato il turno dopo il risultato dello strumento con la prima richiesta — i dettagli nella sezione sulla verifica; il flag accetta anche le abbreviazioni glm (GLM-5.3 Flash) e minimax. Senza il flag --tool l'installer mostrerà un menu di 25 strumenti.

Un dettaglio del modulo: in Zoo Code 3.82.2 non esiste un blocco separato con l'intestazione Model Configuration. I campi dei limiti si trovano nello stesso modulo più in basso, sotto la dicitura «Configure the capabilities and pricing for your custom OpenAI-compatible model», e Max Output Tokens precede Context Window Size.

Al primo avvio, Zoo Code mostra un messaggio di benvenuto con il pulsante Choose your provider: questo conduce a un modulo in cui è pre-selezionato OpenRouter. Cambia il provider in OpenAI Compatible e clicca su Finish. In seguito, lo stesso modulo è accessibile tramite l'icona dell'ingranaggio nell'intestazione del pannello Zoo Code, sezione Providers; le modifiche vengono salvate con il pulsante Save.

Limiti dei modelli di rete:

Il resto può essere lasciato invariato: Enable streaming e Include max output tokens devono essere attivi, Enable R1 model parameters e Use Azure disattivati (queste opzioni sono per la famiglia di modelli R1 e Azure OpenAI), i campi Custom Headers e Extra Body devono rimanere vuoti.

I limiti sono memorizzati nel profilo e non nel modello: se si cambia Model nello stesso profilo, le dimensioni della finestra e il limite di risposta rimarranno invariati. Per questo motivo è più comodo creare un profilo dedicato per ogni modello; ne parleremo nella prossima sezione.

Zoo Code nasce dalla codebase di Roo Code, quindi il trasferimento richiede pochi minuti e non è necessario toccare i file del progetto. La guida alla migrazione ufficiale descrive l'esportazione e l'importazione delle impostazioni; il resto viene trasferito con un singolo pulsante o letto dai percorsi originali:

Il profilo Roo Code che puntava al JoinGonka Gateway verrà trasferito con indirizzo, chiave, modello e limiti: verifica solo che il modello sia attualmente disponibile nella rete; l'elenco viene fornito da GET https://gate.joingonka.ai/v1/models.

Modalità e profili. Le modalità integrate sono cinque: Code, Debug, Architect (modifica solo file Markdown), Ask (risponde senza modifiche) e Orchestrator (distribuisce sottocompiti ad altre modalità). Si cambiano dall'elenco accanto al campo di input, con un comando con il nome della modalità all'inizio del messaggio, ad esempio /architect, o con la combinazione Ctrl+. (Cmd+. su macOS). Ogni modalità ricorda il profilo con cui hai lavorato l'ultima volta e, cambiando modalità, Zoo Code passa automaticamente al profilo corretto.

Da qui nasce uno schema comodo: un profilo per modello, assegnato alle modalità. In Settings → Providers clicca su "+" accanto al campo Configuration Profile, dai un nome al profilo, ad esempio Gonka DeepSeek, e compila il modulo; ripeti per GLM-5.3 Flash e MiniMax M2.7: l'indirizzo e la chiave sono gli stessi per tutti. Quindi, in ogni modalità, seleziona il profilo nell'elenco accanto al campo di input e la modalità lo ricorderà. L'icona del lucchetto in questo elenco, al contrario, blocca un unico profilo per tutte le modalità della cartella di lavoro.

Livello di ragionamento. L'opzione Enable Reasoning Effort nel modulo apre l'elenco Low, Medium, High, Extra High e Max; finché è disattivata, il livello non viene incluso nella richiesta. Per GLM-5.3 Flash, l'interruttore è essenzialmente binario: Low disattiva il ragionamento, qualsiasi altro livello lo lascia attivo al massimo: è comodo mantenere un profilo GLM separato con Low per domande rapide. Maggiori dettagli nella recensione di GLM-5.3 Flash. Per DeepSeek V4 Flash e MiniMax M2.7, il gateway non sovrascrive la scala: il funzionamento del livello dipende dal modello stesso.

Apri una cartella con un file piccolo contenente un errore evidente, ad esempio calc.py con una funzione di addizione che sottrae, e in modalità Code scrivi: "Leggi calc.py e dimmi in una frase se contiene un errore". Zoo Code chiederà il permesso di leggere il file: "Zoo wants to read this file", con i pulsanti Approve e Deny, se la lettura non è stata autorizzata in precedenza in Auto-Approve. Successivamente, il modello richiamerà lo strumento di completamento e l'attività terminerà con un blocco Task Completed contenente la risposta nel merito; il ragionamento, se presente, viene mostrato in un blocco Thinking separato. La percentuale di riempimento del contesto nell'intestazione ridotta dell'attività viene calcolata in base al Context Window Size, motivo in più per impostarlo correttamente.

Abbiamo riprodotto questo processo con una richiesta basata sull'esempio di Zoo Code: un flusso e strumenti in uno schema rigoroso, con il risultato di read_file nella cronologia. DeepSeek V4 Flash ha risposto con una chiamata nativa a attempt_completion con l'output corretto: la funzione sottrae invece di sommare. La seconda metà del controllo è il pannello del gateway: nella sezione "Utilizzo", la richiesta apparirà suddivisa per modello e l'orario dell'ultima chiamata della chiave verrà aggiornato.

Senza Auto-Approve, l'errore arriva sotto forma di blocco API Request Failed con i pulsanti Retry e Start New Task, accompagnato dall'intestazione Provider Error con un codice e un conto alla rovescia per il riavvio. Il testo della risposta del gateway è visibile nel messaggio o nei suoi dettagli:

Un agente consuma token in modo diverso da una chat. In ogni richiesta, Zoo Code inserisce un system prompt con le regole della modalità, le descrizioni degli strumenti e le informazioni sulla cartella di lavoro — si tratta di migliaia di token ancor prima della tua domanda, — e un task solitamente richiede diversi passaggi. Pertanto, il prezzo per token qui è fondamentale.

Tramite il JoinGonka Gateway, i token costano $0.0069 per milione in entrata e $0.021 per milione in uscita — il prezzo è identico per tutti i modelli della rete e viene caricato in questa pagina da una fonte in tempo reale. Ordine di grandezza per i prezzi a settembre 2026:

Per confronto — come si può pagare per i modelli in Zoo Code:

Con Input Price e Output Price compilati, il costo del task è visibile nell'intestazione, ma con una precisione al centesimo — i task brevi sui modelli di rete mostreranno $0.00. Il consumo esatto e il saldo residuo sono disponibili nel pannello di controllo, nelle sezioni "Utilizzo" e "Fatturazione".

Conferme e autonomia. Per impostazione predefinita, Auto-Approve è disattivato e Zoo Code richiede l'autorizzazione per leggere, scrivere ed eseguire comandi; per attività lunghe, abilitare le categorie necessarie nel menu Auto-approve accanto al campo di input. Per i comandi è disponibile il Destructive Command Guard (Settings → Auto-Approve): l'estensione scarica il suo file eseguibile e i comandi superati vengono eseguiti automaticamente, mentre quelli bloccati attendono conferma. Con Auto-Approve, Zoo Code ripete automaticamente anche le richieste fallite: la pausa inizia da 5 secondi e raddoppia a ogni tentativo, ma non supera i 10 minuti.

Risposta in streaming. Non disattivare Enable streaming: durante lo streaming, il gateway restituisce il testo man mano che viene generato e limita la risposta solo al tetto del modello, mentre una richiesta senza streaming e senza un limite esplicito viene troncata a 1500 token di risposta (nel caso di GLM-5.3 Flash a 3000).

Indicizzazione del codice. La ricerca semantica nel progetto (Codebase Indexing) viene configurata separatamente dal modello tramite il provider di embedding; per questo è disponibile l'opzione locale Semble - Local.

Immagini. I modelli di rete sono testuali. Per screenshot e mockup, creare un profilo separato con un modello che elabora immagini e passare a questo durante tali attività.

Privacy. Zoo Code invia agli sviluppatori dati su errori e utilizzo, associati all'identificativo di installazione, senza codice o prompt; questa funzione può essere disattivata tramite l'interruttore Allow error and usage reporting in Settings → About Zoo Code. Il gateway non memorizza il contenuto dei prompt e delle risposte: nel pannello di controllo sono visibili solo i contatori di richieste e token.