Codex CLI codex exec: automatizzare Codex in CI e negli script
Uso Codex CLI tutti i giorni in modalità interattiva, ma il vero salto arriva quando devo farlo girare senza stare davanti allo schermo: dentro una pipeline di CI, in un cron notturno, in uno script che incatena più comandi. Per questo esiste il comando codex exec, la modalità non interattiva di Codex: gli passo un task, lui lo esegue una volta sola ed restituisce solo il messaggio finale su stdout, mentre il progresso scorre su stderr. In questo articolo guardo cosa fa codex exec sotto il cofano, come ne rendo l'output leggibile da una macchina e il percorso che seguo per usarlo in automazione senza dare troppi permessi.
Cosa fa codex exec e perché esce dal terminale
Il codex di tutti i giorni apre una TUI, l'interfaccia interattiva in cui dialogo con l'agente. codex exec fa l'opposto: esegue un singolo compito in modo non interattivo e termina, senza chiedermi nulla a metà strada. È il primitivo giusto per CI/CD, cron e script, dove non c'è nessuno davanti allo schermo a confermare.
La differenza pratica che conta di più è come Codex separa i flussi di output: mentre lavora manda il progresso su stderr, e alla fine stampa solo il messaggio dell'agente su stdout. Così posso reindirizzare o incatenare il risultato senza che il rumore del processo lo sporchi.
Un esempio che uso spesso è codex exec "genera le release notes degli ultimi 10 commit" con l'output mandato dritto in un file. Funziona anche al contrario: se gli do dei dati in pipe insieme a un prompt, Codex tratta il prompt come istruzione e ciò che arriva da stdin come contesto aggiuntivo.
Un output che uno script può leggere: JSON, file e schema
In automazione il messaggio in prosa non basta: mi serve qualcosa che un programma sappia leggere. Per questo codex exec ha il flag --json, che trasforma stdout in un flusso JSON Lines — un evento per riga: avvio del thread, inizio e fine del turno, esecuzioni di comandi, modifiche ai file, chiamate ai tool MCP. Ogni cambiamento di stato diventa una riga JSON che posso filtrare con strumenti come jq.
Quando mi interessa solo la risposta finale uso -o (cioè --output-last-message) per scriverla su file, continuando comunque a vederla a video. E se a valle ho bisogno di campi stabili — un riepilogo, un report di rischio, dei metadati — passo uno schema con --output-schema: Codex garantisce che la risposta finale rispetti quel JSON Schema.
È la parte che cambia tutto rispetto al copia-incolla: con uno schema il risultato dell'agente diventa strutturato e prevedibile, quindi incatenabile con lo step successivo della pipeline senza parsing fragile.
- 01Passo il taskLancio codex exec con il prompt come argomento, oppure glielo do via stdin da un comando precedente.
- 02Sandbox in sola letturaDi default Codex lavora in lettura: ispeziona il repo senza modificarlo, finché non alzo io i permessi.
- 03Progresso su stderrMentre ragiona ed esegue comandi manda l'avanzamento su stderr, separato dal risultato finale.
- 04Risultato su stdoutAlla fine stampa solo il messaggio finale (o JSON con --json), pronto da reindirizzare al passo dopo.
Fonte: documentazione ufficiale OpenAI Codex — Non-interactive mode.
Permessi minimi: la sandbox e la sicurezza in automazione
La regola che mi sono dato in automazione è una sola: dare il minimo dei permessi necessari. Di default codex exec gira in una sandbox in sola lettura, e va benissimo per i task di analisi. Quando serve che modifichi i file alzo a --sandbox workspace-write; solo in un ambiente isolato e controllato — un runner di CI usa e getta — arrivo a --sandbox danger-full-access.
Il vecchio --full-auto è ormai deprecato e stampa un avviso: nei nuovi script preferisco sempre il flag esplicito --sandbox workspace-write, che dice nero su bianco cosa l'agente può fare. Per ambienti blindati esistono anche --ignore-user-config, che evita di caricare il config.toml personale, e --ignore-rules, che salta le policy locali.
Due paletti utili da conoscere. Codex pretende di girare dentro un repository Git per non fare danni irreversibili, e se davvero so che è sicuro lo forzo con --skip-git-repo-check. Sull'autenticazione: in CI non espongo mai la chiave a livello di job — su GitHub Actions uso la Codex GitHub Action, altrove passo CODEX_API_KEY inline solo per quella singola invocazione.
Interattivo o codex exec? Come scelgo
La domanda che mi faccio è semplice: c'è una persona che guarda il risultato e reagisce, oppure no?. Se sto esplorando, facendo refactoring guidato o discutendo un'architettura, resto nel codex interattivo. Se il task è ripetibile e parte da solo — un controllo pre-merge, un riassunto notturno, una fix automatica — allora è lavoro per codex exec.
Non sono alternative in conflitto: li uso negli stessi progetti, in momenti diversi. L'interattivo è la mia officina; codex exec è il braccio che mando in pipeline quando il lavoro è già chiaro e voglio che si ripeta uguale, mille volte, senza di me.
codex — interattivo
- Apre la TUI e dialoga con me
- Chiede conferma sulle azioni a rischio
- Ideale per esplorare, fare refactoring, decidere
- C'è una persona che guida e reagisce
codex exec — non interattivo
- Esegue un task una volta sola ed esce
- Progresso su stderr, risultato su stdout
- Ideale per CI, cron, script ripetibili
- Nessuno davanti: permessi e schema decisi prima
Il flusso che seguo per mettere codex exec in pipeline
Quando porto un task da interattivo ad automatico parto sempre piccolo e a permessi minimi, poi allargo solo se serve. L'obiettivo non è "Codex fa tutto da solo", ma un passo affidabile che si incastra nel resto della pipeline.
Il mini-playbook che applico, in ordine:
- Comincio in sola lettura: faccio girare il task di analisi senza permessi di scrittura finché l'output non è quello che mi aspetto.
- Rendo l'output macchina-leggibile con --json per gli eventi, o --output-schema quando a valle servono campi stabili.
- Incateno con lo stdin: mando log o test in pipe a codex exec e ne uso il risultato nel passo successivo, ad esempio per un riepilogo del fallimento.
- Riprendo quando serve con codex exec resume --last, utile nelle pipeline a due stadi: prima analizza, poi corregge.
- Proteggo le credenziali: su GitHub Actions uso la Codex GitHub Action, mai la chiave a livello di job.
Domande frequenti su comando codex exec
codex exec e il codex interattivo sono la stessa cosa?
No. Il codex interattivo apre la TUI e dialoga con me, chiedendo conferma sulle azioni a rischio; codex exec esegue un singolo task in modo non interattivo e termina. Uso l'interattivo per esplorare e decidere, codex exec quando il lavoro è ripetibile e deve partire senza di me, in CI o in uno script.
Come ottengo da codex exec un output che uno script può leggere?
Con il flag --json trasformo stdout in un flusso JSON Lines, un evento per riga. Se mi serve solo la risposta finale la scrivo su file con -o; se a valle servono campi stabili impongo un JSON Schema con --output-schema, così il risultato è strutturato e prevedibile invece che prosa libera.
codex exec può modificare i file del mio repository?
Solo se glielo permetto. Di default gira in una sandbox in sola lettura. Per fargli scrivere alzo a --sandbox workspace-write, e riservo danger-full-access ad ambienti isolati come un runner di CI usa e getta. Codex inoltre pretende un repository Git, così le modifiche restano tracciabili e reversibili.
Come gestisco l'autenticazione in CI senza esporre la chiave API?
Non metto mai la chiave come variabile a livello di job. Su GitHub Actions uso la Codex GitHub Action, che avvia un proxy e riduce l'esposizione della chiave. In altri ambienti passo CODEX_API_KEY inline solo per la singola invocazione di codex exec, evitando che altro codice nello stesso processo possa leggerla.
Parliamone
Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.