In 2026 migreren van Claude Code naar Codex: een stapsgewijze handleiding

Ailoot-documentatie: API, sleutels en configuratie.

Waarom is de Codex-migratietool eigenlijk nodig?#

OpenAI voegde de functie begin juni 2026 toe aan Codex. De officiële changelog vermeldt het kort:

Met andere woorden: wanneer je de Codex App voor het eerst start, of via de instellingen van een client die al actief is, start een wizard die de lokale configuraties van een andere agent uitleest. Claude Code en Claude Cowork worden momenteel ondersteund.

Het is duidelijk waarom OpenAI dit doet. Nadat Sites werd gelanceerd en de Codex App in mei–juni 2026 werd bijgewerkt, kreeg Codex alles wat Claude Code voorheen op OpenAI voor had: een terminal, plugins, lange sessies en orkestratie. Migratie neemt de laatste drempel weg voor teams die Claude Code al in hun stack hebben geïntegreerd: "ondersteunde instellingen kunnen worden geïmporteerd en daarna tegen de oorspronkelijke inventaris worden gecontroleerd."

Waarom jij het nodig zou kunnen hebben, ligt minder voor de hand. Ik heb ze rechtstreeks vergeleken in de gids Codex vs. Claude Code: Claude is nog steeds beter in lange architectuurdiscussies en Plan Mode, terwijl Codex sneller is bij autonome taken en parallelle PR's. Als je hebt besloten volledig over te stappen, lees dan verder. Als je een combinatie overweegt, zijn de samenwerkingspatronen mogelijk relevanter.

Wat zet de migratietool automatisch over?#

Ik loop de groepen langs en leg precies uit wat er met elk onderdeel van ~/.claude gebeurt.

1. Instructies en context. CLAUDE.md-bestanden — het globale bestand in ~/.claude/ en projectbestanden in repositories — worden omgezet naar de indeling van AGENTS.md. Het globale bestand komt terecht op ~/.codex/AGENTS.md; projectbestanden blijven in de hoofdmap van de repository en in onderliggende mappen. AGENTS.md is in wezen hetzelfde soort Markdown-bestand met regels; de verschillen zijn grotendeels cosmetisch — sectienamen en een paar specifieke richtlijnen. Ik heb uitgelegd wat AGENTS.md is en waarom Codex het nodig heeft.

2. Skills. De map ~/.claude/skills/ wordt volledig gescand; elke skill wordt aangepast aan de Codex-structuur en geplaatst in $HOME/.agents/skills. Projectskills uit .claude/skills/ in een repository worden verplaatst naar .agents/skills. De indeling van SKILL.md met frontmatter wordt vrijwel ongewijzigd overgezet. Als een skill Claude-specifieke triggers gebruikt, wordt deze gemarkeerd voor controle.

3. MCP-servers. De configuratie .mcp.json (zowel globaal als op projectniveau) wordt geïmporteerd naar de Codex-indeling. Servernamen, startcommando's en paden blijven behouden. Wat niet wordt overgezet: tokens en omgevingsvariabelen. Om veiligheidsredenen vraagt Codex je tijdens de migratie opnieuw om API-sleutels en wachtwoorden, zodat die niet worden blootgesteld. Dit is een eenmalige taak: open de MCP-sectie in de Codex App en voer de tokens in die je al in je wachtwoordmanager hebt staan.

4. Hooks. Dit is de ingewikkelde groep. Hooks met deterministische logica (zoals rm -rf blokkeren, waarschuwen bij paden die op inloggegevens lijken en bewijs vastleggen) worden volledig overgezet. Hooks met triggers waarvoor Codex geen equivalent heeft (bijvoorbeeld specifieke Claude Code-lifecyclegebeurtenissen) worden gemarkeerd voor "handmatige controle" en niet automatisch geactiveerd. Ik heb als referentie uitgebreid uitgelegd hoe hooks in Claude Code werken — Codex heeft er minder typen.

5. Sessiegeschiedenis. Maximaal de laatste 30 dagen aan Claude Code-activiteit wordt geïmporteerd als naslag. Dit betekent niet "precies verdergaan waar je was gebleven", maar je eerdere gesprekken zijn wel zichtbaar in Codex, zodat je snel de projectcontext kunt terughalen zonder alles opnieuw uit te leggen.

De migratietool maakt geen onderscheid tussen actieve bestanden en experimentele artefacten — hij zet alles over. Na de migratie is het nuttig handmatig op te ruimen wat je de afgelopen zes maanden niet hebt gebruikt.

Wat wordt NIET overgezet, en waarom?#

Ik loop elke groep langs vanuit het perspectief van "wat moet je na de migratie doen?".

MCP-tokens en API-sleutels. Dit is het meest voorspelbare onderdeel. Na het scannen toont Codex een lijst met alle MCP-servers die het in Claude heeft gevonden. Voor elke server vraagt het om sleutels en tokens. Het makkelijkst is om je wachtwoordmanager bij de hand te houden en alle servers in één keer langs te lopen. Daarna werkt MCP hetzelfde in Codex en Claude Code. Controleer de commando's en verbindingsparameters van de MCP-server die je hebt gekozen aan de hand van de documentatie ervan.

Slashcommando's /name. In Claude Code ben je gewend een skill aan te roepen met /skill-name. In Codex is de canonieke aanroep anders: $skill-name. Een veelgemaakte migratiefout is /name-commando’s zien als bewijs dat skills zijn geladen.

Test na de migratie een paar belangrijke skills met $skill-name in Codex. Als ze werken, is de migratie echt geslaagd. Vertrouw niet op het selectievakje "skills migrated" in de wizard — controleer het door ze aan te roepen.

Hooks zonder Codex-equivalent. Als je een hook had voor specifieke Claude Code-gebeurtenissen — bijvoorbeeld bij pre-tool-use voor een bepaalde combinatie van tools — bestaat die trigger mogelijk niet in Codex. De migratietool markeert zulke hooks en laat ze inactief. Je moet beslissen of je ze herschrijft voor een Codex-equivalent, verwijdert of in Claude Code laat staan (als je beide parallel gebruikt). Een goede regel: zet alleen deterministische hooks over; al het andere is een reden om de hele ladder niet in het nieuwe hulpmiddel te dupliceren.

Teamworkflows op basis van subagents. Ik heb uitgelegd wat subagents in Claude Code zijn en hoe je geneste subagents gebruikt. In Codex worden subagents georganiseerd via profielen en rollen (zie hieronder). Als je in Claude een complexe pipeline had met meerdere subagents achter elkaar, moet je die herschrijven rond het profielconcept van Codex. De migratietool markeert zulke configuraties als "requires architectural rework".

Grote, Claude-specifieke CLAUDE.md-bestanden. Als een bestand is gegroeid tot 2.000–3.000 regels met secties voor elk project, accepteert Codex het mogelijk, maar dat is een slechte aanpak. AGENTS.md is ontworpen om compact en verspreid te zijn: globale regels in ~/.codex/AGENTS.md, projectspecifieke regels in de hoofdmap van de repository en beperkte overschrijvingen in onderliggende mappen. Laat CLAUDE.md na de migratie niet achter als een "gigantisch instructiebestand"; verdeel het over de verschillende niveaus. Ik heb uitgelegd hoe je CLAUDE.md correct configureert; dezelfde aanpak geldt voor AGENTS.md.

Stap voor stap: 4 handelingen in de Codex App#

Hier is de concrete checklist.

1. Stap 1: Werk de Codex App bij naar 26.608 of hoger

   De migratietool verscheen in versie 26.608 (uitgebracht op 9 juni 2026). Open op macOS de Codex App en controleer op updates. Doe hetzelfde op Windows. Als je Codex CLI gebruikt, zorg dan dat het compatibel is met de huidige App. Zonder de nieuwste versie verschijnt "Import other agent setup" niet in Settings.

2. Stap 2: Start de import vanuit Settings

   Open in de Codex App Settings en zoek "Import other agent setup". Als je de Codex App net hebt geïnstalleerd, biedt de wizard de migratie aan tijdens de onboarding. Zodra je start, scant de wizard het bestandssysteem: ~/.claude/ en repositories met CLAUDE.md of .claude/. Afhankelijk van het aantal bestanden duurt het scannen 30 seconden tot enkele minuten.

3. Stap 3: Bevestig het migratieplan

   Na het scannen toont Codex een inventaris: hoeveel skills zijn gevonden, hoeveel MCP-servers, hoeveel CLAUDE.md-bestanden, welke hooks in aanmerking komen voor migratie en hoeveel dagen sessiegeschiedenis beschikbaar zijn. Je kunt groepen die je niet wilt overzetten uitvinken. Standaard is alles geselecteerd wat Codex veilig kan importeren.

4. Stap 4: Wacht tot het klaar is en voer tokens in

   De import duurt 1–5 minuten. Wanneer deze klaar is, opent Codex een vervolgescherm: "dit kon ik niet automatisch overzetten; controleer het handmatig". Meestal is dit een lijst met MCP-servers waarvoor tokens nodig zijn. Open je wachtwoordmanager en voer de sleutels in het Codex-formulier in. Daarna is het grootste deel van de migratie voltooid.

Controleer vervolgens het resultaat. Open een project waaraan je gewoonlijk in Claude Code werkte en controleer het volgende:

• cat ~/.codex/AGENTS.md — staan je globale regels daar?
• Voer een willekeurige skill uit: $skill-name. Deze zou moeten laden.
• Open .mcp.json in het project en controleer of de vereiste servers actief zijn.
• Start een gesprek dat weergeeft hoe je gewoonlijk werkt. Codex toont welke geïmporteerde hooks het niet kan gebruiken; dit zijn concrete inventarisitems die je handmatig moet afhandelen; er is geen vast resterend aandeel vastgesteld.

Hooks en subagents: equivalenten in Codex en wat je moet herschrijven#

Hooks. In Claude Code kun je een shellcommando koppelen aan elke lifecyclegebeurtenis (pre-tool-use, post-tool-use, on-error, on-context-load, enzovoort). Codex heeft een kleinere set gebeurtenissen: het kan vóór uitvoering controleren, bewijs vastleggen en gevaarlijke commando's blokkeren. Als je een pre-tool-use-hook had die filterde op een specifieke combinatie, moet je die in Codex onderbrengen in een algemene controle vóór uitvoering of verwijderen. Ik heb de architectuur van Claude Code-hooks uitgebreid uitgelegd; gebruikte je ze veel, noteer dan elke trigger en vereist effect, vind een ondersteund equivalent en controleer dat vóór inschakelen.

Subagents. In Claude Code is een subagent een afzonderlijke context met een eigen systeemprompt, gestart via een /command of vanuit het hoofdgesprek. Codex heeft een vergelijkbaar concept in profielen: je kunt een profiel definiëren met een specifieke set skills, machtigingen en goedkeuringsbeleid. Profielen lossen ongeveer hetzelfde probleem op — een context isoleren voor een bepaalde categorie taken — maar via instellingen in plaats van een expliciete aanroep van een agent.

Wat dit in de praktijk betekent:

• Had je een subagent "security-reviewer" met een eigen prompt, maak dan in Codex een profiel security-review met de vereiste machtigingen en een hogere reasoning effort.
• Had je een subagent "feature-developer", dan is dat gewoon een standaard werkprofiel; er is niets bijzonders nodig.
• Als je geneste subagents gebruikte, werkt dat niet één-op-één in Codex; denk het opnieuw uit met een keten van profielen of expliciete skills.

De migratietool probeert profielen te maken met de namen van je subagents en markeert welke triggers niet zijn overgezet. Benodigd werk hangt af van rollen, triggers, rechten en afhankelijkheden; test elke vereiste pipeline voordat je die als gemigreerd beschouwt.

Wanneer volledig overstappen en wanneer beide tools behouden?#

Een eenvoudige beslisregel:

Volledig overstappen op Codex is zinvol als:

• Je vooral autonome PR's en parallelle taken uitvoert.
• Je GitHub-workflow diep geïntegreerd is en Codex Cloud Agent 80% van het werk afhandelt.
• Je niet veel tijd besteedt aan architectuurdiscussies en Plan Mode.
• Je liever voor één tool betaalt dan voor twee.

Claude Code + Codex samen blijven gebruiken als:

• Je Plan Mode regelmatig gebruikt voor lange architectuurbeslissingen.
• Je parallel werk nodig hebt: Codex draait in de cloud aan de ene taak terwijl Claude Code de context voor een andere vasthoudt.
• Je veel eenmalige hacks en microprojecten doet waarvoor Plan Mode overdreven is.
• Je een complexe subagentpipeline hebt die niet in één avond kan worden herschreven.

Zelf gebruik ik beide: Claude Code houdt het lange gesprek vast, terwijl Codex taken uitvoert zoals "N bugs parallel oplossen" of "een PR reviewen". Ik heb uitgebreider uitgelegd hoe dit werkt in de gids voor samenwerken met Claude Code en Codex.

Het belangrijkste dat ik over migratie wil zeggen is dit: de migratietool neemt de technische drempel voor overstappen weg, maar beantwoordt niet of je überhaupt moet overstappen. Bepaal eerst wat voor werk je doet. Kies daarna de tool.

Als je via Ailoot toegang wilt tot neurale netwerken, neem dan een kijkje bij Ailoot.