Come usare Codex: guida completa per iniziare con CLI, estensione IDE, Codex Cloud e app desktop

Quando usi Codex per la prima volta, non chiedergli subito di rifattorizzare tutto il progetto. Apri prima il repository e dagli una piccola attività che puoi verificare in circa 20 minuti.

Panoramica dei punti di ingresso

OpenAI Codex non è un singolo comando da terminale né un solo plugin per editor. È un coding agent utilizzabile da più punti di ingresso. Nella documentazione ufficiale troverai CLI, estensione IDE, Codex app e Codex web/cloud. Condividono la stessa capacità di base e lo stesso modello di autenticazione, ma sono adatti a lavori diversi.

Quattro punti di ingresso a confronto

Punto di ingresso	Che cos’è	Ideale per	Utente tipico	Vincolo principale
CLI	Un coding agent eseguito nel terminale locale	Repository locali esistenti, piccole modifiche, workflow da riga di comando	Utenti intensivi del terminale, utenti CI	Richiede un repository Git locale; le modifiche ai file sono visibili in locale
IDE Extension	Collaborazione con Codex nella sidebar dell’editor	Lavoro nell’editor corrente, context più breve tramite file aperti o codice selezionato	Utenti VS Code, Cursor, Windsurf e JetBrains	Dipende dall’ambiente dell’editor; il lavoro complesso può essere delegato a Cloud
Codex App	Un command center desktop	Più thread, worktree, automazioni, gestione Git	Utenti locali che gestiscono più attività in parallelo	macOS e Windows sono supportati; la disponibilità Linux va verificata sulla pagina ufficiale
Codex Cloud/Web	Un cloud agent collegato a GitHub	Repository remoti, PR, attività asincrone, lavoro lontano dalla macchina	Team e workflow su repository remoti	Gli workspace Enterprise possono richiedere admin setup

Autenticazione e differenze di funzionalità

Codex supporta due percorsi di autenticazione, ma le funzionalità disponibili cambiano.

Autenticazione	Punti di ingresso disponibili	Disponibilità delle funzioni Cloud	Uso più adatto
ChatGPT account (Plus/Pro/Business/Edu/Enterprise)	Tutti i punti di ingresso (CLI/IDE/App/Cloud)	Include GitHub code review, Slack e altre cloud-based features	Abbonati individuali e team
API key	CLI, SDK, IDE Extension	Non include GitHub code review, Slack e altre cloud-based features	CI, automazioni e workflow fatturati via API

Pricing, limiti d’uso e accesso esatto alle funzioni vanno controllati sulla pagina ufficiale del pricing e nella dashboard del tuo account. Se accedi con una API key e le funzioni Cloud non sono disponibili, è una differenza tra surface, non una configurazione rotta.

Punto di ingresso CLI

La CLI è un coding agent che gira nel terminale locale. Può leggere il codice dalla directory selezionata, modificare file, eseguire comandi e ispezionare i risultati, quindi funziona bene quando hai già un repository locale.

Definizione e casi d’uso della CLI

Il compito principale della CLI è lavorare dentro un repository locale: leggere codice, modificare file, eseguire test, eseguire lint, controllare errori e produrre un diff. Non devi avere il file aperto in un editor. Devi solo descrivere l’attività nel terminale.

La CLI è adatta quando:

• Hai già un repository Git locale.
• L’attività tocca più file o richiede verifica da riga di comando.
• Vuoi vedere le modifiche ai file in locale per git diff e commit.
• Usi CI o automazioni basate su script.

La CLI è meno adatta quando:

• Non hai ancora un repository locale e devi prima clonarlo.
• Vuoi modificare solo il file attualmente aperto, caso in cui l’estensione IDE è più comoda.
• Ti serve un workflow PR remoto, dove Cloud è più adatto.

Installazione e accesso della CLI

Installazione e accesso possono cambiare nel tempo, quindi considera questi passaggi come il flusso generale e controlla la pagina CLI ufficiale per i comandi esatti.

1. Scegli il metodo di installazione dalla pagina CLI ufficiale: la pagina ufficiale attuale offre un standalone installer. Articoli più vecchi possono citare l’installazione via npm, ma va considerata autorevole la pagina ufficiale corrente.
2. Eseguila la prima volta: dopo l’installazione, esegui codex e segui il flusso di accesso.
3. Scegli il metodo di accesso: puoi usare un ChatGPT account o una API key. Un ChatGPT account copre tutte le surface; una API key è limitata a CLI, SDK ed estensione IDE, senza funzioni Cloud.

La CLI supporta macOS, Windows e Linux. Su Windows, usa il PowerShell native sandbox o WSL2 in base alla guida ufficiale corrente.

Comandi CLI comuni

La CLI ha modalità interactive e non-interactive. Questi sono i sei comandi o gruppi di comandi che un principiante dovrebbe riconoscere per primi; i nomi possono cambiare, quindi controlla la CLI reference quando ti serve la sintassi esatta.

Comando	Scopo	Esempio
codex	Modalità interactive per lavorare in conversazione nel terminale	codex
codex exec	Modalità non-interactive per CI o script	codex exec "fix the CI failure"
codex login	Accedere o cambiare account	codex login
codex update	Aggiornare la CLI	codex update
codex doctor	Controllare configurazione dell’ambiente e problemi comuni	codex doctor
Flag comuni	Regolare permessi, modello, sandbox e approvazioni	--sandbox read-only, --model, --ask-for-approval

La CLI reference include altri comandi e flag, tra cui codex apply, codex cloud e codex app. Alcuni comandi possono avere livelli di maturità diversi. Da principiante, impara prima la modalità interactive e passa a codex exec quando ti serve automazione.

Prima attività con la CLI

La regola per la prima attività è semplice: scegli un repository esistente e dai a Codex un’attività che puoi verificare in circa 20 minuti.

Le best practice di OpenAI consigliano un prompt di qualità con quattro parti.

Parte del prompt	Significato	Esempio
Goal	Il risultato che vuoi	”Correggi il comando di installazione obsoleto nel README”
Context	Il contesto rilevante	”Questo è un progetto Node.js. Il README cita npm install, ma il progetto ora usa yarn.”
Constraints	Confini della modifica	”Modifica solo il README. Non cambiare altri file. Dopo la modifica, esegui node README-example.js per confermare che il comando funzioni.”
Done when	Condizione di verifica	”Il comando nel README è aggiornato e node README-example.js stampa l’output previsto.”

Buone prime attività:

• Correggere un comando o un link obsoleto nel README.
• Aggiungere un test mancante o correggere un test fallito.
• Correggere un piccolo bug con un messaggio di errore chiaro.
• Ripulire un commento TODO.
• Aggiungere una semplice annotazione di tipo a un modulo.

Evita prime attività che:

• Toccano secret o dati di produzione.
• Richiedono un grande refactor o una nuova funzionalità completa.
• Non hanno una condizione di accettazione chiara, come “ottimizza le prestazioni”.

Checklist di revisione della CLI

Dopo che la CLI termina, verifica il risultato in questo ordine.

1. Leggi il diff: esegui git diff nel terminale e conferma che la modifica corrisponda alla richiesta. Non fidarti solo del messaggio finale “done”.
2. Esegui i test: se il progetto ha test, esegui npm test o il comando pertinente.
3. Esegui lint o typecheck: se il progetto ha questi controlli, assicurati che non siano stati introdotti nuovi errori.
4. Controlla l’output dei comandi: se l’attività richiedeva un comando, conferma che l’output corrisponda al risultato atteso.
5. Tieni i secret lontani dalla prima attività: se un’attività tocca configurazioni sensibili, valuta se la modifica è necessaria prima di lasciare che un agent la applichi.

Fai commit o push solo dopo il superamento dei controlli. Se la modifica è sbagliata, ripristinala con Git, restringi il prompt e riprova.

Punto di ingresso IDE Extension

L’estensione IDE permette a Codex di lavorare nella sidebar dell’editor. È adatta quando stai già lavorando nell’editor. Il suo vantaggio è un context più corto e preciso: file aperti, codice selezionato e riferimenti espliciti @file, senza dover descrivere tutto il progetto in un prompt da terminale.

Definizione e casi d’uso dell’IDE

L’estensione IDE non sostituisce l’editor. Inserisce Codex come coding agent dentro il workflow dell’editor. Il context arriva dai file aperti, dagli snippet selezionati o dai file che indichi esplicitamente con @file, quindi può essere più precisa per modifiche locali.

L’estensione IDE è adatta quando:

• Stai lavorando in VS Code, Cursor, Windsurf o JetBrains.
• L’attività riguarda il file corrente o un piccolo gruppo di file collegati.
• Vuoi vedere le modifiche nell’editor mentre avvengono.
• Devi indicare un file specifico come context.

L’estensione IDE è meno adatta quando:

• Non usi un ambiente editor, caso in cui la CLI è più semplice.
• L’attività richiede lunga esecuzione in background, dove Cloud può subentrare.
• L’attività tocca molti file o flussi di comandi complessi, dove CLI o Cloud possono essere più adatti.

IDE supportati

L’estensione IDE supporta questi editor; controlla la pagina IDE ufficiale per la disponibilità corrente.

Editor	Note
VS Code	Supporto ufficiale
Cursor	Fork di VS Code compatibile con l’estensione VS Code
Windsurf	Fork di VS Code compatibile con l’estensione VS Code
JetBrains	Supporta Rider, IntelliJ, PyCharm, WebStorm e IDE collegati, secondo disponibilità ufficiale

Se lavori in Cursor o Windsurf, l’estensione Codex e le funzioni AI integrate dell’editor possono convivere. Codex è un altro coding agent a cui passare quando il lavoro lo richiede.

Installazione e accesso dell’IDE

Usa la pagina IDE ufficiale per i passaggi correnti.

1. Installa dal marketplace dell’estensione: cerca l’estensione Codex in VS Code, Cursor, Windsurf o JetBrains.
2. Accedi: usa un ChatGPT account o una API key. Un ChatGPT account copre tutte le surface; una API key non include le funzioni Cloud.

Context nell’IDE

Il valore principale dell’estensione IDE è il context dell’editor.

Tipo di context	Significato	Esempio
Open files	I file attualmente aperti sono disponibili come context	Apri example.tsx e Codex può ispezionarlo direttamente
Selected code	Lo snippet selezionato diventa context	Seleziona una funzione e chiedi a Codex di spiegarla o rifattorizzarla
Riferimento @file	Riferisci esplicitamente un altro file per nome	@example.tsx please check the component's type definitions
Reasoning effort	Regola quanto reasoning usa l’agent	low/medium/high; usa effort più alto per attività più difficili

L’estensione IDE supporta anche le modalità Chat, Agent e Agent Full Access. La differenza riguarda permessi e livello di automazione. Inizia con la modalità Agent predefinita, poi regola quando conosci i compromessi.

Delegare dall’IDE a Cloud

L’estensione IDE può delegare lavoro a Codex Cloud. Usala quando:

• L’attività può richiedere molto tempo.
• L’attività coinvolge un repository remoto.
• Devi allontanarti dalla macchina mentre il lavoro continua.
• Vuoi eseguire un’attività complessa in background e rivedere il risultato più tardi.

I comandi slash comuni possono includere i seguenti; i nomi possono cambiare, quindi controlla la pagina delle funzioni IDE.

Comando	Scopo
/cloud	Delegare l’attività corrente a Cloud
/local	Eseguire l’attività in locale
/review	Fare review del base branch, delle modifiche non committate o di un commit
/status	Controllare lo stato dell’attività Cloud

Dopo aver usato /cloud, l’IDE mostra lo stato dell’attività. Quando l’attività Cloud termina, torna a rivedere diff e risultato.

Punto di ingresso Codex App

Codex app è un command center desktop per lavoro multi-thread e gestione Git. Non è un’altra finestra di chat. Può riprendere history e configurazione da CLI ed estensione IDE, quindi è utile per continuare il lavoro su un progetto esistente.

Definizione e casi d’uso dell’App

L’app si concentra su più thread, worktree, automazioni e operazioni Git. È utile quando hai bisogno di attività parallele, un diff pane e integrazione Git nello stesso workspace locale.

L’app è adatta quando:

• Ti servono più task thread nello stesso momento.
• Devi isolare lavoro parallelo tramite worktree.
• Vuoi un diff pane visuale e operazioni Git.
• Vuoi un workflow desktop con terminale integrato.

L’app è meno adatta quando:

• Vuoi modificare solo il file corrente, dove l’estensione IDE è più comoda.
• Non hai un repository locale; in quel caso usa Cloud o clona prima il repo.
• Ti serve una sola attività rapida, dove la CLI è più veloce.

Supporto piattaforme dell’App

Codex app supporta macOS e Windows. Controlla la pagina ufficiale dell’app per la disponibilità Linux.

Installazione e accesso dell’App

Usa la pagina ufficiale dell’app per i passaggi correnti.

1. Scarica e installa: prendi l’installer macOS o Windows dalla pagina ufficiale dell’app.
2. Accedi: usa un ChatGPT account o una API key. Alcune funzioni possono non essere disponibili con una API key, secondo la guida ufficiale.
3. Scegli un progetto: al primo avvio ti viene chiesto di selezionare una directory di progetto locale.

Thread mode dell’App

L’app offre tre thread mode: Local, Worktree e Cloud.

Thread mode	Cosa fa	Ideale per
Local	Lavora direttamente nella directory del progetto corrente	Piccole modifiche, lavoro a thread singolo, primo messaggio predefinito
Worktree	Crea un worktree isolato per il thread	Attività parallele, modifiche isolate, prevenzione dei conflitti
Cloud	Delega l’attività a Codex Cloud	Repository remoti, PR, attività lunghe

Tieni il workflow worktree dettagliato per una guida successiva. Da principiante, parti da Local mode.

Funzioni principali dell’App

Le funzioni principali dell’app includono:

Funzione	Cosa fa
Diff pane	Permette di ispezionare visivamente le modifiche ai file e fare stage o revert di chunk
Operazioni Git	Supporta commit, push, creazione PR e operazioni Git correlate
Terminale integrato	Cmd+J su macOS apre il terminale; controlla la pagina ufficiale per le shortcut correnti
IDE sync	Workflow dell’estensione IDE e dell’app possono sincronizzarsi nello stesso progetto
Shared MCP settings	CLI, IDE e app possono condividere MCP settings

L’app include anche un in-app browser, ma non usa il profilo del browser autenticato. Apri le pagine che richiedono login in un browser esterno.

Punto di ingresso Codex Cloud/Web

Codex web/cloud si collega a un GitHub account e permette a Codex di lavorare in un repository remoto e creare PR. È adatto a workflow di team, repository remoti e attività che devono continuare mentre sei lontano dal computer.

Definizione e casi d’uso di Cloud

Cloud riguarda repository remoti, PR e lavoro asincrono. Crea un cloud container, fa checkout del repository, esegue gli script di setup, svolge l’attività e restituisce diff e risposta.

Cloud è adatto quando:

• Hai repository remoti che non vuoi modificare in locale.
• Ti servono PR flow in cui Codex crea o rivede una PR.
• Il lavoro deve continuare mentre sei lontano.
• Hai workflow di team con review e collaborazione.

Cloud è meno adatto quando:

• Devi fare piccole modifiche locali, dove CLI o estensione IDE sono migliori.
• È la tua primissima attività, che conviene verificare prima in locale.
• L’attività richiede interazione frequente, perché Cloud è asincrono.

Buone attività per Cloud

Cloud funziona bene per questi tipi di attività:

Tipo di attività	Note
PR review	Rivedere una PR in un repository remoto
Lavoro complesso o lungo	Eseguire attività che richiedono più tempo
Attività parallele	Delegare più attività nello stesso momento
Modifiche a repository remoti	Cambiare codice senza toccare il checkout locale

Non inviare a Cloud un grande refactor o una funzionalità completa il primo giorno. Usa prima CLI o IDE in locale, impara come si presenta il risultato, poi sposta su Cloud le attività adatte.

Gli workspace Enterprise possono richiedere admin setup. Controlla la pagina Cloud ufficiale e la policy del tuo workspace.

Flusso Cloud

Un’attività Cloud segue grosso modo cinque passaggi:

1. Creare un container: Cloud crea l’ambiente runtime.
2. Fare checkout del repository: esegue il checkout del repository GitHub.
3. Eseguire lo script di setup: esegue lo script configurato, se esiste.
4. Eseguire il ciclo dell’agent: l’agent esegue comandi, controlla i risultati e continua finché l’attività è completata.
5. Restituire diff e risposta: l’attività finita mostra diff e risposta.

La cache del container può durare fino a 12 ore. Controlla la pagina ufficiale Cloud environments per la policy corrente.

Note di sicurezza Cloud

Cloud ha alcuni confini di sicurezza importanti:

Elemento di sicurezza	Significato
I secrets sono disponibili solo durante il setup	I secrets sono disponibili agli script di setup e rimossi prima dell’agent phase. Non far dipendere l’agent phase da script che leggono secrets.
L’agent phase non ha internet di default	Durante l’agent phase, l’accesso a internet è spento di default, anche se può essere configurato come limited o unrestricted. Non presumere che l’agent possa raggiungere servizi esterni.
La cache dura fino a 12 ore	La cache del container non è storage a lungo termine. Non dare per scontato che lo stato persista indefinitamente.

Per una configurazione di sicurezza più approfondita, usa la guida successiva su permessi, sandbox e secrets.

Prossimi passi

Dopo la prima attività, se Codex continua a fare lo stesso errore alla seconda o terza esecuzione, scrivi una guida AGENTS.md per il progetto. AGENTS.md dà ai coding agent istruzioni specifiche del progetto, così non devi ripetere lo stesso context in ogni prompt.

Argomenti consigliati per continuare:

• Regole di progetto AGENTS.md: conserva le indicazioni del progetto e riduce il context ripetuto.
• Isolamento con worktree: esegui più attività in parallelo senza mescolare le modifiche.
• Workflow Cloud: repository remoti, PR e configurazione dell’ambiente.
• Permessi, sandbox e secrets: confini di sicurezza e configurazione.
• Confronto tra tre strumenti: Codex vs Claude Code vs Cursor in progetti reali.
• Automazione con codex exec: chiamate CI e automazioni basate su script.

Articoli BetterLink correlati:

• Panoramica degli strumenti di coding AI 2026
• Guida produttiva a Claude Code CLI
• Pratica workflow con Cursor
• Gateway e harness per Codex