OpenHands + JoinGonka Gateway: agente sul proprio endpoint

Il progetto oggi ha diverse interfacce, e a seconda di quella che hai avviato, dipende dove cercare le impostazioni del modello. I valori sono identici ovunque, cambia solo il percorso per accedervi.

Per Agent Canvas sono necessari Node.js e uv, su cui gira il server locale dell'agente (dettagli nelle istruzioni di installazione). Le istruzioni menzionano Node.js 22.12 o superiore, ma il pacchetto stesso a partire dalla versione 1.17 richiede Node.js 24 o superiore: installa la 24 per evitare avvisi di incompatibilità. Esiste anche un'opzione in container: l'immagine ghcr.io/openhands/agent-canvas espone l'interfaccia su http://localhost:8000/canvas e vede solo le directory che hai montato.

Chiave JoinGonka. Registrati su gate.joingonka.ai/register, conferma l'indirizzo e crea una chiave con prefisso jg- nella sezione "API Keys". Una chiave e un saldo sono validi per tutti i modelli della rete. Nell'elenco degli strumenti dell'installer @joingonka/setup OpenHands non c'è, e non è una dimenticanza: le sue impostazioni vivono nell'interfaccia e nell'archiviazione protetta del backend, non in un file di configurazione testuale che si può modificare facilmente dall'esterno.

Passaggio 1. Avvia Agent Canvas e apri Settings > LLM. La procedura di configurazione iniziale propone il provider proprietario di OpenHands: questo passaggio può essere saltato, è facile tornare alle impostazioni in un secondo momento.

Passaggio 2. Fai clic su Add LLM Profile e vai alla scheda Advanced: la scheda Basic offre solo i provider e i modelli presenti nell'elenco integrato.

Passaggio 3. Compila i tre campi:

Passaggio 4. Salva il profilo. Prima di salvare, Canvas verifica la configurazione con una richiesta dal backend: se la chiave viene rifiutata o il modello non è disponibile, il profilo non verrà salvato e vedrai un messaggio di errore.

Passaggio 5. Inizia una nuova conversazione e invia un breve messaggio. Le conversazioni già aperte continuano a funzionare con il modello con cui sono iniziate.

Perché openai/. LiteLLM identifica il provider tramite il prefisso del modello. Il prefisso openai/ non significa "modello di OpenAI", ma "comunicare con il server tramite il protocollo OpenAI Chat Completions". Viene tagliato solo il primo segmento, quindi al gateway arriva l'identificatore reale: deepseek-ai/DeepSeek-V4-Flash-0731. Nella documentazione di OpenHands lo stesso schema è mostrato con l'esempio openai/qwen/qwen3.6-35b-a3b. Senza il prefisso, LiteLLM si rifiuterà di funzionare con il messaggio LLM Provider NOT provided.

Perché solo /v1. LiteLLM contatta il server tramite il client ufficiale OpenAI, che aggiunge automaticamente /chat/completions. Pertanto l'indirizzo deve terminare necessariamente con /v1: senza il suffisso, la richiesta non raggiungerà l'API; con un suffisso in più, punterebbe a un percorso inesistente. Un altro requisito di Canvas: l'indirizzo deve essere raggiungibile dal backend, non solo dal browser. Il gateway è un indirizzo HTTPS pubblico, visibile dal container Docker esattamente come dall'host; soluzioni come host.docker.internal sono necessarie solo per i modelli in esecuzione sulla tua macchina.

Profili per tutti e tre i modelli. Crea un profilo per ogni modello di rete e assegna loro nomi brevi, ad esempio deepseek, glm e minimax (la documentazione indica un limite di dieci profili). È possibile passare da uno all'altro direttamente nella conversazione senza perdere il contesto: tramite il pulsante di selezione del profilo nel campo di input o con il comando /model glm; /model senza argomenti mostrerà l'elenco. Per evitare di inserire la chiave in ogni profilo, puoi salvarla una volta nel blocco Provider Connections, accessibile dal backend locale.

Interfaccia precedente in Docker. I campi sono gli stessi: Settings → scheda LLM → attiva Advanced → Custom Model, Base URL, API Key → Save Changes.

La CLI si installa con un solo comando tramite uv e al primo avvio ti guida da sé nella configurazione del modello; in seguito ci si torna con Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Per gli script sono più comode le variabili d'ambiente. Dettaglio importante: per impostazione predefinita la CLI le ignora e le applica solo con il flag --override-with-envs — per una singola esecuzione, senza salvare nulla:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Lo stesso set funziona senza interfaccia — per CI e attività in batch:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

In modalità headless l'agente agisce sempre con approvazione automatica, quindi avvialo dove può fare tutto: in una directory separata o in un container. Il flag --json trasforma l'output in un flusso di eventi JSONL — comodo da elaborare in una pipeline. È esattamente così che abbiamo verificato il collegamento il 21 settembre 2026 su CLI 1.16.0: nell'intestazione la CLI stampa Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, poi l'agente legge il file e risponde nel merito.

Le impostazioni salvate della CLI si trovano in ~/.openhands/agent_settings.json: il modello si cambia modificando tre campi del blocco llm — model, api_key e base_url. Non conviene creare il file da zero: la procedura guidata del primo avvio vi scrive anche le altre impostazioni dell'agente, tra cui la compressione della cronologia, senza la quale una conversazione lunga sbatte contro la finestra di contesto.

Se integri l'agente nel tuo codice, gli stessi tre valori li accetta l'OpenHands SDK:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Il prezzo dei modelli nella rete è lo stesso, quindi la scelta dipende dal comportamento. Per un Autonomous agent, due cifre sono fondamentali. Finestra di contesto: a ogni passaggio la cronologia viene reinviata, quindi più lunga è la finestra, più a lungo l'agente lavora senza perdite. Limite di risposta: il passaggio in cui l'agente scrive un intero file di grandi dimensioni deve rientrare in un'unica risposta. Nella tabella sono riportati i risultati del nostro test sullo stesso compito (leggere un file e trovare l'errore) tramite OpenHands CLI 1.16.0 con SDK 1.21.0.

Lo schema di lavoro per un compito a lungo termine segue il consiglio della documentazione di OpenHands: pianificare con un modello ed eseguire con un altro. Iniziate la conversazione sul profilo glm e chiedete un piano senza modificare i file; dopodiché inviate /model deepseek e date il comando di esecuzione. La cronologia, i file e lo stato del compito vengono conservati durante il passaggio. Tenete il profilo minimax come terzo: è comodo passarvi quando gli altri due sono saturi nelle ore di punta, e nella sezione Settings > Application è possibile affidare a lui la generazione dei titoli delle conversazioni.

Compressione della cronologia. Anche una finestra di centinaia di migliaia di token è finita in un compito che dura molte ore. In OpenHands se ne occupa il condensatore: comprime gli eventi passati in un breve riassunto, il che, secondo la documentazione, riduce la latenza e il consumo di token nelle conversazioni lunghe. In Agent Canvas si configura nella sezione Settings > Condenser; nel nostro test, il CLI l'ha attivato da solo con una soglia di 80 eventi.

Limiti del modello. OpenHands trae la finestra di contesto e il limite di risposta dal database di LiteLLM, ma gli identificatori della rete Gonka non vi sono presenti (abbiamo verificato su LiteLLM 1.81), quindi l'agente non ha valori propri per questi modelli. Ciò non interferisce con il funzionamento: il gateway applica il limite di risposta autonomamente, secondo la tabella sopra. Se desiderate impostare i limiti esplicitamente, nell'SDK si utilizzano i campi max_input_tokens e max_output_tokens, mentre in Canvas la scheda All apre l'elenco completo dei campi del profilo. Dettagli sul modello predefinito sono disponibili nella panoramica di DeepSeek V4 Flash.

È possibile verificare se le richieste passano effettivamente attraverso il gateway da due punti. Dal lato OpenHands: avvia una nuova conversazione e assegna un compito breve come "leggi il README e riassumilo in una frase": l'agente dovrebbe richiamare lo strumento e rispondere. Dal lato del gateway: vai nel pannello di controllo, sezione "Utilizzo": la richiesta apparirà nella suddivisione "Per modelli", mentre nel blocco "Per chiavi" verrà aggiornato l'orario dell'ultima richiesta. Se è vuoto, significa che la conversazione sta avvenendo su un altro profilo: controlla quale di essi è contrassegnato come attivo.

Secondo la documentazione di OpenHands, il numero di tentativi e le pause tra essi in caso di errore 429 si configurano tramite le variabili LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT e LLM_RETRY_MAX_WAIT. I valori predefiniti nella documentazione e nell'SDK divergono, quindi fai riferimento a quelli effettivi: nello stato della conversazione CLI 1.16.0 abbiamo osservato 5 tentativi con pause da 8 a 64 secondi.

Attraverso il 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 aggiornato in questa pagina da una fonte in tempo reale.

Le stime nella colonna di destra si riferiscono ai prezzi di settembre 2026; il funzionamento dell'economia degli agenti è analizzato in dettaglio nell'articolo sull'API più economica per AI-agent.

Limite di spesa. OpenHands consiglia di impostare limiti di spesa; il gateway ha questa funzione integrata nel modello di pagamento: il saldo è prepagato e l'agente non spenderà più di quanto presente sul conto. Il saldo residuo e il consumo giornaliero sono visibili nel pannello. Per CI e automazioni in background, crea una chiave separata in modo che il loro consumo non si mescoli con il tuo; le chiavi secondarie con limite giornaliero sono descritte nell'articolo sui Management Keys.

Confini della fiducia. Agent Canvas, eseguito tramite npm, lavora con i privilegi del tuo utente e vede l'intero file system. Per codice altrui, utilizza la versione in Docker: l'agente vedrà solo la directory montata. Questa è una proprietà di OpenHands e non dipende dal provider del modello.

La corrispondenza rimane a te. OpenHands conserva la cronologia della conversazione localmente, in ~/.openhands, e la invia al modello ad ogni passaggio; il gateway non conserva la corrispondenza: i tuoi prompt e il codice non rimangono memorizzati dopo la risposta.

Se l'attività include immagini (screenshot dell'interfaccia, schemi), crea per essa un profilo separato con un modello vision: i modelli della rete Gonka sono testuali. Per codice, comandi e file questa non è una limitazione.