Codex incluye un importador de un solo comando que migra automáticamente la gran mayoría de configuraciones de Claude Code. El desafío reside en los detalles operativos: ciertos bloques deben ajustarse manualmente, y un elemento no se transfiere de forma nativa — los propios modelos de Anthropic.

Completar la migración de casi todo el entorno de Claude Code a Codex requiere aproximadamente 20 minutos. A continuación se detallan las pautas fundamentales para una transición sin fricciones.

1. Qué se migra y qué no — veredicto rápido

1.1. Diagnóstico rápido: matriz de compatibilidad de superficies

Pregunta	Solución / Respuesta
¿Se puede transferir la mayor parte de la configuración?	Sí. 9 de las 12 superficies se migran o reconfiguran sin problemas.
¿Cuál es la vía más rápida?	Ejecutar `codex` → `/import` (Codex 0.140+), y luego ajustar manualmente 3 puntos.
¿Qué se migra automáticamente?	Archivos de instrucciones, servidores MCP, skills, comandos slash y endpoints.
¿Qué requiere ajuste manual?	Modelo de permisos, formato de hooks y descriptores de subagentes.
¿Cuál es el único punto ciego real?	Modelos Anthropic Claude. Codex estándar solo admite modelos de OpenAI.
¿Cuál es la solución al punto ciego?	Configurar una puerta de enlace como `model_provider` para usar Claude en Codex.

📌 Versiones del entorno: Guía validada con Codex CLI 0.142.5 (1 de julio de 2026) y Claude Code 2.1.178. Si dispone de una versión anterior de Codex, actualice primero: el comando /import se introdujo en la versión 0.140.0.

1.2. Componentes automáticos y manuales de la migración

Elementos que se transfieren de forma directa:

Instrucciones para el repositorio y directrices personales (contenido de CLAUDE.md).
Servidores MCP — comandos y argumentos binarios se conservan literalmente.
Skills — ambas plataformas respetan el estándar unificado Agent Skills.
Comandos slash y plantillas de prompts reutilizables.
Endpoints de API personalizados y tokens de autenticación.

Elementos que requieren adaptación o soluciones alternativas:

Lista de permisos por comando (permissions.allow) — Codex utiliza un esquema de sandbox por capas.
Evento de hook ConfigChange (Codex dispone de PreCompact/PostCompact, pero no escucha cambios en el archivo de configuración).
Estilos de salida (outputStyle) — el concepto no existe en Codex.
Modelos de Anthropic — Codex opera de forma nativa únicamente con OpenAI; Claude requiere una puerta de enlace.

2. Mapa completo: las 12 configuraciones de Claude Code y sus análogos en Codex

2.1. Matriz comparativa de superficies de configuración

Ambas herramientas resuelven idénticos problemas de automatización mediante paradigmas de almacenamiento diferenciados: Claude Code utiliza JSON (settings.json, .mcp.json) y Markdown (CLAUDE.md, .claude/agents/*.md), mientras que Codex centraliza la configuración en un archivo TOML (~/.codex/config.toml) junto con AGENTS.md.

#	Superficie en Claude Code	Equivalente en Codex CLI	Veredicto de migración
1	`CLAUDE.md` (memoria)	`AGENTS.md` (o archivo de respaldo)	Migración directa
2	`.mcp.json` (JSON)	`[mcp_servers.*]` en `config.toml`	Migración con reformateo
3	`.claude/skills/`	Codex skills (`[[skills.config]]`)	Migración directa
4	`.claude/commands/`	Comandos slash / prompts	Migración con reestructuración
5	`.claude/agents/` (Markdown)	Archivos `.codex/agents/*.toml`	Reconstrucción en TOML
6	`settings.json` (JSON)	`config.toml` + perfiles (TOML)	Reconstrucción en TOML
7	`permissions.allow/ask/deny`	`approval_policy` + `sandbox_mode`	Reconceptualización
8	Hooks (`PreToolUse`, `Stop`, …)	`[[hooks.*]]` en `config.toml`	Reconstrucción en TOML
9	Hook `ConfigChange`	Sin equivalente	Sin equivalente directo
10	Endpoint `ANTHROPIC_BASE_URL`	`[model_providers.*]`	Migración directa
11	`outputStyle`	Sin equivalente	Sin equivalente directo
12	Modelos Anthropic Claude	Solo modelos OpenAI por defecto	Punto ciego (resuelto vía proxy)

2.2. Diferencias arquitectónicas clave: JSON vs TOML

Las filas 9 y 11 son superficiales: la ausencia de outputStyle no perjudica el rendimiento, y ConfigChange solo es relevante para flujos que modifican configuraciones dinámicamente en plena sesión.

El obstáculo principal radica en la fila 12 (modelos de Anthropic). No obstante, la declaración de un proxy compatible en la sección [model_providers] permite ejecutar Claude Opus y Sonnet dentro del entorno aislado de Codex sin fricciones.

3. Cuándo migrar y cuándo quedarse en Claude Code

3.1. Flujos de trabajo y criterios para migrar a Codex

Migrar a Codex resulta conveniente cuando los proyectos priorizan tareas desatendidas y un aislamiento estricto del sistema de archivos:

Automatización en CI/CD: Necesidad de ejecutar agentes de forma no interactiva con modos predecibles read-only o workspace-write.
Estandarización de equipos: Definir un único archivo config.toml en el repositorio con perfiles de riesgo preconfigurados, en lugar de dispersar archivos .claude/settings.local.json.
Últimos modelos de OpenAI Codex: Acceso directo a gpt-5.5 y gpt-5.4 como motor central de generación de código.

3.2. Casos en los que conviene permanecer en Claude Code

Conviene continuar en Claude Code bajo las siguientes condiciones:

Dependencia de hooks concretos: Uso de disparadores ConfigChange o directivas de formato outputStyle.
Flujo conversacional interactivo: Sesiones prolongadas basadas en diálogo; el modelo conversacional de Claude Code maneja mejor la alternancia interactiva que el bucle por lotes «tarea → revisión» de Codex.
Listas de permisos muy específicas: Si ha construido un allowlist minucioso con expresiones regulares para cada binario, la transición a las políticas más amplias del sandbox de Codex requerirá replantear su modelo de seguridad.

💡 Regla de parada: Si su objetivo exclusivo es evaluar el rendimiento de los modelos de Codex en un repositorio existente, no rediseñe toda la configuración. Simplemente ejecute /import dentro de Codex y analice los resultados. La personalización profunda solo es requerida al adoptar Codex como herramienta principal.

4. Requisitos del sistema antes de comenzar

4.1. Verificación de versiones de CLI, proyecto y permisos

Antes de modificar los archivos de configuración, compruebe cuatro requisitos básicos:

Codex CLI versión 0.140.0 o superior: Verifique la instalación con el comando codex --version.
Proyecto Claude Code intacto: Mantenga el directorio .claude/ y el archivo CLAUDE.md sin alterar hasta verificar la migración.
Clave API operativa: Disponga de una clave de OpenAI o credenciales de una puerta de enlace (por ejemplo, ofox.ai) para modelos Claude.
Permisos de escritura locales: Codex consulta ~/.codex/config.toml en cada inicio.

4.2. Ruta de migración: pipeline de transición paso a paso

El proceso de transición se estructura en seis etapas consecutivas:

mermaid

flowchart LR A["Auditoría CLAUDE.md + settings.json"] --> B["Ejecutar codex /import"] B --> C["Revisión del reporte de conflictos"] C --> D["Ajuste manual de permisos y hooks"] D --> E["Añadir model_provider para Claude"] E --> F["Prueba con perfil read-only"]

5. Migración de configuración paso a paso

5.1. Paso 1: Ejecutar el importador automático (/import)

Acceda a la raíz de su proyecto e invoque la herramienta interactiva de importación:

bash

cd my-project codex # Dentro de la sesión interactiva de Codex: /import

El comando /import transfiere selectivamente los parámetros del proyecto, las instrucciones y el contexto reciente. El resultado es un archivo base ~/.codex/config.toml, un borrador de AGENTS.md y un registro detallado de elementos omitidos.

5.2. Paso 2: Instrucciones — migrar de CLAUDE.md a AGENTS.md

Codex busca automáticamente AGENTS.md. Para conservar la compatibilidad con repositorios existentes sin duplicar archivos, declare rutas de reserva:

toml

# ~/.codex/config.toml project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] project_doc_max_bytes = 32768

Las instrucciones del proyecto, pautas de estilo, comandos de compilación y pruebas unitarias se cargarán directamente en la memoria del agente.

5.3. Paso 3: Servidores MCP — convertir de JSON a TOML

Ambos ecosistemas implementan el estándar Model Context Protocol. Los binarios de los servidores no varían; únicamente se transforma la declaración de JSON a tablas TOML.

Entrada original en .mcp.json:

json

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }

Configuración equivalente en ~/.codex/config.toml:

toml

[mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"]

Si el servidor necesita variables de entorno, establézcalas en línea: env = { GITHUB_TOKEN = "..." }. Se admiten tanto procesos locales STDIO como conexiones remotas SSE/HTTP.

5.4. Paso 4: Subagentes — configurar en .codex/agents/

Claude Code almacena subagentes como archivos Markdown en .claude/agents/. Codex utiliza archivos TOML individuales en ~/.codex/agents/ (globales) o .codex/agents/ (de proyecto):

toml

# .codex/agents/reviewer.toml name = "reviewer" description = "Reviews diffs for correctness and style" developer_instructions = """ Review the diff for correctness and style. Cite file and line for each issue found. """

Los subagentes en Codex están habilitados por defecto y se ejecutan ante llamadas explícitas del usuario o del agente principal.

5.5. Paso 5: Modelo de permisos — configurar sandbox y approval

La concepción de seguridad varía sensiblemente: en lugar de un allowlist detallado con expresiones glob (permissions.allow), Codex emplea niveles de aislamiento del sistema de archivos (sandbox_mode) y confirmación de operaciones (approval_policy).

Patrón en Claude Code	Finalidad	Equivalente en Codex (`~/.codex/config.toml`)
`allow: ["Bash(npm run test *)"]`	Ejecución desatendida de comandos seguros	`sandbox_mode = "workspace-write"` `approval_policy = "on-request"`
`ask: ["Bash(python *)"]`	Solicitar confirmación previa	`approval_policy = "on-request"`
`deny: ["Read(./.env)"]`	Bloquear rutas externas sensibles	`sandbox_mode = "workspace-write"`
`Plan mode`	Inspección y análisis sin escritura	`sandbox_mode = "read-only"`
`--dangerously-skip-permissions`	Autonomía sin restricciones	`approval_policy = "never"` `sandbox_mode = "danger-full-access"`

Configuración de seguridad equilibrada recomendada:

toml

# ~/.codex/config.toml approval_policy = "on-request" sandbox_mode = "workspace-write"

5.6. Paso 6: Hooks — portar manejadores de eventos del ciclo de vida

Codex admite de forma nativa hooks de ciclo de vida para eventos clave: PreToolUse, PostToolUse, SessionStart, Stop, PreCompact y PostCompact.

toml

# ~/.codex/config.toml [[hooks.PreToolUse]] matcher = "^Bash$" [[hooks.PreToolUse.hooks]] type = "command" command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

⚠️ Advertencia importante: El hook ConfigChange no tiene soporte en Codex. Cualquier lógica orientada a reaccionar a cambios en tiempo de ejecución debe delegarse a scripts ejecutados antes de la sesión.

6. Punto ciego de la migración: modelos Claude en Codex y cómo conservarlos

6.1. Arquitectura de puerta de enlace model_provider para Anthropic

Codex fue diseñado para interactuar con modelos de OpenAI (gpt-5.5, gpt-5.4) y carece de un selector nativo para Anthropic. Para emplear Claude Opus o Claude Sonnet dentro del flujo de trabajo de Codex, se utiliza un proxy intermedio compatible con el API de OpenAI.

Registre el proveedor en ~/.codex/config.toml:

toml

# ~/.codex/config.toml [model_providers.ofox] name = "ofox.ai gateway" base_url = "https://api.ofox.ai/v1" env_key = "OFOX_API_KEY" wire_api = "responses" requires_openai_auth = false

6.2. Configuración de wire_api=responses y activación del perfil claude

Al integrar un proveedor externo, dos parámetros son críticos:

wire_api = "responses": El protocolo obsoleto chat se retiró de Codex en febrero de 2026.
requires_openai_auth = false: Desactiva la verificación del prefijo estándar sk- de OpenAI en el cliente.

Defina el perfil correspondiente en ~/.codex/claude.config.toml:

toml

# ~/.codex/claude.config.toml model = "anthropic/claude-opus-4.8" model_provider = "ofox"

Inicie Codex con dicho perfil ejecutando:

bash

codex --profile claude

7. Errores comunes de migración y sus soluciones

7.1. Matriz de resolución de problemas y causas raíz

Síntoma	Causa raíz	Solución de ingeniería
Codex no reconoce `CLAUDE.md`	Busca `AGENTS.md` por defecto	Renombrar el archivo o añadir `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]`
El proveedor personalizado devuelve `401`	El cliente espera tokens con formato `sk-`	Incluir `requires_openai_auth = false` en `[model_providers.*]`
Error de arranque: `chat wire API deprecated`	Protocolo `chat` obsoleto y eliminado	Configurar `wire_api = "responses"`
Los subagentes no realizan acciones	Archivo TOML ausente o falta de llamada explícita	Crear `.codex/agents/NAME.toml`; Codex solo inicia subagentes mediante comando directo
Los hooks no se activan	Nombre de evento erróneo o regex defectuoso	Verificar el nombre del evento y la expresión regular `matcher` en `[[hooks.*]]`
Comandos previamente autorizados son bloqueados	El sandbox de Codex opera con mayor rigidez	Ampliar `sandbox_mode` o fijar `approval_policy = "on-request"`

7.2. Configuración de confianza del proyecto y precedencia

Si el archivo .codex/config.toml ubicado en el proyecto es ignorado por completo, compruebe el estado de confianza del repositorio. Por motivos de seguridad, Codex únicamente evalúa configuraciones de proyecto en rutas explícitamente marcadas como de confianza y restringe la modificación de credenciales o proveedores globales desde archivos locales.

8. Migración para equipos

8.1. Centralización en config.toml frente a archivos .local.json

En Claude Code, los equipos debían coordinar dos capas: .claude/settings.json en el repositorio y archivos locales ignorados .claude/settings.local.json. En Codex, el esquema se simplifica:

Aspecto de colaboración	Claude Code	OpenAI Codex CLI
Configuración compartida	`.claude/settings.json` (versionado)	`.codex/config.toml` (versionado en git)
Ajustes individuales	`.claude/settings.local.json`	Archivos de perfil individuales en `~/.codex/`
Instrucciones de proyecto	`CLAUDE.md`	`AGENTS.md`
Gestión de riesgos	`permission allowlist`	Indicadores `--profile strict` o `--profile fast`

8.2. Puerta de enlace API compartida y facturación unificada

Centralizar el acceso mediante un model_provider ofrece ventajas organizativas:

Los parámetros del proxy se versionan en el archivo .codex/config.toml del equipo.
Los desarrolladores introducen sus credenciales mediante un gestor de secretos común (OFOX_API_KEY).
Todo el equipo opera bajo un único punto de enrutamiento y facturación centralizada, tanto si un ingeniero utiliza openai/gpt-5.5 como si emplea anthropic/claude-opus-4.8.

9. Nivel avanzado: perfiles para CI, trabajo local y revisión

9.1. Configuración de perfiles de seguridad por niveles

Los perfiles son archivos independientes alojados en ~/.codex/ que se invocan puntualmente mediante la bandera --profile. Esto evita sobreescribir la configuración global ante diferentes tareas.

Configuración para auditorías automáticas en CI:

toml

# ~/.codex/ci.config.toml model = "gpt-5.5" approval_policy = "never" sandbox_mode = "read-only"

9.2. Escenarios prácticos: revisión aislada en CI y desarrollo local

El comando codex --profile ci garantiza una inspección de código segura en modo solo lectura, previniendo modificaciones o accesos de red no deseados.

Para el trabajo cotidiano se utiliza local.config.toml con sandbox_mode = "workspace-write", mientras que tareas de análisis arquitectónico complejo se delegan a codex --profile claude, ejecutando Claude Opus sin alterar los parámetros base de la estación de trabajo.

10. Preguntas frecuentes (FAQ)

10.1. Compatibilidad de modelos y archivos de configuración

❓ ¿Es posible utilizar modelos Claude en Codex CLI directamente?
Codex incluye soporte nativo únicamente para modelos de OpenAI. No obstante, puede conectar modelos de Anthropic (como anthropic/claude-opus-4.8) registrando una puerta de enlace compatible en la sección [model_providers] y asignándola a un perfil específico.

❓ ¿Reconoce Codex CLI el archivo CLAUDE.md existente?
De forma predeterminada busca AGENTS.md. Para continuar utilizando el archivo anterior sin duplicidades, añada project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"] en ~/.codex/config.toml.

❓ ¿Cómo se importan las configuraciones de Claude Code a Codex?
Ejecute codex en la raíz del proyecto y teclee /import. La herramienta automatizada transferirá las instrucciones, servidores MCP y comandos slash, generando un resumen de los puntos que requieren atención manual.

❓ ¿Existe diferencia entre AGENTS.md y CLAUDE.md?
En funcionalidad son equivalentes. AGENTS.md es un estándar abierto multipropósito adoptado por la industria, mientras que CLAUDE.md es el formato propietario de Claude Code. El cuerpo de las instrucciones se interpreta idénticamente.

10.2. Aspectos técnicos de hooks, MCP y subagentes

❓ ¿Dispone Codex CLI de un sistema de hooks similar al de Claude Code?
Sí, y está activo de manera predeterminada. Admite eventos como PreToolUse, PostToolUse, SessionStart, Stop, PreCompact y PostCompact. El único hook de Claude Code que carece de equivalente es ConfigChange.

❓ ¿Pueden Claude Code y Codex compartir los mismos servidores MCP?
Sí. La arquitectura y los binarios de los servidores MCP son idénticos. Únicamente varía la sintaxis de definición: en lugar de un bloque JSON en .mcp.json, se declaran como tablas TOML en config.toml.

❓ ¿Se deben reprogramar los subagentes al migrar?
No, las instrucciones de los prompts se conservan íntegras. Solo cambia el contenedor: el contenido de los archivos Markdown en .claude/agents/*.md se traslada al atributo developer_instructions dentro de .codex/agents/*.toml.