Tutorial Codex CLI in italiano

Cos'e Codex CLI

Codex CLI e un agent harness di OpenAI: un coding agent leggero che gira nel tuo terminale, mette un modello in un ciclo con dei tool (leggere file, modificare file, eseguire comandi shell) e lavora direttamente nel tuo repository verso un obiettivo che tu fissi. Come Claude Code, non ti da solo snippet da incollare; fa modifiche multi-file ed esegue comandi, e mantieni il controllo verificando cosa propone e approvando le azioni importanti. E open-source ed e cresciuto in fretta: a inizio 2026, aveva superato due milioni di utenti attivi a settimana. Il modello di configurazione di progetto e AGENTS.md, una convenzione aperta e agnostica agli strumenti per dare a un coding agent le sue istruzioni permanenti, l'equivalente Codex del CLAUDE.md di Claude Code. Vedi il glossario sull'agent harness per il concetto sottostante.

• Un coding agent da terminale che legge, modifica ed esegue codice nel tuo repo, non autocomplete.
• Tu supervisioni: propone azioni e approvi quelle importanti.
• Open-source, con oltre due milioni di utenti attivi a settimana a inizio 2026.
• Configurato con AGENTS.md, una convenzione aperta e agnostica agli strumenti per le istruzioni permanenti.

Installare Codex CLI

Installa Codex CLI con npm o Homebrew. L'installazione npm mette il binario codex globalmente sul tuo path e richiede Node.js 18 o piu recente; il cask Homebrew e l'opzione pratica su macOS. Sceglline uno, poi conferma che sia sul tuo path. Questi comandi sono aggiornati a giugno 2026 contro il quickstart ufficiale, ma poiche lo strumento si muove in fretta, verifica la documentazione OpenAI Codex se qualcosa e cambiato.

# npm (needs Node.js 18+)
npm install -g @openai/codex

# Homebrew on macOS
brew install --cask codex

# Confirm it is installed and on your path
codex --version

Connettersi

Al primo avvio, Codex ti invita ad autenticarti, e hai due vie. La consigliata per la maggior parte e la connessione con il tuo account ChatGPT, che usa Codex nell'ambito di un piano ChatGPT a pagamento (Plus, Pro, Business, Edu o Enterprise). L'alternativa e una chiave API OpenAI, fatturata a token, la scelta giusta per l'automazione, il CI o se preferisci una fatturazione a uso; nota che alcune funzionalita possono differire tra le due. Per usare una chiave, definiscila come variabile d'ambiente prima dell'avvio, oppure segui il flusso di login in-app per ChatGPT. Lancia semplicemente codex e scegli "Sign in with ChatGPT" quando richiesto.

# Start Codex; on first run it walks you through sign-in
codex

# Option A (recommended): choose "Sign in with ChatGPT" in the prompt
# uses your paid ChatGPT plan (Plus, Pro, Business, Edu, Enterprise)

# Option B: authenticate with an API key (good for CI and automation)
export OPENAI_API_KEY="your-api-key"
codex

Dargli regole con AGENTS.md

AGENTS.md e il modo in cui insegni a Codex le regole permanenti del tuo progetto, lo stesso ruolo che CLAUDE.md svolge per Claude Code, e poiche e una convenzione aperta, molti agenti la leggono. Codex costruisce una instruction chain all'avvio, va da un file globale fino alla tua directory corrente e li concatena, con i file piu vicini alla tua directory di lavoro che hanno priorita in caso di conflitto. Questo da tre scope utili: un ~/.codex/AGENTS.md globale per i tuoi default personali, un AGENTS.md alla radice del tuo repo per le regole di progetto che tutti condividono, e file AGENTS.md annidati in sottodirectory per override specifici a una zona. Tienili concentrati su setup, convenzioni e requisiti di test; Codex rispetta un limite di dimensione standard (circa 32 Kio sulla chain), e come ogni file di istruzioni permanenti, un file conciso batte uno tentacolare.

# AGENTS.md (at your repository root)

## Setup
- Install with `bun install`. The dev server is `bun run dev`.

## Conventions
- TypeScript only. Use "-" not em dashes. Border radius is always rounded-sm.

## Tests and quality gate
- Before you call a task done, run: bun run lint && bun run typecheck && bun run test.

## Out of scope
- Do not edit files under /generated; they are built, not hand-edited.

Il tuo primo compito

Apri un terminale nel progetto su cui vuoi lavorare, ed esegui codex. Comincia in piccolo per costruire fiducia: chiedigli di spiegare il progetto o trovare dove si trova qualcosa prima di lasciarlo cambiare qualsiasi cosa. Quando chiedi un cambiamento, preferibilmente fallo proporre prima il suo approccio, verifica il cambiamento che fa, e mantieni i tuoi test verdi. Un'abitudine di sicurezza che la documentazione raccomanda e fare commit di un checkpoint Git pulito prima di un compito e di nuovo dopo, cosi un cambiamento che non ti piace e a un git restore di distanza. Codex offre modalita di approvazione che pilotano quanto puo fare senza chiedere; comincia piu prudente, dove chiede prima di eseguire comandi o modificare, e rilassalo solo una volta che ti fidi del workflow su un repo.

• Esegui codex nel tuo progetto; comincia con una richiesta in sola lettura come "explain what this project does".
• Per le modifiche, fallo proporre l'approccio, poi verifica il diff prima di accettarlo.
• Fai commit di un checkpoint Git prima e dopo un compito, per poter tornare indietro con pulizia.
• Comincia con una modalita di approvazione prudente (chiede prima di agire) e rilassala solo una volta che ti fidi.

Dove andare dopo

Una volta acquisite le basi, le abitudini che rendono Codex affidabile sono le stesse che rendono affidabile ogni coding agent, e si trasferiscono direttamente dalle nostre altre guide. Appoggiati alla guida Prompt pattern per coding agent per briefare bene, alla guida Context Engineering per una window affilata su compiti lunghi, e al pilastro Cos'e l'agentic engineering per la disciplina di dirigere e verificare piuttosto che accettare output non verificato. Se usi anche l'agente di Anthropic, il confronto Claude Code vs Codex CLI espone dove ognuno conviene, e il corso Foundations installa ed esegue entrambi fianco a fianco.

• Prompt pattern per coding agent: come briefare Codex con una spec, esempi e una verification loop.
• Context Engineering: mantieni la sua context window affilata su compiti lunghi.
• Claude Code vs Codex CLI: quale agente da terminale conviene a quale lavoro.
• Corso Foundations: installa ed esegue Claude Code e Codex fianco a fianco.

Passo dopo passo

1. 01

   Installare Codex CLI

   Installa con npm ("npm install -g @openai/codex", richiede Node.js 18+) o Homebrew ("brew install --cask codex" su macOS). Conferma con "codex --version".

2. 02

   Connettersi

   Esegui "codex" e scegli "Sign in with ChatGPT" per usare un piano ChatGPT a pagamento, oppure definisci OPENAI_API_KEY nel tuo ambiente per autenticare con una chiave API per l'automazione e il CI.

3. 03

   Scrivere un AGENTS.md

   Aggiungi un AGENTS.md alla radice del tuo repo con il tuo setup, le tue convenzioni e il comando di quality gate. Codex legge i file globali, di progetto e annidati, con il piu vicino alla directory di lavoro che vince.

4. 04

   Eseguire un primo compito in sicurezza

   Esegui "codex" nel tuo progetto, comincia con una richiesta in sola lettura, fai commit di un checkpoint Git prima e dopo, e usa una modalita di approvazione prudente, cosi chiede prima di eseguire comandi o modificare.

5. 05

   Verificare e continuare

   Leggi il diff prima di accettare un cambiamento, mantieni i tuoi test verdi, e rilassa la modalita di approvazione solo una volta che ti fidi del workflow su questo repo.

Domande frequenti

Continua a imparare