Codex CLI: la tua chiave invece dell'abbonamento

Codex non è un suggeritore dentro l'editor, ma un esecutore autonomo. Tu formuli il compito a parole, lui decide da sé quali file leggere, quali comandi eseguire e cosa modificare. Ha a disposizione una decina di strumenti: esecuzione di comandi, lettura di file, gestione di un piano di lavoro, richiesta di chiarimenti all'utente, generazione di agenti figli per sottoattività.

Due modalità di lavoro. Interattiva — codex senza argomenti, dialogo nel terminale con la visualizzazione di ogni passo. Non interattiva — codex exec "task", esecuzione singola fino al risultato: comoda negli script e in CI.

La sicurezza è integrata: per impostazione predefinita l'agente lavora in sandbox e chiede conferma prima delle modifiche. Il livello di controllo si imposta nella configurazione — da «chiedi tutto» fino a un'esecuzione completamente autonoma con diritto di scrittura nella directory di lavoro.

Un'altra particolarità è lo stato della conversazione. Codex non chiede al server di ricordare nulla: tiene l'intera cronologia dalla sua parte e la invia per intero a ogni turno. Per te questo significa che la conversazione non resta sul lato del provider del modello, e cambiare endpoint non interrompe la sessione già avviata.

La differenza rispetto a Claude Code e ad altri agenti da terminale sta proprio nel protocollo. Codex comunica con il modello tramite le Responses API, dove la conversazione non è descritta come un elenco piatto di messaggi, ma come una sequenza di elementi: testo, invocazione di strumento, risultato dell'invocazione, blocco di ragionamento. Per lo strumento questo significa un modello di dialogo più rigoroso, per te — la necessità di avere un endpoint che comprenda questo protocollo.

La via rapida — l'installer. Il comando npx @joingonka/setup --tool codex scrive da sé il blocco del provider in ~/.codex/config.toml con wire_api = "responses", il modello e la sua finestra di contesto reale, conservando i tuoi commenti e le altre impostazioni, per poi verificare chiave e modello con una richiesta reale. Se nel config è già selezionato un altro provider, l'installer non lo tocca e ti suggerisce il comando per un avvio una tantum. La chiave viene inserita direttamente nel file (permessi 600), nel campo experimental_bearer_token — l'unico in cui Codex può conservare la chiave in chiaro; lo stesso Codex lo considera sperimentale. La variante manuale qui sotto aggira il problema con una variabile d'ambiente.

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

# ~/.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 indica il nome della variabile d'ambiente da cui Codex la preleverà. Il nome della variabile è tuo, non OPENAI_API_KEY — così la configurazione non interferisce con gli altri tuoi strumenti che usano OpenAI.

export JOINGONKA_API_KEY=jg-your-key

Il campo model imposta il modello predefinito, mentre model_provider indica quale dei blocchi descritti utilizzare. Entrambi si possono sovrascrivere al momento dell'avvio, quindi un solo config può servire comodamente più provider: quello di produzione, quello sperimentale e quello di riserva.

La chiave viene rilasciata nell'area personale dopo la registrazione, dove puoi anche vedere saldo e consumo. Se preferisci non toccare il config condiviso, lo stesso blocco si può passare una tantum tramite -c: codex -c model_provider=joingonka …. E per tenere più configurazioni indipendenti, indica la cartella delle impostazioni con la variabile CODEX_HOME.

Il modo più veloce per verificare che il collegamento funzioni è un'esecuzione singola:

codex exec "Answer in one line: what is 17*3?"

Nell'intestazione della risposta Codex stampa con chi sta lavorando: model, provider: joingonka, la modalità sandbox e l'ID della sessione. Se lì c'è il vostro provider e in basso è arrivata la risposta, la connessione è viva.

Poi vale la pena verificare la cosa più importante, il motivo per cui si installa Codex: il lavoro con i file. Mettete nella directory un piccolo file con un errore evidente e chiedetegli di trovarlo:

codex exec "Read calc.py and tell me in one sentence whether it has a bug."

L'agente deve chiamare da solo lo strumento di lettura, aprire il file e rispondere nel merito, indicando la riga. Se questo accade, il ciclo agentico completo (richiesta → chiamata allo strumento → risultato → risposta) attraverso il gateway si compone correttamente.

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

La prima richiesta della sessione può richiedere qualche secondo: Codex invia un grande system prompt e la descrizione di tutti i suoi strumenti, e il nodo di rete deve accettare il task. Le risposte successive arrivano più in fretta.

Tutti i modelli della rete sono disponibili allo stesso prezzo, quindi la scelta riguarda il comportamento, non il budget. Di seguito il risultato di un test dal vivo dello stesso compito (lettura di un file e ricerca di un errore) tramite Codex su DeepSeek V4 Flash e MiniMax M2.7; GLM-5.3 Flash è entrato nella rete dopo il test, quindi sono riportate le proprietà del modello.

La raccomandazione predefinita è DeepSeek V4 Flash: il lavoro agentico esaurisce rapidamente il volume del contesto, e 380K token permettono di tenere in memoria molti file contemporaneamente. Se il compito richiede riflessione su logiche complesse, scegli GLM-5.3 Flash, ma tieni un margine per max_tokens: una parte del budget di risposta viene assorbita dal ragionamento. Il modello si cambia con una sola riga model nel file di configurazione o con il flag -c model=… senza modificare il file.

L'elenco aggiornato dei modelli della rete è 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.0069 per milione in ingresso e $0.021 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.