OpenAI Codex: installazione, accesso e primi passi

La parola “Codex” nei risultati di ricerca indica tre cose diverse e, di solito, chi la cerca per la prima volta non capisce cosa ha trovato. C’era un modello Codex, ritirato nel 2023; oggi il nome appartiene a un programma agente, e nella mischia ci sono un’altra dozzina di prodotti con lo stesso nome.

Qui parlo di un solo Codex: l’agente di programmazione di OpenAI. Cosa fa, dove funziona, quanto costa, come installarlo in cinque minuti e cosa dice OpenAI sui Paesi. È tutto basato sulla documentazione ufficiale, con link per ogni dato alla fine.

Altri materiali sulla configurazione degli strumenti sono nella documentazione Ailoot.

Che cos’è OpenAI Codex?#

Confrontalo con una normale chat. In chat copi un pezzo di codice, lo incolli, ottieni una risposta e poi la copi di nuovo. Un agente funziona diversamente: descrivi un’attività in linguaggio naturale e lui apre i file pertinenti nella cartella del progetto, apporta modifiche, esegue controlli e ti mostra il risultato.

OpenAI lo descrive in una riga nel suo repository:

Localmente significa che il programma viene scaricato sulla tua macchina, dove può vedere i tuoi file ed eseguire comandi nella tua cartella. Solo la richiesta al modello viene inviata al cloud.

Il codice open source è su GitHub con licenza Apache-2.0. Al 1° agosto 2026, il repository ha 103.000 stelle e l’ultima versione, 0.146.0, è stata pubblicata il 29 luglio. Gli aggiornamenti escono quasi ogni giorno, quindi molto probabilmente la tua versione sarà già diversa.

In cosa Codex nel 2026 è diverso dal vecchio Codex che è stato ritirato?#

Spesso vengono confusi perché entrambi i prodotti sono ufficiali e provengono da OpenAI. A distinguerli sono le date.

Il primo era una famiglia di modelli: code-davinci-001, code-davinci-002, code-cushman-001, code-cushman-002. Facevano una sola cosa: completare il codice per te, e alimentavano la prima versione di GitHub Copilot. Nell’elenco dei modelli ritirati di OpenAI, tutti e quattro compaiono su una sola riga: annunciati il 20 marzo 2023, ritirati il 23 marzo, con gpt-4o come sostituto consigliato.

Il secondo è un programma che si installa sul computer. Il pacchetto @openai/codex è comparso nel registro npm il 16 aprile 2025. Il modello al suo interno viene sostituito nel tempo con uno più recente, mentre il programma rimane lo stesso.

Qualsiasi istruzione su Codex precedente all’aprile 2025 descrive un prodotto ritirato. Se trovi materiale che definisce Codex un modello e suggerisce di richiamarlo tramite code-davinci-002, chiudilo.

Dove funziona Codex: nel terminale, nell’editor, nel browser o nell’app?#

Non devi scegliere tra un ambiente e l’altro. L’accesso è lo stesso, così come l’account. Cambia solo il luogo in cui ti è più comodo lavorare.

L’estensione funziona diversamente con Xcode e JetBrains rispetto agli altri editor:

Il cloud funziona diversamente dagli altri quattro ambienti. L’attività viene inviata a un container OpenAI, dove viene estratta una copia del repository da GitHub. L’agente lavora senza usare il tuo computer e, in seguito, puoi esaminare il risultato e decidere se integrare le modifiche nella tua copia. La configurazione richiede tre passaggi: collegare GitHub, creare un ambiente con le dipendenze necessarie e assegnare un’attività.

Se accedi con una chiave API, funzionano il terminale, l’editor e l’app. Il cloud non è disponibile con una chiave, così come le funzioni ad esso collegate, per esempio la revisione automatica del codice e l’avvio di attività da Slack. Per usarle devi accedere con un account ChatGPT.

Quale modello viene eseguito dentro Codex?#

OpenAI riassume così:

Accanto al modello c’è un secondo controllo: il livello di ragionamento. Ha quattro impostazioni: Low (chiamata Light nell’app e nell’editor), Medium, High e Extra High. OpenAI consiglia di usare il livello più basso che consente di ottenere il risultato desiderato e di aumentarlo quando un’attività richiede pianificazione.

Al di sopra ci sono altre due modalità. Max concede al modello più tempo per un’attività. Ultra suddivide il lavoro in parti e le assegna a subagenti in parallelo. La documentazione afferma chiaramente che la maggior parte delle attività non richiede né l’una né l’altra.

C’è anche un’opzione separata, gpt-5.3-codex-spark: una versione di ricerca per iterazioni rapide, disponibile solo con il piano Pro.

Scegliere il modello e il livello di ragionamento è già context engineering: decidi quanto deve ragionare l’agente e quali informazioni portare nell’attività. La combinazione si basa su tre pilastri: clone AI (la tua metodologia all’interno dell’agente), Second Brain (la struttura delle conoscenze sul progetto) e context engineering. Senza questa combinazione, l’agente AI inizia a inventare cose.

Quanto costa Codex e cosa comprendono i piani?#

Ho verificato i prezzi sulla pagina ufficiale dei prezzi il 1° agosto 2026.

Con la fatturazione mensile, Business costa $25 per postazione anziché $20.

Passiamo ai limiti. OpenAI non indica un solo numero fisso:

Invece di un solo numero, OpenAI pubblica un intervallo: quanti messaggi puoi inviare nell’arco di cinque ore lavorando sul tuo computer. I dati sono gli stessi per Plus e Business:

Con il piano Pro da $100, tutti i valori sono moltiplicati per cinque; con quello da $200, per venti. Oltre alla finestra di cinque ore, OpenAI menziona anche limiti settimanali, ma non ne pubblica i valori specifici.

L’intervallo di dieci volte per un singolo modello ha una spiegazione semplice. Un messaggio può consumare l’uno o il dieci percento della disponibilità giornaliera: conta la quantità di lavoro svolto, mentre il numero di richieste ha poca importanza. In Limiti di Claude Pro e Max ho spiegato in dettaglio come vengono usati i token, con Claude come esempio: il meccanismo è esattamente lo stesso.

Quando esaurisci il limite, hai tre opzioni: acquistare crediti aggiuntivi senza cambiare piano, passare a un modello più leggero oppure avviare una sessione con una chiave API e pagare i token man mano che li usi.

Quali restrizioni regionali si applicano a Codex?#

OpenAI pubblica l’elenco ufficiale dei Paesi e territori supportati. La Bielorussia non è nell’elenco. Kazakistan, Armenia, Georgia, Turchia, Serbia e Ucraina sono presenti.

La formulazione riportata sulla stessa pagina:

Installare ed eseguire il programma è una cosa; accedere al modello è un’altra. Il controllo del Paese avviene all’accesso: sia l’accesso tramite ChatGPT sia quello con una chiave API richiedono un account OpenAI.

Le segnalazioni su GitHub mostrano l’aspetto di un rifiuto legato al Paese. Nel gennaio 2026, uno sviluppatore venezuelano ha scritto che usava Codex 0.88.0 in PowerShell e riceveva lo stesso errore a ogni tentativo:

{
  "error": {
    "code": "unsupported_country_region_territory",
    "message": "Country, region, or territory not supported",
    "type": "request_forbidden"
  }
}

Il codice unsupported_country_region_territory e lo stato 403 indicano un rifiuto legato al Paese. Se lo vedi, significa che non hai sbagliato nulla durante l’installazione e che Node non c’entra.

C’è un secondo ostacolo che non viene affatto descritto nella documentazione, ma che nella pratica si presenta spesso: la verifica del numero di telefono. La segnalazione “La verifica del numero di telefono non funziona” ha 206 commenti; una seconda, relativa a un vecchio numero non più accessibile e impossibile da sostituire, è aperta da giugno 2026 e ha 71 commenti. La storia è sempre la stessa: ChatGPT funziona nel browser con lo stesso account, ma Codex chiede la verifica del telefono e non c’è modo di aggirarla. OpenAI non pubblica un elenco dei Paesi i cui numeri di telefono accetta, quindi non c’è modo di verificare in anticipo se il tuo è accettato.

Non tratterò metodi alternativi: questo articolo spiega come funziona lo strumento.

Anche Anthropic pubblica il proprio elenco dei Paesi supportati e il funzionamento è lo stesso. I materiali che presentano uno strumento come «consentito» e l’altro come «bloccato» fuorviano i lettori: dal punto di vista formale, si trovano nella stessa situazione. Entrambi gli elenchi possono cambiare, quindi controlla le versioni aggiornate.

Come installare Codex: istruzioni passo passo#

La parte tecnica comincia qui, per chi ha già un account OpenAI attivo.

1. Installa il programma

   Scegli il metodo adatto al tuo sistema. In seguito, usa lo stesso metodo per aggiornare il programma alla versione più recente.

2. Apri la cartella del progetto

   L’agente lavora nella cartella da cui lo hai avviato. Raggiungila prima di eseguire il primo comando.

3. Accedi al tuo account

   La prima volta che esegui codex, ti verrà proposto di accedere. Si aprirà il browser e, dopo l’accesso, tornerai al terminale.

4. Assegnagli la prima attività

   Descrivi in linguaggio naturale ciò di cui hai bisogno. Inizia con qualcosa di innocuo, per esempio chiedigli di descrivere il progetto.

Comando di installazione per macOS e Linux:

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

Su Windows, usa lo stesso programma di installazione tramite PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Se hai già Node, puoi installarlo tramite npm:

npm install -g @openai/codex

Homebrew funziona su macOS. Assicurati di usare --cask; senza, installerai la cosa sbagliata:

brew install --cask codex

Su Linux e WSL2, la sandbox si basa su bubblewrap, che devi installare in anticipo:

sudo apt install bubblewrap

Su Fedora e sistemi correlati, usa sudo dnf install bubblewrap. Inoltre, WSL versione 1 era supportato fino alla versione 0.114; a partire dalla 0.115, la sandbox è passata a bubblewrap e WSL1 non ha più funzionato. Su Windows, invece, tutto funziona anche senza WSL, usando la sandbox integrata.

Cosa fare al primo avvio?#

Per iniziare, vai nella cartella del progetto e digita codex: si aprirà una sessione. Poi descrivi l’attività in linguaggio naturale, senza sintassi speciale.

Cinque comandi per i primi minuti:

1. /status - il modello, la politica di approvazione e le cartelle che l’agente considera la propria area di lavoro.
2. /permissions - la modalità di accesso attuale e come passare da una modalità all’altra.
3. /model - cambia il modello e il livello di ragionamento.
4. /init - crea un file AGENTS.md che descrive il progetto; ne parleremo nella prossima sezione.
5. /review - una revisione separata delle modifiche, senza modificare file.

Oltre al semplice codex, ci sono tre comandi utili per il terminale:

codex resume                    # torna alla conversazione precedente in questa cartella
codex exec "fix the tests"      # esecuzione singola senza dialogo, per gli script
codex --image screenshot.png    # allega un’immagine all’attività

Sia nella documentazione del terminale sia in quella dell’estensione, OpenAI ripete lo stesso consiglio: esegui un commit prima e dopo un’attività. L’agente modifica i file da solo e vuoi poter annullare le modifiche con un solo comando fin dal primo giorno.

Come spieghi il tuo progetto a Codex con AGENTS.md?#

L’ordine è rigoroso e la documentazione lo afferma nella primissima riga della sezione:

Per prima cosa, Codex legge il file globale ~/.codex/AGENTS.md, dove inserisci le abitudini valide per tutti i tuoi progetti. Poi legge i file presenti nel progetto: un file per cartella, dalla radice del repository fino alla cartella corrente. Li combina dall’alto verso il basso e un file più vicino prevale su uno più distante. Per esempio, una regola in services/payments ha la precedenza su una regola generale nella radice.

Un file semplice ha questo aspetto:

# AGENTS.md

## Come lavorare con questo progetto

- Esegui i test con `npm test`; non eseguirli un file alla volta.
- Installa i pacchetti con pnpm.
- Chiedimi prima di aggiungere una nuova dipendenza di produzione.
- Non toccare affatto la cartella `legacy/`.

Il limite è di 32 kilobyte per i file combinati. Superato quel limite, i file successivi semplicemente non vengono aggiunti e non ricevi alcun avviso. Un file AGENTS.md troppo grande consuma inoltre il limite a ogni esecuzione, perché il file intero viene inserito nel contesto.

Se conosci CLAUDE.md, il funzionamento ti sembrerà familiare: è la stessa tecnica con un nome diverso. Il file delle regole del progetto è la base di un Second Brain: l’agente apprende informazioni sul tuo lavoro prima ancora che tu abbia la possibilità di spiegargli qualcosa. Ho descritto come usare entrambi i file in un progetto in AGENTS.md e CLAUDE.md insieme.

Cosa fa Codex da solo e per cosa richiede approvazione?#

Queste due impostazioni vengono spesso confuse, quindi OpenAI ne spiega la differenza in una riga:

Impostare la revisione automatica lascia invariati i confini della cartella di lavoro. L’automazione elimina solo i clic: non cambia le autorizzazioni dell’agente.

L’app e l’editor hanno tre modalità di accesso. Ask for approval è sempre disponibile ed è la modalità iniziale consigliata. Approve for me e Full access devono prima essere abilitate nelle impostazioni.

Il terminale segue una logica propria: il programma controlla la cartella e propone un insieme di autorizzazioni adatto.

In modalità locale l’accesso alla rete è disattivato per impostazione predefinita. L’agente esegue comandi che ha ideato da solo, e nessuno vorrebbe consentirgli di raggiungere Internet per impostazione predefinita.

Anche all’interno della cartella di lavoro, in ogni modalità l’agente può leggere solo alcune posizioni: .git, .agents e .codex. Usa /status per vedere quali cartelle l’agente considera attualmente la propria area di lavoro.

C’è anche la modalità di accesso completo, attivabile con il flag --dangerously-bypass-approvals-and-sandbox. La documentazione la definisce a rischio più elevato e la contrassegna come “non consigliata”. Il nome del flag dice tutto; non ho altro da aggiungere.

Codex o Claude Code: quale scegliere?#

La differenza tra gli strumenti è minore di quanto si possa dedurre dalle discussioni online. Entrambi leggono il progetto e modificano i file da soli, chiedendo prima di uscire dalla cartella.

Per iniziare, è più semplice considerare cosa paghi già. Se hai un abbonamento ChatGPT, Codex è già incluso e non devi pagare a parte. Ho realizzato un confronto dettagliato con misurazioni in un articolo dedicato a Codex e Claude Code a confronto; se vuoi trasferire le impostazioni di lavoro da uno all’altro, c’è una guida alla migrazione.

Quali sono i problemi più comuni al primo avvio?#

Questo elenco si basa sulle segnalazioni nel repository del progetto. Non ci sono supposizioni: ogni elemento deriva dall’esperienza di qualcuno che ci si è imbattuto.

1. È stato installato il pacchetto sbagliato. npm install -g codex senza prefisso installa un generatore di siti statici del 2011. Il pacchetto corretto è @openai/codex.
2. bubblewrap non è installato. Senza bubblewrap su Linux e WSL2, la sandbox non si avvia. Codex passa alla propria alternativa integrata e segnala il problema all’avvio. Basta installarlo con un comando.
3. Accesso negato per il Paese. Il codice unsupported_country_region_territory e lo stato 403 compaiono al momento dell’autenticazione. Non dipende dall’installazione.
4. Viene richiesta la verifica del telefono. Non succede a tutti e il problema non è descritto nella documentazione. Non esiste un metodo ufficiale per sostituire un numero a cui non si ha più accesso; la segnalazione è aperta da giugno 2026.
5. I limiti di utilizzo si esauriscono prima del previsto. La segnalazione “I token si esauriscono molto rapidamente” è la più discussa dell’intero repository, con 627 commenti. Può essere utile passare a un modello più leggero e ridurre il livello di ragionamento.

La lingua dell’interfaccia non influisce sul lavoro dell’agente: non è necessario che la lingua dell’attività coincida con quella dell’interfaccia.

Cosa fare dopo#

La prima ora con un agente è sempre dedicata alla stessa cosa: capire fin dove può spingersi da solo. Puoi scoprirlo solo con il tuo progetto; un esempio nella documentazione non te lo dirà.

Ecco l’ordine che consiglio per iniziare:

1. Installa il programma e accedi a un account OpenAI attivo.
2. Apri una cartella di progetto reale ed esegui codex.
3. Controlla /status e /permissions, seleziona esplicitamente sola lettura per una semplice ispezione e verifica la modalità attiva prima di chiedere come sia organizzato il progetto.
4. Crea un commit e assegnagli la prima attività di modifica.
5. Scrivi un file AGENTS.md di tre righe e confronta le risposte dell’agente prima e dopo.

Clone AI + Second Brain + Context Engineering: trovi altri materiali su come lavorare con gli strumenti nella documentazione Ailoot.