Codex CLI: permessi, config, automazione

Codex CLI è l'agente da riga di comando di OpenAI che legge il repository, propone modifiche ed esegue comandi restando nel terminale, con licenza Apache-2.0. L'installazione richiede un comando solo, mentre la parte che ti farà perdere tempo è il sistema di permessi, che lavora su due livelli separati: la sandbox stabilisce cosa può fare tecnicamente, la politica di approvazione stabilisce quando deve fermarsi a chiederti il consenso. Questa pagina copre entrambi i livelli nella versione 0.147.0 di oggi, l'uso di codex exec negli script e i casi in cui uno strumento diverso rende di più.

Come si installa Codex CLI?

Si installa con un gestore di pacchetti o con lo script ufficiale, e la scelta dipende da quanto vuoi dipendere da Node. Se Node lo hai già bastano npm install -g @openai/codex oppure brew install --cask codex su Mac, mentre lo script curl -fsSL https://chatgpt.com/codex/install.sh | sh scarica il binario già compilato e ignora Node del tutto. Su Windows l'equivalente è powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex", e i binari nativi coprono Apple Silicon, x86_64, Linux arm64 e Windows.

Al primo avvio digiti codex dentro la cartella del progetto e scegli tra account ChatGPT e chiave API, poi il comando /init genera il file AGENTS.md con le istruzioni di progetto. Prima di riempirlo vale la pena decidere cosa scriverci e cosa lasciarne fuori, visto che le istruzioni troppo lunghe peggiorano il risultato invece di migliorarlo.

Come funzionano sandbox e approvazioni?

Funzionano come due controlli indipendenti che si combinano, e confonderli è il motivo per cui l'agente sembra ignorare le impostazioni. La sandbox stabilisce cosa il processo può toccare: read-only lascia leggere ma non modificare né eseguire comandi senza approvazione, workspace-write permette di scrivere ed eseguire comandi locali dentro la cartella di lavoro, danger-full-access rimuove sia il confine sul filesystem sia quello sulla rete. La politica di approvazione stabilisce invece quando l'agente si ferma a chiedere: untrusted chiede prima di quasi tutto, on-request chiede solo per uscire dalla sandbox, never non chiede mai.

La combinazione sensata per il lavoro quotidiano è workspace-write insieme a on-request, perché l'agente procede senza interrompere ogni due minuti ma deve chiedere il permesso per uscire dalla cartella o raggiungere la rete. Il confinamento lo applica il sistema operativo: su macOS Codex usa il framework Seatbelt, su Linux e WSL2 usa bubblewrap tramite l'eseguibile bwrap, che richiede il supporto ai namespace utente non privilegiati. Se quel supporto manca sulla tua distribuzione la sandbox non parte, ed è la causa più frequente dei problemi su server e container minimali.

Dove si mette la configurazione?

La configurazione sta in un file TOML letto da più posizioni in ordine di precedenza: prima i flag a riga di comando, poi il file di progetto .codex/config.toml, poi i profili in ~/.codex/<nome>.config.toml, poi il file personale ~/.codex/config.toml, poi /etc/codex/config.toml e infine i valori predefiniti. Il file di progetto vince su quello personale, ed è il motivo per cui conviene committarlo: il team eredita le stesse regole senza doverle ripetere a voce.

Le chiavi che userai quasi sempre sono quattro e stanno tutte al primo livello del file.

model = "gpt-5.6"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

I server MCP si dichiarano nella tabella [mcp_servers], quindi se hai già scritto un server tuo per esporre i dati della tua applicazione lo colleghi con la stessa configurazione degli altri client. La versione 0.147.0 del 7 agosto 2026 ha portato il supporto MCP alla revisione 2026-07-28, con avvio non bloccante dei server.

Come si usa Codex CLI in uno script o in CI?

Si usa con codex exec, che esegue il task senza aprire l'interfaccia interattiva e scrive il risultato sullo standard output. La forma minima è codex exec "genera le note di rilascio degli ultimi 10 commit", mentre per l'automazione il flag utile è --json, che trasforma l'output in un flusso JSON Lines dove ogni evento diventa un oggetto strutturato da passare a jq. Se ti serve una risposta con una forma precisa esiste --output-schema, che accetta un JSON Schema e obbliga la risposta a rispettarlo, così lo script a valle non interpreta testo libero.

In modalità non interattiva la sandbox predefinita è read-only, quindi un comando che deve modificare file va lanciato passando esplicitamente --sandbox workspace-write. Il vecchio --full-auto è deprecato e stampa un avviso al posto di funzionare, mentre danger-full-access la documentazione lo limita agli ambienti isolati come un runner di CI o un container. Su GitHub Actions la strada consigliata resta l'action ufficiale invece della CLI installata a mano, perché avvia un proxy verso l'API e riduce l'esposizione della chiave.

Quale modello gira dietro Codex CLI oggi?

Il modello predefinito è gpt-5.6-sol con ragionamento medio, e si cambia in sessione con /model oppure una volta per tutte nel file di configurazione. La famiglia GPT-5.6 uscita a luglio 2026 comprende tre modelli chiamati Sol, Terra e Luna, e su Codex gli utenti gratuiti e Go usano Terra mentre i piani a pagamento accedono agli altri e ai livelli di ragionamento più alti.

Il 31 agosto 2026 GPT-5.4 e GPT-5.4 mini vengono dismessi su Codex per chi accede tramite ChatGPT, con Terra come sostituto del primo e Luna del secondo, quindi un config.toml committato mesi fa con il modello fissato a mano smette di funzionare entro fine mese. Sui costi dei piani trovi i listini verificati e il criterio di scelta in un pezzo dedicato.

Quando conviene lasciar perdere Codex CLI?

Conviene lasciar perdere quando il lavoro è esplorativo, perché un agente da terminale rende al massimo sui task specificati fino in fondo come un aggiornamento di dipendenze o una modifica meccanica ripetuta su molti file. E se lavori già dentro un flusso strutturato con le fasi separate il guadagno arriva dal processo più che dalla riga di comando che esegue.

Domande frequenti

Codex CLI è gratis o serve un abbonamento?

Il codice è aperto con licenza Apache-2.0 e il repository raccoglie oltre 105.000 stelle su GitHub, e la CLI in sé non si paga. Quello che si paga è l'accesso ai modelli, incluso in tutti i piani ChatGPT compreso quello gratuito, dove il modello disponibile su Codex è Terra. In alternativa ti autentichi con una chiave API e paghi a consumo.

Che differenza c'è tra sandbox e approvazioni in Codex CLI?

La sandbox è un confine tecnico imposto dal sistema operativo e definisce dove l'agente può scrivere e se raggiunge la rete, mentre la politica di approvazione definisce quando si ferma a chiederti il permesso. Sono indipendenti, quindi puoi avere una sandbox permissiva con approvazioni frequenti oppure il contrario.

Codex CLI funziona anche su Windows?

Funziona su Windows con un binario nativo, installabile dallo script PowerShell ufficiale oppure da npm. La differenza pratica riguarda la sandbox, perché il confinamento su WSL2 passa da bubblewrap e richiede i namespace utente non privilegiati.

Come si aggiorna Codex CLI all'ultima versione?

Si aggiorna con lo stesso canale usato per installarlo, con npm install -g @openai/codex, brew upgrade --cask codex oppure una nuova esecuzione dello script ufficiale. La versione stabile mentre scrivo è la 0.147.0 del 7 agosto 2026, e in parallelo esiste una linea alpha che conviene evitare se il terminale lo usi per lavorare.