Codex CLI: come iniziare e configurarlo per il team

Dedica i primi 15 minuti alla configurazione, se hai già un progetto funzionante e un account abilitato. L’installazione, l’accesso o una suite di test lenta possono richiedere più tempo. Un buon primo risultato è una piccola modifica verificata, oppure una spiegazione precisa di ciò che la blocca. Comandi verificati l’11 ottobre 2026.

Come installare Codex CLI e portare a termine il primo task

Codex lavora all’interno del progetto: può esaminare i file, modificarli ed eseguire gli strumenti installati sul computer. Immaginalo come un collaboratore con un banco di lavoro separato. Tu definisci l’attività e i limiti; la decisione di integrare il risultato nel prodotto resta tua. Guida di OpenAI alla CLI

Dal minuto 0 al minuto 3: scegli un metodo di installazione

Su macOS o Linux, il comando per l’installer autonomo è:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Puoi scegliere un’alternativa più adatta al tuo ambiente. Usa un solo metodo, così saprai anche come gestire gli aggiornamenti.

Per Windows, la documentazione indica questo comando esatto da eseguire in una nuova finestra di PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex".

Questi sono i metodi riportati nella documentazione attuale della CLI e nel repository ufficiale. Prima di avviare Codex, apri nel terminale la directory del progetto.

Dal minuto 3 al minuto 5: scegli l’accesso con ChatGPT o con una chiave API

Per la prima sessione interattiva, usa l’accesso con ChatGPT se il tuo piano e il tuo workspace lo consentono. Esegui codex login e completa la procedura nel browser. Anche avviando codex senza aver già effettuato l’accesso compare l’opzione Sign in with ChatGPT.

Scegli l’autenticazione con chiave API quando vuoi usare il tuo account OpenAI Platform, per esempio per flussi di lavoro programmatici. Se OPENAI_API_KEY è già disponibile nell’ambiente della shell, il comando documentato per macOS/Linux è printenv OPENAI_API_KEY | codex login --with-api-key. Non salvare la chiave nei file del repository.

Esegui codex login status per verificare quale metodo è attivo. È una distinzione importante per il team: l’autenticazione con ChatGPT segue i controlli del workspace ChatGPT, mentre quella tramite API segue i controlli dell’organizzazione API. Guida all’autenticazione

Costi: l’accesso con ChatGPT utilizza quanto incluso nel piano abilitato; l’uso tramite chiave API viene fatturato separatamente su OpenAI Platform, alle tariffe API. Per confrontare i piani, consulta la nostra guida ai prezzi di Codex. Durante una prova con il team, confronta il tempo necessario per svolgere l’attività a mano con quello dedicato a prompt, revisione e correzioni, poi sottrai il costo aggiuntivo di utilizzo dal valore del tempo effettivamente risparmiato. Una prima bozza più rapida conviene solo se diminuisce il lavoro complessivo necessario per accettarla. La distinzione di OpenAI tra autenticazione e fatturazione

Dal minuto 5 al minuto 8: esamina il progetto prima di modificarlo

Prima di iniziare, crea un punto di ripristino in Git. Dalla shell, nella directory del progetto, avvia una sessione di analisi con il comando documentato codex --sandbox read-only --ask-for-approval on-request.

Assegna un’indagine circoscritta. Puoi adattare al progetto questo prompt di esempio:

È un suggerimento su come impostare il lavoro, non un comando speciale di Codex. Leggi la risposta e verifica che abbia individuato la parte giusta dell’applicazione. La sandbox in sola lettura consente l’analisi e l’esecuzione di comandi entro i suoi limiti; le azioni che li superano possono richiedere un’approvazione. Guida ad approvazioni e sandbox

Dal minuto 8 al minuto 12: autorizza una piccola modifica

Quando sei pronto, usa /permissions per consentire le modifiche nel workspace. Per avviare una nuova sessione, la combinazione documentata è codex --sandbox workspace-write --ask-for-approval on-request.

Definisci poi un criterio di accettazione:

Parti da un risultato che puoi valutare rapidamente. Un test su un comportamento noto è un primo incarico migliore di una richiesta generica di migliorare l’architettura.

Dal minuto 12 al minuto 15: controlla il diff e i risultati

Usa /diff per esaminare la patch e /review per richiedere una revisione. Controlla l’output effettivo dei test, i file modificati e il rispetto del criterio di accettazione. Esegui il commit solo dopo la tua revisione. Questi comandi con la barra iniziale vanno usati nella sessione di Codex, non al prompt della shell. Riferimento dei comandi CLI

Scegli il modello dopo aver stabilito un termine di confronto

Inizia con il modello disponibile nella sessione, poi usa /model per sceglierne un altro o regolare l’intensità del ragionamento. L’esempio di avvio attualmente riportato da OpenAI è codex --model gpt-6.1-sol.

La raccomandazione attuale è GPT-6.1 Sol per le attività di programmazione complesse, quando account e client vi hanno accesso, e GPT-6 Luna per attività mirate e ripetibili. Un ragionamento più approfondito può aiutare nelle analisi difficili, ma richiede anche più tempo e consuma più token. Per confrontare i risultati, mantieni costanti il task iniziale e l’impostazione dell’intensità di ragionamento. Guida ai modelli di Codex

Durante l’introduzione di Codex nel team, annota il modello usato insieme all’attività svolta e all’esito dei test. Selezionare il nome di un modello non dà all’account il diritto di accedervi.

Configura separatamente sandbox e approvazioni

La sandbox definisce a cosa possono accedere i comandi. La policy di approvazione stabilisce quando Codex deve chiedere il permesso prima di agire. Puoi pensare alla sandbox come alle pareti di una stanza di lavoro e alla policy di approvazione come al permesso di aprire una porta.

Per il lavoro interattivo, usa on-request: le azioni consentite all’interno della sandbox possono procedere, mentre quelle che richiedono un accesso più ampio possono far comparire una richiesta di approvazione. never significa che Codex non può chiedere approvazioni; non rimuove la sandbox. Un’azione bloccata può restare tale.

Definire un perimetro di scrittura non significa ricevere una richiesta prima di ogni modifica. Con workspace-write e on-request, Codex può modificare i file del workspace ed eseguire automaticamente i comandi consentiti. Controlla le impostazioni attive con /permissions. Il funzionamento di sandbox e approvazioni secondo OpenAI

Se un vecchio modello di configurazione del team contiene approval_policy = "untrusted", aggiornalo: OpenAI ha ritirato questa impostazione esplicita e avverte che può impedire l’avvio. Anche il precedente metodo codex exec --full-auto è deprecato. Usa le impostazioni documentate per sandbox e approvazioni. Indicazioni attuali per la migrazione

Raccogli le regole di lavoro in AGENTS.md

Usa AGENTS.md per evitare di spiegare ogni volta come funziona il repository. Codex legge queste istruzioni all’avvio di un’esecuzione. /init può generare una struttura iniziale, che un responsabile del repository dovrebbe rivedere prima che il team inizi a usarla.

Un file utile per il repository risponde a quattro domande:

• Come si installano le dipendenze e si avvia il progetto?
• Quali test e controlli vanno eseguiti per una modifica?
• Quali directory contengono file generati o richiedono particolare attenzione?
• Cosa deve includere il resoconto finale, per esempio il comportamento modificato, i test eseguiti e gli errori ancora irrisolti?

Scrivi i comandi e le convenzioni effettivamente usati, evitando una lista generica di desideri. Conserva le preferenze personali in ~/.codex/AGENTS.md; salva nella radice del progetto e versiona con un commit le istruzioni condivise del repository.

Codex carica le istruzioni globali, poi percorre le directory dalla radice del progetto fino alla directory corrente. Le istruzioni più locali prevalgono su quelle lette in precedenza; nella stessa directory, AGENTS.override.md prevale su AGENTS.md. Dopo aver modificato le istruzioni, riavvia la sessione e chiedi a Codex di riassumere quelle che ha caricato. Regole di individuazione di AGENTS.md

Considera questo file un manuale per chi contribuisce al progetto. Per imporre restrizioni tecniche, usa la configurazione e i requisiti gestiti centralmente.

Mantieni config.toml essenziale e facile da verificare

Salva le impostazioni personali predefinite in ~/.codex/config.toml. Inserisci quelle condivise del progetto in .codex/config.toml, che Codex carica solo per i progetti attendibili. Queste impostazioni usano TOML, un formato testuale per parametri identificati da un nome.

Questa configurazione iniziale combina i valori riportati nella guida di OpenAI. Includi la riga del modello solo se il tuo account può accedervi:

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

I flag della CLI e le impostazioni passate con --config prevalgono sulla configurazione del progetto. Le impostazioni di un progetto attendibile prevalgono sui profili selezionati e sulle impostazioni personali predefinite. I requisiti dell’organizzazione possono limitare ciò che è consentito, indipendentemente da queste impostazioni. Nozioni di base sulla configurazione

web_search = "cached" seleziona risultati di ricerca web memorizzati nella cache. È un’impostazione distinta dall’accesso alla rete per i comandi della shell. Il download di una dipendenza può richiedere un’approvazione anche quando Codex dispone di uno strumento di ricerca web. Chiarisci questa distinzione nelle note per chi entra nel team, invece di ampliare i permessi ogni volta che un comando fallisce.

Aggiungi un server MCP quando serve davvero

MCP, abbreviazione di Model Context Protocol, collega Codex a strumenti e informazioni di contesto esterne. Un server locale viene eseguito come processo; un server remoto si raggiunge tramite un indirizzo HTTP. Aggiungine uno quando un’attività richiede informazioni o azioni che il repository non può fornire.

L’esempio nella documentazione di OpenAI è codex mcp add context7 -- npx -y @upstash/context7-mcp. Avvia un server di documentazione tramite npx, che deve quindi essere disponibile. Esegui codex mcp list per vedere i server configurati, poi usa /mcp all’interno di una sessione per controllare le connessioni attive. Per un server che supporta OAuth, usa codex mcp login <server-name>, sostituendo il segnaposto con il nome assegnato al server nella configurazione.

La configurazione del server va inserita sotto [mcp_servers.<server-name>], nello stesso sistema di configurazione TOML. Il team può limitare gli strumenti esposti con enabled_tools e disabled_tools; l’elenco degli strumenti vietati viene applicato dopo quello degli strumenti consentiti. Parti dal più piccolo insieme di strumenti utile allo scopo. Configurazione e impostazioni MCP

Per la questione distinta delle risposte troppo lunghe degli strumenti, leggi il nostro approfondimento sui limiti dell’output MCP in Codex CLI. Collegare un server e controllare la quantità di output che restituisce sono due decisioni di configurazione diverse.

Usa i worktree per lavorare su copie separate del repository

Un worktree di Git offre a un’attività un checkout separato del repository. È utile per tenere le modifiche di un esperimento separate dai file su cui stai già lavorando.

Con la release 0.154.0, OpenAI ha introdotto i worktree gestiti per task della CLI, sessioni interattive e fork. L’implementazione li rende disponibili solo attivando la funzionalità sperimentale worktrees e ne limita l’uso alle sessioni locali. Abilitala con codex features enable worktrees, il comando documentato della CLI per attivare le funzionalità, poi avvia Codex con codex --worktree. Note di rilascio, implementazione dei worktree interattivi, comandi per le funzionalità

All’interno di una sessione che li supporta, /worktree permette di avviare una nuova conversazione o crearne un fork in un checkout gestito. Il fork conserva la cronologia della conversazione; una nuova conversazione riparte da zero. Queste opzioni richiedono che la funzionalità sia abilitata e che il repository Git sia locale. Comandi di sessione per i worktree

Metti in conto di occuparti personalmente della revisione, dell’integrazione e della pulizia finale. L’implementazione della CLI lascia disabilitata la pulizia automatica dei checkout gestiti che crea. Inoltre, un checkout separato non sostituisce le impostazioni della sandbox né la revisione prima del merge. Ciclo di vita dei checkout gestiti

Quando sei pronto per lavorare su attività parallele, consulta la nostra guida ai worktree di Codex CLI. Per un primo incarico di scrittura di test è sufficiente un solo checkout.

Sei attività utili per un piccolo team, in ordine di priorità

Quelli che seguono sono incarichi suggeriti, non promesse di produttività misurata. Parti da quelli il cui criterio di accettazione è più facile da verificare.

Codex non prende le decisioni di prodotto che mancano e non dimostra che una suite di test superata copra ogni rischio. I criteri di accettazione e la tua revisione restano parte del lavoro. Per una valutazione più ampia, leggi la nostra recensione di Codex; per confrontare le opzioni prima dell’acquisto, consulta Codex vs Claude Code.

Due strumenti mirati che un fondatore con competenze tecniche potrebbe creare

L’opportunità più promettente è un servizio di test di regressione per un singolo stack. L’offerta consiste in una patch di test già revisionata, rivolta a piccoli team con bug noti e una copertura dei test debole. La versione minima utile parte da un caso riproducibile, esegue un task circoscritto con Codex in un checkout separato e restituisce la patch insieme ai risultati dei test. La stima di DataForSEO per il mercato statunitense, rilevata l’11 ottobre 2026, è di 880 ricerche mensili per “automated software testing services.” È un indicatore dell’interesse per quel tipo di servizio, non della disponibilità ad acquistare questo prodotto. La difficoltà sta nel creare fixture affidabili e asserzioni significative; un test che si limita a ripetere l’implementazione aggiunge poco valore.

La seconda opzione è un assistente per la revisione del codice specifico per un repository. Un responsabile tecnico potrebbe pagare per revisioni che applicano le convenzioni documentate del team e restituiscono un elenco breve e verificabile di rilievi. Parti da un solo repository, dal suo AGENTS.md e da una procedura di revisione ripetibile. La stessa verifica della domanda stima 1,300 ricerche mensili negli Stati Uniti per “ai code review.” Il problema è distinguersi: Codex esegue già revisioni del codice, quindi il prodotto deve rendere i rilievi più pertinenti e ridurre i falsi allarmi. La generazione di test offre un primo risultato più concreto, perché il cliente può esaminare ed eseguire ciò che riceve.

Le domande più frequenti durante la configurazione

Lunedì, fai eseguire lo stesso piccolo task a un responsabile del repository insieme a due colleghi, annota l’impegno richiesto per revisione e correzioni e aggiorna le istruzioni condivise nei punti in cui il passaggio di consegne si inceppa. Amplia l’uso solo quando il team riesce a ripetere quel ciclo con sicurezza.

Se vuoi un flusso di lavoro sul repository costruito attorno a questi controlli, realizziamo sistemi AI per la produzione.