Salta al contenuto principale

02 - Codex CLI: installazione e primo lavoro, passo per passo

Come installare Codex CLI e fare un primo lavoro che puoi verificare e annullare, con un controllo di perimetro sulle modifiche che esegui tu.

Cosa ne pensi di questo articolo?

02 - Codex CLI: installazione e primo lavoro, passo per passo
OpenAI Codexfedericocalo.dev

In Breve

Come installare Codex CLI e fare un primo lavoro che puoi verificare e annullare, con un controllo di perimetro sulle modifiche che esegui tu.

Hai deciso di provare Codex CLI e la domanda non è come si installa, perché sono tre comandi: è come fai il primo lavoro senza ritrovarti con un diff che non capisci e che non sai annullare. La documentazione ufficiale, letta il 13 novembre 2026, dà la sequenza minima: installa la CLI, apri la cartella di un progetto, lancia codex e scegli «Sign in with ChatGPT» (o un altro metodo disponibile), poi descrivi un compito e crea checkpoint Git prima e dopo, così da poter tornare indietro. Il resto di questa pagina è la disciplina che trasforma quella sequenza in un lavoro che puoi verificare: un compito piccolo con un criterio di «finito» eseguibile, un perimetro di file dichiarato prima, e un controllo tuo, non dell'agente, su che cosa è cambiato. Il costo è tempo: è più lento di «fai tutto tu», e rende solo quando il compito è abbastanza piccolo da essere controllato in pochi minuti.

Metodo e limiti. Non sono affiliato a OpenAI. Non ho installato né lanciato Codex CLI e non ho chiamato alcun modello: i comandi di installazione e i comandi interni a Codex li riferisco dalla documentazione ufficiale, letta il 2026-11-13, e non li ho provati. Ho invece eseguito io, due volte con la stessa uscita, lo script di controllo del perimetro che trovi più sotto: gira su un repository di prova costruito al momento (Python 3.14, Git 2.53, Node 24), senza alcun assistente.

Prima di installare: due decisioni

Come ti autentichi. Con l'account ChatGPT oppure con una chiave API. La parte 1 della serie mette a confronto i due metodi; qui basta sapere che si può cambiare dopo, con codex login, che per impostazione predefinita apre il browser per l'accesso ChatGPT e accetta anche una chiave API o un token di accesso.

Su che sistema. La pagina sulla sandbox dice che su macOS la sandbox funziona subito, perché usa Seatbelt, già integrato. Su Linux e WSL2 devi prima installare bubblewrap con il gestore di pacchetti (la pagina mostra sudo apt install bubblewrap per Ubuntu e Debian): Codex usa il primo bwrap che trova nel PATH e, se non c'è, ripiega su un programma di supporto incluso, che però richiede la creazione di namespace utente non privilegiati. Su Windows da PowerShell usa una sandbox nativa, e in WSL2 quella di Linux; la pagina su approvazioni e sicurezza precisa che WSL1 era supportato fino alla versione 0.114 e che dalla 0.115 la sandbox Linux è passata a bwrap, quindi WSL1 non è più supportato. Se la sandbox non parte, Codex mostra un avviso all'avvio: il sintomo è lì, non in un blocco misterioso del tuo editor.

Installazione: quattro vie, un solo programma

I comandi seguenti sono copiati dalla pagina Codex CLI della documentazione. Non li ho eseguiti, e per questo non c'è un'uscita da mostrare: sono lo schema del produttore, da adattare al tuo sistema. Per aggiornare, la pagina indica di rilanciare lo stesso comando (per Homebrew brew upgrade --cask codex); esiste anche codex update, che secondo la pagina dei comandi funziona solo quando la release installata supporta l'aggiornamento automatico.

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

# Windows (da una nuova finestra PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm, su qualunque sistema
npm install -g @openai/codex

# Homebrew
brew install --cask codex

La scelta fra le vie è di governo, non di tecnica. Le righe con curl ... | sh e irm ... | iex eseguono ciò che scaricano nel momento in cui lo scaricano: in un ambiente regolamentato, scarica prima lo script e leggilo, oppure usa un gestore di pacchetti che il tuo reparto sicurezza già controlla. npm si appoggia a Node e si integra con i tuoi strumenti di versione; Homebrew è la via più ordinata su macOS. Qualunque scelga, annota la versione installata: nella parte 1 ho mostrato con uno script che la CLI rilascia versioni alpha a ritmo quasi quotidiano, e due colleghi possono vedere comandi diversi.

Il primo avvio, e perché conta il repository Git

All'avvio, la pagina sulla sicurezza spiega che Codex rileva se la cartella è sotto controllo di versione e propone un valore iniziale diverso: nelle cartelle con Git raccomanda il profilo Auto (scrittura nel workspace più approvazioni a richiesta), nelle altre raccomanda read-only; a seconda della configurazione può anche partire in sola lettura finché non dichiari fidata la cartella. È una buona ragione pratica per lavorare dentro un repository: senza Git l'agente parte da un profilo più restrittivo, e tu non hai uno strumento per vedere che cosa ha cambiato. I tre comandi di apertura sono questi, in ordine.

cd ~/progetti/listino-prezzi
git status          # l'albero di lavoro deve essere pulito
git log -1 --oneline
codex               # al primo avvio: «Sign in with ChatGPT» o altro metodo

Il git status pulito non è formalismo. Con un albero già sporco non sai più distinguere ciò che ha cambiato l'agente da ciò che avevi cambiato tu, e la tua unica rete di sicurezza, il confronto con l'ultimo commit, perde significato. La pagina della CLI lo dice in una riga («Create Git checkpoints before and after a task so you can revert changes»): il checkpoint prima è un commit, quello dopo è il commit che fai solo dopo aver controllato.

Il primo compito: quattro parti, di cui una eseguibile

La pagina Best practices della documentazione suggerisce di includere nel prompt quattro cose: l'obiettivo, il contesto (quali file, cartelle o errori contano), i vincoli (quali standard o convenzioni rispettare) e il «done when», cioè che cosa dev'essere vero perché il compito sia finito, per esempio test che passano o un bug che non si riproduce più. Un prompt tipico del primo giorno, scritto da me come esempio da adattare al tuo stack, mette nel «done when» un comando che tu stesso puoi rilanciare.

Aggiungi un test per la funzione calcolaSconto in src/prezzi.js.
Copri: importo zero, importo negativo (deve lanciare RangeError), sconto del 100%.
Non modificare altri file. Segui lo stile dei test già presenti nel repository.
Hai finito quando "node --test src/prezzi.test.js" esce con codice 0.

Il prompt è un testo, non un programma, e non l'ho dato a nessun agente: è uno schema da adattare, non eseguito. Osserva però che le ultime due righe sono verificabili da una macchina: «non modificare altri file» è un perimetro, «esce con codice 0» è un criterio. L'agente le legge come istruzioni, tu puoi trasformarle in un controllo che non dipende dall'agente. Un obiettivo come «migliora questo progetto» non ha questa proprietà: nessun comando può dirti se è stato raggiunto.

Il controllo che resta tuo: perimetro e criterio

Lo script che segue costruisce un repository di prova in una cartella temporanea, con una funzione calcolaSconto e un commit di partenza. Poi simula due modifiche, scritte nello script stesso (non c'è alcun assistente): nella prima viene creato soltanto il file di test richiesto; nella seconda, in più, viene modificato il README.md, un file che il compito non autorizzava. La funzione giudica pone le due domande del primo lavoro: i file toccati stanno nell'insieme PERIMETRO? e il comando CRITERIO esce con codice 0? Per la prima legge git status --porcelain -uall (l'opzione -uall elenca anche i singoli file nuovi, non la sola cartella); per la seconda lancia node --test con il reporter tap, e dall'uscita tiene solo le righe pass e fail: i tempi, che cambiano a ogni esecuzione, restano fuori, e per questo l'uscita riportata è identica a ogni esecuzione.

"""Il controllo che resta tuo anche se usi un agente: che cosa e' cambiato, e dov'e'.

Costruisce un repository di prova, simula due "modifiche di un agente" (scritte qui,
nessun assistente coinvolto) e le giudica con le due domande del primo lavoro:
i file toccati stanno nel perimetro dichiarato? il comando del criterio di finito passa?
"""
import subprocess, sys, tempfile
from pathlib import Path

PERIMETRO = {"src/prezzi.test.js"}          # i soli file che il compito puo' toccare
CRITERIO = ["node", "--test", "--test-reporter=tap", "src/prezzi.test.js"]

def git(repo, *args):
    return subprocess.run(["git", *args], cwd=repo, check=True,
                          capture_output=True, text=True).stdout

def prepara(repo):
    git(repo, "init", "-q")
    git(repo, "config", "user.email", "prova@example.org")
    git(repo, "config", "user.name", "Prova")
    (repo / "src").mkdir()
    (repo / "src/prezzi.js").write_text(
        "export function calcolaSconto(importo, percento) {\n"
        "  if (importo < 0) throw new RangeError('importo negativo');\n"
        "  return importo - importo * percento / 100;\n}\n")
    (repo / "package.json").write_text('{"type": "module"}\n')
    (repo / "README.md").write_text("Listino\n")
    git(repo, "add", "-A")
    git(repo, "commit", "-q", "-m", "stato di partenza")

TEST = (
    "import test from 'node:test';\nimport assert from 'node:assert/strict';\n"
    "import { calcolaSconto } from './prezzi.js';\n"
    "test('importo zero', () => assert.equal(calcolaSconto(0, 10), 0));\n"
    "test('importo negativo', () => assert.throws(() => calcolaSconto(-1, 10), RangeError));\n"
    "test('sconto del 100%', () => assert.equal(calcolaSconto(80, 100), 0));\n")

def giudica(repo):
    righe = git(repo, "status", "--porcelain", "-uall").splitlines()
    toccati = sorted(r[3:] for r in righe)
    fuori = [f for f in toccati if f not in PERIMETRO]
    prova = subprocess.run(CRITERIO, cwd=repo, capture_output=True, text=True)
    esiti = {l.lstrip("# ") for l in prova.stdout.splitlines()
             if l.startswith(("# pass", "# fail"))}
    print("  toccati :", ", ".join(toccati))
    print("  fuori   :", ", ".join(fuori) or "nessuno")
    print("  criterio:", "passa" if prova.returncode == 0 else "FALLISCE", sorted(esiti))
    return not fuori and prova.returncode == 0

if __name__ == "__main__":
    with tempfile.TemporaryDirectory() as cartella:
        repo = Path(cartella)
        prepara(repo)
        (repo / "src/prezzi.test.js").write_text(TEST)
        print("A) modifica dentro il perimetro")
        ok_a = giudica(repo)
        (repo / "README.md").write_text("Listino\nSconti in arrivo\n")
        print("B) la stessa modifica, piu' un file non richiesto")
        ok_b = giudica(repo)
        git(repo, "restore", "README.md")
        print("C) dopo git restore README.md")
        ok_c = giudica(repo)
    print("verdetti:", ok_a, ok_b, ok_c)
    sys.exit(0 if (ok_a, ok_b, ok_c) == (True, False, True) else 1)

# Comando: python3 -I perimetro.py
# Output:
# A) modifica dentro il perimetro
#   toccati : src/prezzi.test.js
#   fuori   : nessuno
#   criterio: passa ['fail 0', 'pass 3']
# B) la stessa modifica, piu' un file non richiesto
#   toccati : README.md, src/prezzi.test.js
#   fuori   : README.md
#   criterio: passa ['fail 0', 'pass 3']
# C) dopo git restore README.md
#   toccati : src/prezzi.test.js
#   fuori   : nessuno
#   criterio: passa ['fail 0', 'pass 3']
# verdetti: True False True

Leggi i tre scenari. Nel caso A i file toccati stanno tutti nel perimetro e i tre test passano: è l'esito che vuoi. Nel caso B il criterio passa ancora (tre test, zero fallimenti), ma il perimetro è violato da README.md: il test verde da solo non basta, ed è esattamente il tipo di modifica in più che un riepilogo scritto dall'agente può non menzionare. Nel caso C, dopo git restore README.md, il repository torna al caso A. Lo script non dimostra nulla su Codex: dimostra che il confronto fra ciò che hai chiesto e ciò che è cambiato è un controllo meccanico che puoi eseguire tu, in dieci righe, prima di leggere una sola riga di diff.

Quando non usarlo così: il perimetro a elenco fisso funziona per compiti piccoli e prevedibili, come aggiungere un test. Per un refactoring che tocca per sua natura molti file, un perimetro per cartella o per modello (per esempio «solo sotto src/prezzi/») ha più senso, e il compito dovrebbe forse essere spezzato.

I comandi interni che servono subito

La pagina dei comandi della CLI documenta decine di comandi interni alla sessione; per il primo giorno ne bastano sei, che ho verificato uno per uno su quella pagina.

  • /init: genera una bozza di AGENTS.md nella cartella corrente, da rivedere e modificare (la parte 4 spiega come scriverlo bene).
  • /status: mostra modello attivo, criterio di approvazione, cartelle scrivibili e consumo di token della sessione.
  • /permissions: apre il selettore dei profili di approvazione, per esempio Auto oppure Read Only.
  • /model: cambia modello e livello di ragionamento (parte 5).
  • /review: rivede la copia di lavoro e riassume i problemi trovati, guardando soprattutto cambiamenti di comportamento e test mancanti.
  • /diff: mostra le modifiche esatte ai file, da usare dopo la revisione.

Il comando che conta di più è /status, da aprire all'inizio di ogni compito che ti interessa: ti dice con quali permessi e con quali cartelle scrivibili stai lavorando. Molti incidenti di questo tipo di strumenti nascono da un permesso ampio dato per un'attività e dimenticato per la successiva. /review è utile come secondo paio d'occhi ma resta un altro passaggio dello stesso strumento: non sostituisce né il tuo git diff né il tuo criterio di «finito». Esiste anche la forma non interattiva codex review, con un solo bersaglio fra --uncommitted, --base e --commit, oppure un prompt personalizzato.

Le opzioni a riga di comando che cambiano il lavoro

Oltre alla sessione interattiva, la pagina della CLI elenca queste funzioni, che qui riporto con ciò che comportano.

  • codex resume: riapre una chat recente; --last si riferisce alla cartella corrente, a meno che tu non aggiunga --all.
  • codex --image: allega uno screenshot o un diagramma al primo prompt.
  • codex --search: porta la ricerca web da «cached», che è il valore predefinito, alla navigazione dal vivo.
  • codex cloud: sfoglia e invia lavoro a Codex Cloud, poi applica i risultati al repository locale (parte 7).
  • codex mcp: aggiunge server MCP locali o remoti e ne mostra gli strumenti.
  • codex exec: esecuzione non interattiva per script e CI (parte 6).

La differenza fra ricerca «cached» e «live» ha un motivo di sicurezza. La pagina sulla sicurezza spiega che la modalità predefinita serve risultati da un indice di pagine web mantenuto da OpenAI, invece di scaricare pagine in tempo reale, e che questo riduce l'esposizione all'iniezione di istruzioni da contenuti arbitrari; con --search (o web_search = "live") ottieni dati recenti ma accetti quel rischio. Usala quando il compito dipende da una libreria uscita da poco, e tratta i risultati web come non fidati, come dice la stessa pagina. Se non ti serve, lasciala spenta.

Quando qualcosa non va

  • Il login non si completa. Rilancia codex login e segui il flusso nel browser; se il tuo piano non include la superficie che stai provando, la pagina dei prezzi è la prima da rileggere.
  • La sandbox non parte su Linux. Controlla che bwrap sia installato e che i namespace utente non privilegiati siano consentiti; la pagina sulla sandbox ha una sezione dedicata a Ubuntu 24.04 e al profilo AppArmor di bwrap.
  • L'agente chiede continuamente il permesso. È il comportamento prudente. Non risolverlo alzando i permessi a caso: la parte 3 mostra come allargare solo ciò che serve.
  • Il comportamento non corrisponde a una guida. Guarda la versione che hai installato e confrontala con le release. La pagina dei comandi documenta codex doctor, che genera un rapporto diagnostico locale su installazione, configurazione, autenticazione, ambiente di esecuzione, Git e terminale; è lo strumento da usare prima di aprire una segnalazione.

In tutti e quattro i casi la regola è la stessa: prima leggi il messaggio, poi restringi il compito, e solo infine allarga i permessi. Alzare i permessi è l'ultima risorsa, perché è l'unica delle quattro che rende più grave un errore successivo.

Domande frequenti

Devo lavorare dentro un repository Git per usare Codex?

Non è obbligatorio, ma è consigliato dalla documentazione. Nelle cartelle senza controllo di versione Codex raccomanda il profilo di sola lettura, e tu non avresti il confronto con l'ultimo commit per vedere che cosa è cambiato. Per un esperimento, crea un repository di prova: bastano git init e un commit.

Come torno indietro se l'agente rovina un file?

Con il checkpoint fatto prima. Se il file non è ancora in un commit tuo, git restore <file> riporta il file all'ultimo commit, come mostra lo scenario C dello script; se hai già committato, git revert annulla il commit con un nuovo commit. Per questo conviene committare le modifiche dell'agente separatamente dalle tue.

Come aggiorno la CLI?

Rilanciando lo stesso comando con cui l'hai installata, secondo la pagina della CLI; con Homebrew usi brew upgrade --cask codex. Dopo l'aggiornamento riapri una sessione: le guide scritte per versioni precedenti possono descrivere comandi cambiati.

Che cosa sai fare adesso

Sai installare la CLI per il tuo sistema e capire che cosa ti serve prima (bwrap su Linux, un repository Git ovunque), formulare un compito con obiettivo, contesto, vincoli e criterio, e verificare tu, con un controllo meccanico, che le modifiche stiano nel perimetro e che il criterio passi. Il passo successivo è capire che cosa l'agente può fare mentre lavora: nella parte 3 su sandbox e approvazioni vedi le due manopole che lo decidono. Se ti manca la mappa del prodotto, torna alla parte 1.

Che cosa non ho verificato

Non ho installato né eseguito la CLI: nomi dei comandi, delle opzioni e dei comandi interni sono verificati sulla documentazione del 2026-11-13, non su una macchina. Non ho verificato il comportamento della sandbox su Linux, macOS o Windows, né il testo esatto degli avvisi all'avvio. Il prompt di esempio e il controllo di perimetro sono miei, non del produttore; il controllo non prova che Codex rispetti il perimetro, solo che tu puoi verificarlo.

Nella stessa serie trovi anche la scelta del modello e del ragionamento (parte 5) e il confronto con Claude Code, Copilot e Cursor (parte 8).

Fonti

  • Codex CLI - le quattro vie di installazione, il primo avvio, i checkpoint Git, le funzioni resume, --image, --search, cloud, mcp, exec; consultata il 2026-11-13
  • Developer commands - /init, /status, /permissions, /review, /diff, codex doctor, codex login, codex update, codex review; consultata il 2026-11-13
  • Sandbox - requisiti per sistema operativo, bubblewrap, avvisi all'avvio; consultata il 2026-11-13
  • Agent approvals & security - profilo raccomandato con o senza Git, ricerca web «cached» e «live», fine del supporto WSL1; consultata il 2026-11-13
  • Best practices - le quattro parti del prompt: Goal, Context, Constraints, Done when; consultata il 2026-11-13

Lo script perimetro.py è stato eseguito due volte con Python 3.14, Git 2.53 e Node 24, con la stessa uscita; la CLI di Codex non è stata installata né eseguita, e i comandi di installazione sono riportati come schema del produttore.

← Parte 1: la mappa del prodotto Parte 3: sandbox e approvazioni →

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti