Codex CLI: la tua chiave invece dell'abbonamento

Codex non è un semplice suggeritore nell'editor, ma un esecutore autonomo. Tu definisci il task a parole, lui decide quali file leggere, quali comandi eseguire e cosa modificare. Ha a disposizione circa una decina di strumenti: esecuzione di comandi, lettura di file, gestione di un piano di lavoro, richiesta di chiarimenti all'utente, generazione di agent secondari per i sottotask.

Due modalità di lavoro. Interattiva — codex senza argomenti, dialogo nel terminale con visualizzazione di ogni passaggio. Non interattiva — codex exec «task», un'esecuzione singola fino al risultato: utile negli script e in CI.

La sicurezza è integrata: per impostazione predefinita, l'agent lavora in una sandbox e chiede conferma prima di apportare modifiche. Il livello di controllo si imposta nella configurazione, da "chiedere tutto" a un'esecuzione completamente autonoma con diritti di scrittura nella cartella di lavoro.

Un'altra peculiarità è lo stato del dialogo. Codex non chiede al server di ricordare nulla: mantiene l'intera sequenza internamente e la invia completa a ogni passaggio. Per te significa che la corrispondenza non rimane depositata presso il provider del modello e che cambiare endpoint non interrompe la sessione iniziata.

La differenza rispetto a Claude Code e altri agent da terminale sta proprio nel protocollo. Codex comunica con il modello tramite Responses API, dove la conversazione non è descritta come un elenco piatto di messaggi, ma come una sequenza di elementi: testo, chiamata dello strumento, risultato della chiamata, blocco di ragionamento. Questo fornisce allo strumento un modello di dialogo più rigoroso e a te la necessità di disporre di un endpoint che comprenda tale protocollo.

Codex memorizza le impostazioni in ~/.codex/config.toml. Il proprio provider si descrive con un blocco [model_providers.*] e il campo chiave qui è wire_api: senza di esso, Codex proverà a parlare tramite Chat Completions e non riuscirà a completare il ciclo agent.

# ~/.codex/config.toml
model_provider = "joingonka"
model = "deepseek-ai/DeepSeek-V4-Flash-0731"

[model_providers.joingonka]
name = "JoinGonka Gateway"
base_url = "https://gate.joingonka.ai/v1"
env_key = "JOINGONKA_API_KEY"
wire_api = "responses"

La chiave non viene scritta nel file: env_key nomina la variabile d'ambiente da cui Codex la prenderà. Il nome della variabile è personalizzato, non OPENAI_API_KEY, così questa impostazione non interferisce con altri tuoi strumenti che lavorano con OpenAI.

export JOINGONKA_API_KEY=jg-la-tua-chiave

Il campo model imposta il modello predefinito e model_provider quale dei blocchi descritti utilizzare. Entrambi possono essere sovrascritti al momento dell'avvio, quindi una singola configurazione può gestire comodamente più provider: di lavoro, sperimentale e di riserva.

La chiave viene fornita nell'area personale dopo la registrazione, dove è possibile visualizzare anche il saldo e i consumi. Se preferisci non toccare la configurazione generale, lo stesso blocco può essere trasmesso una tantum tramite -c: codex -c model_provider=joingonka …. E per mantenere diverse configurazioni indipendenti, specifica la cartella delle impostazioni con la variabile CODEX_HOME.

Il modo più rapido per verificare che la connessione funzioni è una prova singola:

codex exec "Rispondi in una riga: quanto fa 17*3?"

Nell'intestazione della risposta, Codex stampa con chi sta lavorando: model, provider: joingonka, modalità sandbox e ID sessione. Se vedi il tuo provider e ricevi una risposta in basso, la connessione è attiva.

Successivamente, è importante verificare ciò per cui Codex viene installato: il lavoro sui file. Metti un piccolo file con un errore evidente nella directory e chiedi di trovarlo:

codex exec "Leggi calc.py e dimmi in una frase se c'è un errore."

L'agente dovrebbe richiamare autonomamente lo strumento di lettura, aprire il file e rispondere correttamente, indicando la riga. Se questo avviene, l'intero ciclo dell'agente (richiesta → chiamata dello strumento → risultato → risposta) tramite il gateway è configurato correttamente.

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

La prima richiesta in una sessione può richiedere alcuni secondi: Codex invia un ampio system prompt e la descrizione di tutti i suoi strumenti, e il nodo di rete deve accettare l'attività. Le risposte successive arriveranno più velocemente.

Tutti i modelli della rete sono disponibili allo stesso prezzo, quindi la scelta riguarda il comportamento e non il budget. Di seguito il risultato di una prova reale della stessa attività (lettura di un file e ricerca di un errore) tramite Codex su ciascuno dei modelli.

La raccomandazione predefinita è DeepSeek V4 Flash: il lavoro dell'agente esaurisce rapidamente il contesto, e 380K token offrono la possibilità di gestire molti file contemporaneamente. Se desideri risposte estremamente brevi, scegli Kimi K2.6. Il modello può essere cambiato con una sola riga model nel file di configurazione o con il flag -c model=… senza dover modificare il file.

L'elenco aggiornato dei modelli di rete è sempre disponibile su GET https://gate.joingonka.ai/v1/models.

Gli strumenti dell'agente consumano token in modo diverso rispetto alla chat: per ogni frase Codex aggiunge un system prompt e la descrizione di tutti gli strumenti, quindi conduce un dialogo a più fasi con il modello. In una prova reale, una semplice attività come "leggi il file e trova l'errore" è costata circa 18-20 mila token. È un prezzo normale per l'autonomia, ed è proprio per questo che il prezzo per token è determinante.

Tramite JoinGonka Gateway, i token costano $0.0047 per milione in ingresso e $0.014 per milione in uscita — il prezzo è identico per tutti i modelli della rete e viene estratto su questa pagina da una fonte in tempo reale.

Per confronto, ecco come funzionano le opzioni a pagamento di Codex e dei suoi concorrenti:

Il pagamento avviene in base al consumo effettivo, senza abbonamento mensile e senza quote sul numero di richieste: non ci sono finestre di cinque ore, limiti di "prompt" o moltiplicatori nelle ore di punta. Il saldo viene ricaricato con criptovaluta; il residuo e il consumo giornaliero sono visibili nel pannello personale. Analisi dettagliata dell'economia nell'articolo sull'API più economica.

La cronologia della conversazione è gestita da Codex stesso. La invia interamente a ogni richiesta e non chiede al server di ricordare nulla; noi non memorizziamo le conversazioni. Il tuo codice e i tuoi prompt non rimangono sul gateway dopo la risposta.

La ricerca web funziona. Codex dichiara uno strumento di ricerca in ogni richiesta e il gateway lo accetta: la ricerca viene eseguita dal nostro lato e i risultati vengono integrati nella risposta del modello.

Gli strumenti sono locali, non cloud. Codex esegue i comandi e legge i file localmente sulla tua macchina, quindi l'accesso al progetto non dipende dal fornitore del modello.

Sandbox. Su Linux Codex utilizza bubblewrap per isolare i comandi in esecuzione. Se non è presente nel sistema, Codex ti avviserà e utilizzerà una copia integrata: ciò non influisce sul funzionamento, ma è più comodo installare il pacchetto tramite il gestore standard.

Se hai bisogno di lavorare con le immagini — screenshot dell'interfaccia, schemi nelle foto — usa per tali compiti uno strumento con un modello dotato di capacità visive: nella rete Gonka i modelli sono testuali. Per codice, comandi e file, questo non rappresenta un limite.

Altri agenti terminali, se Codex non fa per te: la guida rapida all'API mostra come collegare qualsiasi strumento compatibile in pochi minuti.