Come migrare da Claude Code a Codex nel 2026: guida passo passo

Documentazione Ailoot: API, chiavi e configurazione.

Perché serve proprio lo strumento di migrazione di Codex?#

OpenAI ha aggiunto la funzione a Codex all'inizio di giugno 2026. Il changelog ufficiale la descrive brevemente:

In altre parole: quando avvii per la prima volta l'app Codex, o dalle impostazioni di un client già in esecuzione, si avvia una procedura guidata che legge le configurazioni locali di un altro agente. Attualmente sono supportati Claude Code e Claude Cowork.

È chiaro perché OpenAI lo stia facendo. Dopo il lancio di Sites e l'aggiornamento dell'app Codex a maggio-giugno 2026, Codex ha acquisito tutto ciò che Claude Code aveva in precedenza in più rispetto a OpenAI: un terminale, plugin, sessioni lunghe e orchestrazione. La migrazione rimuove l'ultimo ostacolo per i team che hanno già integrato Claude Code nel proprio stack: "le impostazioni supportate possono essere importate e poi confrontate con l’inventario originale".

Il motivo per cui potrebbe servirti è meno ovvio. Ho confrontato i due strumenti testa a testa nella guida a Codex e Claude Code: Claude è ancora avanti nelle lunghe discussioni architetturali e nella modalità Plan, mentre Codex è più veloce nei task autonomi e nelle PR parallele. Se hai deciso di passare completamente, continua a leggere. Se stai valutando una combinazione, potrebbero interessarti di più gli schemi di collaborazione.

Cosa trasferisce automaticamente lo strumento di migrazione?#

Esaminerò i gruppi e spiegherò esattamente cosa succede a ciascuna parte di ~/.claude.

1. Istruzioni e contesto. I file CLAUDE.md — quello globale in ~/.claude/ e quelli di progetto nei repository — vengono convertiti nel formato AGENTS.md. Il file globale finisce in ~/.codex/AGENTS.md; i file di progetto restano nella radice del repository e nelle cartelle figlie. Il formato AGENTS.md è essenzialmente lo stesso tipo di file Markdown con regole; le differenze sono per lo più estetiche: i nomi delle sezioni e un paio di direttive specifiche. Ho spiegato che cos'è AGENTS.md e perché serve a Codex.

2. Competenze. La cartella ~/.claude/skills/ viene analizzata per intero; ogni competenza viene adattata alla struttura di Codex e collocata in $HOME/.agents/skills. Le competenze di progetto da .claude/skills/ in un repository vengono spostate in .agents/skills. Il formato SKILL.md con frontmatter viene trasferito quasi senza modifiche. Se una competenza usa trigger specifici di Claude, viene segnalata per la revisione.

3. Server MCP. La configurazione .mcp.json (sia globale sia a livello di progetto) viene importata nel formato di Codex. I nomi dei server, i comandi di avvio e i percorsi vengono conservati. Cosa non viene trasferito: token e variabili d'ambiente. Per motivi di sicurezza, Codex ti chiederà nuovamente le chiavi API e le password, così non vengono esposte durante la migrazione. È un'operazione una tantum: apri la sezione MCP nell'app Codex e inserisci i token che hai già nel gestore di password.

4. Hook. Questo è il gruppo complicato. Gli hook con logica deterministica (bloccare rm -rf, avvisare in caso di percorsi che sembrano contenere credenziali, registrare prove) vengono trasferiti integralmente. Gli hook con trigger che non hanno equivalenti in Codex (per esempio eventi specifici del ciclo di vita di Claude Code) vengono contrassegnati per la "revisione manuale" e non vengono attivati automaticamente. Ho spiegato in dettaglio come funzionano gli hook in Claude Code, come riferimento: Codex ne ha meno tipologie.

5. Cronologia delle sessioni. Vengono importati come riferimento fino agli ultimi 30 giorni di attività di Claude Code. Questo non significa "riprendere esattamente da dove avevi interrotto", ma le conversazioni passate saranno visibili in Codex, così potrai richiamare rapidamente il contesto del progetto senza dover rispiegare tutto.

Lo strumento di migrazione non distingue tra file attivi e artefatti sperimentali: trasferisce tutto. Dopo la migrazione, è utile eliminare manualmente ciò che non usi da sei mesi.

Cosa NON viene trasferito e perché?#

Esaminerò ogni gruppo dal punto di vista di "cosa fare dopo la migrazione".

Token MCP e chiavi API. È la parte più prevedibile. Dopo la scansione, Codex ti mostrerà l'elenco di tutti i server MCP trovati in Claude. Ti chiederà le chiavi e i token per ciascuno. La cosa più semplice è tenere a portata di mano il gestore di password e passare in rassegna tutti i server in una sola sessione. Dopodiché, MCP funziona allo stesso modo in Codex e Claude Code. Verifica i parametri di comando e connessione del server MCP scelto consultando la relativa documentazione.

Comandi slash /name. In Claude Code, sei abituato a richiamare una competenza con /skill-name. In Codex, il modo canonico di richiamarla è diverso: $skill-name. Un errore di migrazione comune è considerare i comandi /name come prova che le competenze siano state caricate.

Dopo la migrazione, prova alcune competenze fondamentali con $skill-name in Codex. Se funzionano, la migrazione è riuscita davvero. Non fidarti della casella "competenze migrate" nella procedura guidata: verifica richiamandole.

Hook senza equivalenti in Codex. Se avevi un hook per eventi specifici di Claude Code — per esempio, su pre-tool-use per una particolare combinazione di strumenti — quel trigger potrebbe non esistere in Codex. Lo strumento di migrazione li segnalerà e li lascerà inattivi. Dovrai decidere se riscriverli per un equivalente in Codex, eliminarli o mantenerli in Claude Code (se lo usi in parallelo). Una buona regola: trasferisci solo gli hook deterministici; tutto il resto è un motivo per non duplicare la gerarchia nel nuovo strumento.

Flussi di lavoro di team basati sui subagent. Ho spiegato che cosa sono i subagent in Claude Code e come usare i subagent annidati. In Codex, i subagent sono organizzati tramite profili e ruoli (vedi sotto). Se in Claude avevi una pipeline complessa con diversi subagent in sequenza, dovrai riscriverla attorno al concetto di profilo di Codex. Lo strumento di migrazione contrassegna queste configurazioni come "richiede una rielaborazione architetturale".

File CLAUDE.md lunghi e specifici di Claude. Se un file è arrivato a 2.000–3.000 righe con sezioni per ogni progetto, Codex potrebbe accettarlo, ma è una cattiva pratica. AGENTS.md è progettato per essere compatto e distribuito: regole globali in ~/.codex/AGENTS.md, regole specifiche del progetto nella radice del repository e override mirati nelle cartelle figlie. Dopo la migrazione, non lasciare CLAUDE.md come "un enorme file di istruzioni": suddividilo tra i vari livelli. Ho spiegato come configurare correttamente CLAUDE.md; lo stesso approccio vale per AGENTS.md.

Passo dopo passo: 4 azioni nell'app Codex#

Ecco la checklist specifica.

1. Passaggio 1: aggiorna l'app Codex alla versione 26.608 o successiva

   Lo strumento di migrazione è apparso nella versione 26.608 (rilasciata il 9 giugno 2026). Su macOS, apri l'app Codex e controlla la disponibilità di aggiornamenti. Fai lo stesso su Windows. Se usi Codex CLI, assicurati che sia compatibile con l'app attuale. Senza l'ultima versione, "Importa la configurazione di un altro agente" non apparirà nelle Impostazioni.

2. Passaggio 2: avvia l'importazione dalle Impostazioni

   Nell'app Codex, apri Impostazioni e cerca "Importa la configurazione di un altro agente". Se hai appena installato l'app Codex, la procedura guidata proporrà la migrazione durante la configurazione iniziale. Una volta avviata, la procedura guidata analizza il filesystem: ~/.claude/ e i repository che contengono CLAUDE.md o .claude/. La scansione richiede da 30 secondi a diversi minuti, a seconda del numero di file.

3. Passaggio 3: conferma il piano di migrazione

   Dopo la scansione, Codex mostrerà un inventario: quante competenze sono state trovate, quanti server MCP, quanti file CLAUDE.md, quali hook sono idonei alla migrazione e quanti giorni di cronologia delle sessioni sono disponibili. Puoi deselezionare qualsiasi gruppo che non vuoi trasferire. Per impostazione predefinita, è selezionato tutto ciò che Codex ritiene sicuro importare.

4. Passaggio 4: attendi il completamento e inserisci i token

   L'importazione richiede 1–5 minuti. Al termine, Codex aprirà una finestra di follow-up: "ecco cosa non sono riuscito a trasferire automaticamente; controllalo manualmente". Di solito è un elenco di server MCP che richiedono token. Apri il gestore di password e inserisci le chiavi nel modulo di Codex. A quel punto, la parte principale della migrazione è completa.

Poi verifica il risultato. Apri un progetto su cui lavoravi abitualmente in Claude Code e controlla:

• cat ~/.codex/AGENTS.md — ci sono le tue regole globali?
• Esegui una qualsiasi competenza: $skill-name. Dovrebbe caricarsi.
• Apri .mcp.json nel progetto e controlla che i server necessari siano in esecuzione.
• Avvia una conversazione che rispecchi il tuo modo abituale di lavorare. Codex mostrerà quali hook importati non può usare: sono elementi specifici dell’inventario da gestire manualmente; non è stabilita una quota residua fissa.

Hook e subagent: equivalenti in Codex e cosa riscrivere#

Hook. In Claude Code puoi associare un comando shell a ogni evento del ciclo di vita (pre-tool-use, post-tool-use, on-error, on-context-load e così via). Codex ha un insieme più ristretto di eventi: può effettuare controlli prima dell'esecuzione, registrare prove e bloccare comandi pericolosi. Se avevi un hook pre-tool-use che filtrava una combinazione specifica, in Codex dovrai inserirlo in un controllo generale pre-esecuzione oppure eliminarlo. Ho spiegato in dettaglio l'architettura degli hook di Claude Code; se li usavi molto, elenca ogni trigger e il suo effetto necessario, individua un equivalente supportato e verificalo prima di abilitarlo.

Subagent. In Claude Code, un subagent è un contesto separato con il proprio prompt di sistema, avviato tramite un /command o dalla conversazione principale. Codex ha un concetto simile nei profili: puoi definire un profilo con un insieme specifico di competenze, autorizzazioni e criteri di approvazione. I profili risolvono più o meno lo stesso problema — isolare il contesto per una determinata classe di task — ma attraverso le impostazioni anziché con una chiamata esplicita a un agente.

Cosa significa nella pratica:

• Se avevi un subagent "security-reviewer" con il proprio prompt, crea in Codex un profilo security-review con le autorizzazioni necessarie e un livello di ragionamento più alto.
• Se avevi un subagent "feature-developer", è semplicemente un profilo di lavoro predefinito; non serve fare nulla di speciale.
• Se usavi subagent annidati, non potrai riprodurli in Codex in modo identico; ripensali come una catena di profili o competenze esplicite.

Lo strumento di migrazione proverà a creare profili usando i nomi dei tuoi subagent e segnalerà quali trigger non sono stati trasferiti. Il lavoro dipende da ruoli, trigger, permessi e dipendenze: prova ogni pipeline necessaria prima di considerarla migrata.

Quando migrare del tutto e quando mantenere entrambi gli strumenti#

Un semplice criterio decisionale:

Passare completamente a Codex ha senso se:

• Ti occupi soprattutto di PR autonome e task paralleli.
• Il tuo flusso di lavoro su GitHub è profondamente integrato e Codex Cloud Agent gestisce l'80% del lavoro.
• Non dedichi molto tempo alle discussioni architetturali e alla modalità Plan.
• Vuoi pagare per un solo strumento anziché due.

Usare insieme Claude Code e Codex se:

• Usi regolarmente la modalità Plan per decisioni architetturali di lunga durata.
• Hai bisogno di lavoro parallelo: Codex lavora nel cloud su un task mentre Claude Code mantiene il contesto per un altro.
• Fai molti hack una tantum e microprogetti per i quali la modalità Plan è eccessiva.
• Hai una pipeline complessa di subagent che non può essere riscritta in una sera.

Personalmente li uso entrambi: Claude Code mantiene la conversazione lunga, mentre Codex si occupa di "correggere N bug in parallelo" o "revisionare una PR". Ho spiegato meglio come funziona nella guida per lavorare insieme con Claude Code e Codex.

La cosa principale che direi sulla migrazione è questa: lo strumento di migrazione rimuove l'ostacolo tecnico al passaggio, ma non risponde alla domanda se sia necessario passare in primo luogo. Decidi prima che tipo di lavoro fai. Poi scegli lo strumento.

Se hai bisogno di accedere alle reti neurali tramite Ailoot, dai un'occhiata ad Ailoot.