Cómo migrar de Claude Code a Codex en 2026: guía paso a paso

Documentación de Ailoot: API, claves y configuración.

¿Por qué hace falta la herramienta de migración de Codex?#

OpenAI añadió esta función a Codex a principios de junio de 2026. El registro de cambios oficial lo resume así:

En otras palabras: cuando inicias la aplicación Codex por primera vez, o desde la configuración de un cliente que ya está en ejecución, se inicia un asistente que lee las configuraciones locales de otro agente. Actualmente son compatibles Claude Code y Claude Cowork.

Está claro por qué OpenAI lo hace. Tras el lanzamiento de Sites y la actualización de la aplicación Codex en mayo-junio de 2026, Codex consiguió todo lo que Claude Code tenía antes frente a OpenAI: un terminal, plugins, sesiones largas y orquestación. La migración elimina la última barrera para los equipos que ya han integrado Claude Code en su stack: «pueden importarse los ajustes admitidos y comprobarse después contra el inventario original».

No está tan claro por qué podrías necesitarlo. Los comparé directamente en la guía de Codex frente a Claude Code: Claude sigue por delante en las conversaciones largas sobre arquitectura y el modo Plan, mientras que Codex es más rápido en las tareas autónomas y las PR en paralelo. Si has decidido cambiar por completo, sigue leyendo. Si estás considerando combinar las herramientas, quizá te interesen más los patrones de colaboración.

¿Qué transfiere automáticamente la herramienta de migración?#

Voy a repasar los grupos y explicar exactamente qué ocurre con cada elemento de ~/.claude.

1. Instrucciones y contexto. Los archivos CLAUDE.md —el global de ~/.claude/ y los archivos de proyecto en los repositorios— se convierten al formato AGENTS.md. El archivo global acaba en ~/.codex/AGENTS.md; los archivos de proyecto permanecen en la raíz del repositorio y en sus subcarpetas. El formato AGENTS.md es esencialmente el mismo tipo de archivo Markdown con reglas; las diferencias son principalmente cosméticas: los nombres de las secciones y un par de directivas específicas. He explicado qué es AGENTS.md y por qué Codex lo necesita.

2. Skills. Se analiza toda la carpeta ~/.claude/skills/; cada skill se adapta a la estructura de Codex y se coloca en $HOME/.agents/skills. Los skills del proyecto que están en .claude/skills/ dentro de un repositorio se trasladan a .agents/skills. El formato SKILL.md con frontmatter se transfiere prácticamente tal cual. Si un skill usa activadores específicos de Claude, se marca para revisión.

3. Servidores MCP. La configuración .mcp.json (tanto global como a nivel de proyecto) se importa al formato de Codex. Se conservan los nombres de los servidores, los comandos de inicio y las rutas. Lo que no se transfiere: los tokens y las variables de entorno. Por motivos de seguridad, Codex volverá a pedirte las claves API y las contraseñas para que no queden expuestas durante la migración. Es una tarea que solo hay que hacer una vez: abre la sección MCP en la aplicación Codex e introduce los tokens que ya tienes en tu gestor de contraseñas.

4. Hooks. Este es el grupo complicado. Los hooks con lógica determinista (bloquear rm -rf, alertar sobre rutas que parecen contener credenciales, registrar pruebas) se transfieren por completo. Los hooks con activadores que no tienen equivalente en Codex (por ejemplo, ciertos eventos del ciclo de vida específicos de Claude Code) se marcan para «revisión manual» y no se activan automáticamente. He explicado en detalle cómo funcionan los hooks en Claude Code, como referencia: Codex tiene menos tipos.

5. Historial de sesiones. Se importa como referencia hasta la actividad de Claude Code de los últimos 30 días. Esto no significa que puedas «continuar exactamente donde lo dejaste», pero tus conversaciones pasadas estarán visibles en Codex para que puedas recuperar rápidamente el contexto del proyecto sin tener que volver a explicarlo todo.

La herramienta de migración no distingue entre archivos activos y artefactos experimentales: lo transfiere todo. Después de la migración, conviene eliminar manualmente todo lo que no hayas usado en los últimos seis meses.

¿Qué NO se transfiere y por qué?#

Voy a repasar cada grupo desde la perspectiva de «qué hacer después de la migración».

Tokens de MCP y claves API. Esta es la parte más predecible. Después del análisis, Codex te mostrará una lista de todos los servidores MCP que encontró en Claude. Te pedirá las claves y los tokens de cada uno. Lo más fácil es tener a mano el gestor de contraseñas y revisar todos los servidores de una sola vez. Después, MCP funciona de la misma manera en Codex y Claude Code. Comprueba la documentación para verificar los parámetros de comando y conexión del servidor MCP que hayas elegido.

Comandos slash /name. En Claude Code, estás acostumbrado a invocar un skill con /skill-name. En Codex, la invocación canónica es distinta: $skill-name. Un error de migración habitual es tomar los comandos /name como prueba de que los skills se han cargado.

Después de la migración, prueba algunos skills clave con $skill-name en Codex. Si funcionan, la migración realmente se ha completado con éxito. No te fíes de la casilla «skills migrados» del asistente: compruébalo invocándolos.

Hooks sin equivalente en Codex. Si tenías un hook para eventos específicos de Claude Code —por ejemplo, en pre-tool-use para una combinación concreta de herramientas—, puede que ese activador no exista en Codex. La herramienta de migración los marcará y los dejará inactivos. Tendrás que decidir si los reescribes para que tengan un equivalente en Codex, los eliminas o los conservas en Claude Code (si lo ejecutas en paralelo). Una buena regla: transfiere solo los hooks deterministas; todo lo demás es una razón para no duplicar la escalera en la nueva herramienta.

Flujos de trabajo de equipo basados en subagentes. He explicado qué son los subagentes en Claude Code y cómo usar subagentes anidados. En Codex, los subagentes se organizan mediante perfiles y roles (véase más abajo). Si tenías en Claude un pipeline complejo con varios subagentes encadenados, tendrás que reescribirlo en torno al concepto de perfil de Codex. La herramienta de migración marca estas configuraciones como «requiere una reestructuración arquitectónica».

Archivos CLAUDE.md extensos y específicos de Claude. Si un archivo ha crecido hasta tener entre 2.000 y 3.000 líneas con secciones para cada proyecto, Codex puede aceptarlo, pero es una mala práctica. AGENTS.md está diseñado para ser compacto y estar distribuido: reglas globales en ~/.codex/AGENTS.md, reglas específicas del proyecto en la raíz del repositorio y anulaciones acotadas en las subcarpetas. Después de la migración, no dejes CLAUDE.md como un «archivo de instrucciones gigante»; divídelo en distintos niveles. He explicado cómo configurar CLAUDE.md correctamente; el mismo enfoque se aplica a AGENTS.md.

Paso a paso: 4 acciones en la aplicación Codex#

Esta es la lista de comprobación concreta.

1. Paso 1: actualiza la aplicación Codex a la versión 26.608 o posterior

   La herramienta de migración apareció en la versión 26.608 (publicada el 9 de junio de 2026). En macOS, abre la aplicación Codex y busca actualizaciones. Haz lo mismo en Windows. Si ejecutas Codex CLI, asegúrate de que sea compatible con la aplicación actual. Sin la última versión, «Importar la configuración de otro agente» no aparecerá en Configuración.

2. Paso 2: inicia la importación desde Configuración

   En la aplicación Codex, abre Configuración y busca «Importar la configuración de otro agente». Si acabas de instalar la aplicación Codex, el asistente te ofrecerá la migración durante la incorporación. Una vez iniciado, el asistente analiza el sistema de archivos: ~/.claude/ y los repositorios que contienen CLAUDE.md o .claude/. El análisis tarda entre 30 segundos y varios minutos, según el número de archivos.

3. Paso 3: confirma el plan de migración

   Después del análisis, Codex mostrará un inventario: cuántos skills se encontraron, cuántos servidores MCP, cuántos archivos CLAUDE.md se encontraron, qué hooks cumplen los requisitos para migrarse y cuántos días del historial de sesiones están disponibles. Puedes desmarcar cualquier grupo que no quieras transferir. De forma predeterminada, está seleccionado todo lo que Codex considera seguro importar.

4. Paso 4: espera a que termine e introduce los tokens

   La importación tarda entre 1 y 5 minutos. Cuando finalice, Codex abrirá una ventana de seguimiento: «esto es lo que no he podido transferir automáticamente; compruébalo manualmente». Normalmente, es una lista de servidores MCP que necesitan tokens. Abre el gestor de contraseñas e introduce las claves en el formulario de Codex. Después, la parte principal de la migración habrá terminado.

A continuación, verifica el resultado. Abre un proyecto en el que suelas trabajar con Claude Code y comprueba lo siguiente:

• cat ~/.codex/AGENTS.md — ¿están ahí tus reglas globales?
• Ejecuta cualquier skill: $skill-name. Debería cargarse.
• Abre .mcp.json en el proyecto y comprueba que los servidores necesarios estén en ejecución.
• Inicia una conversación que refleje tu forma habitual de trabajar. Codex te mostrará qué hooks importados no puede usar; son elementos concretos del inventario que debes resolver manualmente; no se acredita una proporción fija restante.

Hooks y subagentes: equivalentes en Codex y qué debes reescribir#

Hooks. En Claude Code puedes asociar un comando de shell a cada evento del ciclo de vida (pre-tool-use, post-tool-use, on-error, on-context-load, etc.). Codex tiene un conjunto de eventos más reducido: puede comprobar antes de la ejecución, registrar pruebas y bloquear comandos peligrosos. Si tenías un hook pre-tool-use que filtraba una combinación concreta, en Codex tendrás que integrarlo en una comprobación general previa a la ejecución o eliminarlo. He explicado en detalle la arquitectura de los hooks de Claude Code; si los usabas mucho, enumera cada activador y efecto requerido, identifica un equivalente admitido y verifícalo antes de activarlo.

Subagentes. En Claude Code, un subagente es un contexto separado con su propio prompt del sistema, iniciado mediante un /command o desde la conversación principal. Codex tiene un concepto similar en los perfiles: puedes definir un perfil con un conjunto específico de skills, permisos y una política de aprobación. Los perfiles resuelven más o menos el mismo problema —aislar el contexto para una clase concreta de tareas—, pero mediante la configuración y no invocando explícitamente a un agente.

En la práctica, esto significa lo siguiente:

• Si tenías un subagente «security-reviewer» con su propio prompt, crea en Codex un perfil security-review con los permisos necesarios y un nivel de razonamiento más alto.
• Si tenías un subagente «feature-developer», eso es simplemente un perfil de trabajo predeterminado; no hace falta nada especial.
• Si usabas subagentes anidados, no funcionará de la misma manera en Codex; replantea el flujo mediante una cadena de perfiles o skills explícitos.

La herramienta de migración intentará crear perfiles con los nombres de tus subagentes y señalará qué activadores no se transfirieron. El trabajo depende de roles, activadores, permisos y dependencias; prueba cada pipeline necesario antes de darlo por migrado.

Cuándo migrar por completo y cuándo conservar ambas herramientas#

Un filtro de decisión sencillo:

Cambiar por completo a Codex tiene sentido si:

• Principalmente haces PR autónomas y tareas en paralelo.
• Tu flujo de trabajo con GitHub está profundamente integrado y Codex Cloud Agent se encarga del 80 % del trabajo.
• No dedicas mucho tiempo a conversaciones sobre arquitectura y al modo Plan.
• Quieres pagar por una herramienta en lugar de dos.

Conservar Claude Code y Codex juntos si:

• Usas el modo Plan habitualmente para tomar decisiones de arquitectura complejas.
• Necesitas trabajar en paralelo: Codex se ejecuta en la nube en una tarea mientras Claude Code mantiene el contexto de otra.
• Haces muchos hacks puntuales y microproyectos para los que el modo Plan es excesivo.
• Tienes un pipeline complejo de subagentes que no se puede reescribir en una tarde.

Personalmente, uso ambas herramientas: Claude Code mantiene la conversación larga, mientras que Codex se ocupa de «corregir N errores en paralelo» o «revisar una PR». He explicado más sobre cómo funciona en la guía para trabajar con Claude Code y Codex juntos.

Lo principal que diría sobre la migración es esto: la herramienta elimina la barrera técnica para cambiar, pero no responde si necesitas cambiar en primer lugar. Decide primero qué tipo de trabajo haces. Luego elige la herramienta.

Si necesitas acceder a redes neuronales a través de Ailoot, echa un vistazo a Ailoot.