Migra de Claude Code a Codex (2026): 12 configs, 1 callejón sin salida

Puedes mover casi toda tu configuración de Claude Code a Codex en unos 20 minutos. Aquí está la decisión antes de seguir scrolleando:

Casi todo se mueve, porque las dos herramientas resuelven el mismo problema con formatos de archivo distintos. La migración es en gran parte una traducción entre dos dialectos.

Aquí está el mapa completo de superficies. Guarda esta tabla; es toda la migración en una pantalla.

Las filas 9 y 11 son cosméticas. No vas a extrañar outputStyle, y ConfigChange solo importa si construiste automatización que reacciona a un archivo de config cambiando a mitad de sesión. La fila 12 es la que detiene a la gente, y tiene un arreglo limpio que la mayoría de guías de migración omite.

Migra cuando tu trabajo tenga forma de tarea y quieras sandboxing más estricto; quédate en Claude Code cuando tu trabajo tenga forma de conversación y esté guiado por hooks. Las dos herramientas cargan modelos mentales distintos, y las diferencias de config siguen de ahí.

Antes de tocar la config, confirma los cuatro prerrequisitos de abajo. Un Codex desactualizado es la razón más común de que /import y los bloques [features] no hagan nada en silencio.

• Codex CLI 0.140.0 o más nuevo. Verifícalo con codex --version. El comando /import llegó en 0.140.0; esta guía se probó en 0.142.5.
• Tu proyecto de Claude Code existente, con su directorio .claude/ y CLAUDE.md intactos. No lo borres hasta que la migración esté verificada.
• Una API key del proveedor que vaya a manejar Codex. OpenAI por defecto, o una key de gateway si vas a mantener los modelos Claude.
• Acceso de escritura a ~/.codex/. Codex lee ~/.codex/config.toml en cada invocación y, en proyectos confiables, .codex/config.toml en la raíz del repo.

Corre primero el importador automatizado, luego recorre las cinco superficies que no puede manejar del todo. No te saltes los pases manuales — el importador es honesto sobre lo que deja atrás, pero sí deja cosas atrás.

Paso 1: Corre el importador

Inicia Codex en tu proyecto e importa. Codex 0.140 agregó /import para traer selectivamente setup, configuración de proyecto y chats recientes desde Claude Code. Elige las superficies que quieras.

cd mi-proyecto
codex
# luego, dentro de la sesión:
/import

Resultado esperado: un ~/.codex/config.toml poblado, un borrador de AGENTS.md y un reporte corto listando lo que se saltó o marcó como conflicto.

Paso 2: Instrucciones, de CLAUDE.md a AGENTS.md

Codex lee AGENTS.md, no CLAUDE.md. Si el importador no creó uno todavía, renombra tu archivo o dile a Codex que siga leyendo el nombre viejo.

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

Resultado esperado: tus instrucciones a nivel de repo cargan en el contexto de Codex en la próxima corrida. El contenido pasa sin cambios; solo el nombre de archivo y la ruta de carga difieren — que es justo por qué la convención AGENTS.md existe entre herramientas.

Paso 3: Servidores MCP, de JSON a TOML

Los procesos MCP son idénticos. Solo cambia la forma de la declaración. Una entrada de .mcp.json de Claude Code así:

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

se vuelve una tabla TOML en ~/.codex/config.toml:

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

Resultado esperado: codex lista las herramientas MCP de github al arrancar. Si un servidor necesita variables de entorno, agrégalas inline: env = { "GITHUB_TOKEN" = "..." }. Ambos transportes se mantienen: Codex acepta los mismos servidores STDIO basados en comando que corrías en Claude Code, y también toma servidores HTTP streaming en la misma tabla, así que un endpoint MCP alojado remotamente se mueve sin levantar un proceso local.

Paso 4: Subagentes a .codex/agents/

Claude Code guarda los subagentes como Markdown en .claude/agents/. Codex guarda cada subagente en su propio archivo TOML, uno por agente, bajo ~/.codex/agents/ (personal) o .codex/agents/ (scoped al proyecto). Los subagentes vienen habilitados por defecto, así que no hay feature flag que voltear.

# .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.
"""

Resultado esperado: el rol reviewer queda disponible a través del flujo de subagentes de Codex, que Codex invoca solo cuando se lo pides explícitamente. El cuerpo del prompt de tu viejo archivo Markdown pasa a developer_instructions; lo que cambia es el wrapper. Si tenías muchos subagentes, este es el pase manual más tedioso, pero es mecánico.

Paso 5: Permisos a Sandbox y Approval

Esta es la superficie que genuinamente se rompe, porque las dos herramientas modelan la seguridad distinto. Claude Code usa una allowlist por comando con reglas glob. Codex usa dos diales gruesos: un sandbox de filesystem y una approval policy. No hay un mapeo uno a uno limpio, así que portas intención, no reglas.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Resultado esperado: Codex corre libre dentro del repo y pregunta antes de tocar algo fuera de él o llegar a la red. El control granular por comando que tenías en Claude Code no sobrevive; si dependías de una allowlist larga y precisa, acepta que el modelo de Codex es más contundente por diseño.

Paso 6: Hooks

Codex ya tiene hooks, habilitados por defecto, y cubren la mayoría de los eventos de Claude Code. Los declaras como bloques array-of-tables en config.toml; para apagar todo el sistema setearías [features] hooks = false.

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"          # misma idea que el matcher PreToolUse de Claude Code

  [[hooks.PreToolUse.hooks]]
  type = "command"
  command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

Resultado esperado: PreToolUse, PostToolUse, SessionStart, Stop e incluso PreCompact/PostCompact disparan como lo hacían en Claude Code, una vez que traduces el handler de JSON a TOML. La única brecha es ConfigChange, que no tiene evento en Codex — cualquier automatización que hayas construido para reaccionar a un archivo de config cambiando a mitad de sesión es la única parte de tu setup de hooks que no viene.

El único paso de migración sin respuesta nativa es mantener tus modelos Claude, porque Codex vanilla autentica contra OpenAI y maneja modelos de OpenAI como gpt-5.5 y gpt-5.4. No hay un switch integrado que seleccione Claude Opus o Sonnet. Si migraste a Codex por su sandbox y flujo pero aún quieres Opus escribiendo tu código, necesitas un puente.

El puente es un model_provider custom. Codex habla con cualquier gateway compatible con OpenAI, así que registras uno y apuntas un profile a un modelo Claude. Agrega el provider a ~/.codex/config.toml:

# ~/.codex/config.toml — registra un gateway compatible con OpenAI

[model_providers.gateway]
name = "tu gateway"
base_url = "https://tu-gateway.ejemplo/v1"
env_key = "GATEWAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Dos detalles hacen tropezar a la gente. Ambos son sobre cómo Codex negocia el protocolo de comunicación, no sobre el gateway en sí.

Luego crea un archivo de profile en ~/.codex/claude.config.toml:

model = "anthropic/claude-opus-4.8"
model_provider = "gateway"

Córralo con codex --profile claude. Ahora el bucle de tarea y el sandbox de Codex manejan el anthropic/claude-opus-4.8 de Anthropic, y cambiar model = "openai/gpt-5.5" en un segundo profile te deja hacer A/B entre los dos sin cambiar la auth. Esta es la única superficie de migración donde un gateway no es una conveniencia sino la única forma de mantener lo que viniste a buscar.

Seis fallos cubren casi toda migración atascada. El patrón es el mismo cada vez: un supuesto de Claude Code que Codex no comparte.

Si un .codex/config.toml de proyecto se ignora por completo, verifica que el proyecto esté marcado como confiable. Codex solo carga config scoped al proyecto en directorios confiables, y no deja que un archivo de proyecto sobreescriba provider, auth o selección de profile.

Para un equipo, la migración es más limpia que el caso individual, porque Codex colapsa dos archivos de Claude Code en una config commiteada. En Claude Code mandabas un .claude/settings.json para el equipo y dejabas a cada dev mantener un .claude/settings.local.json gitignored. En Codex, commiteas un único .codex/config.toml en la raíz del repo y dejas que cada dev elija un profile.

El beneficio de equipo es el mismo truco de gateway de la sección del callejón, aplicado una vez. Registra un model_provider en la config commiteada, entrega a cada dev el mismo esquema de key de gateway vía tu secret manager, y todo el equipo rutea por un endpoint con una sola vista de billing — ya corran openai/gpt-5.5 o anthropic/claude-opus-4.8. Ese ruteo de un solo endpoint es la razón concreta por la que un gateway compartido le gana a keys de provider por desarrollador.

Los profiles son donde Codex devuelve el esfuerzo de migración, porque reemplazan el hábito de Claude Code de hacer malabares con settings.json contra settings.local.json. Un profile es un archivo separado bajo ~/.codex/, y lo eliges por corrida con --profile. Nada cambia globalmente hasta que tú decidas.

Crea tres archivos para tres posturas de riesgo. El config.toml base guarda las piezas compartidas — providers, servidores MCP y hooks; cada profile sobreescribe solo las dos o tres keys que difieren. Esa disciplina de un solo archivo es lo que hace al setup de Codex más fácil de razonar que la pila de scopes de Claude Code, una vez que la migración queda atrás.

# ~/.codex/ci.config.toml

model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"

Corre review automatizado en CI con codex --profile ci, y puede leer todo pero no cambiar nada. Mantén un local.config.toml en workspace-write para el trabajo del día a día, y el claude.config.toml de la sección del callejón que cambia el driver a anthropic/claude-opus-4.8 cuando quieras el modelo de Anthropic en un problema difícil.

La mayoría de guías de migración venden el rename. La lección real es que tu config de tooling no es la herramienta — es un contrato, y el contrato de Codex es más contundente y más componible que el de Claude Code.

Cuando una superficie "se rompe", suele significar que la herramienta nueva eligió una abstracción más gruesa a propósito. El sandbox de dos diales de Codex reemplaza una allowlist por comando porque los diales gruesos sobreviven a un equipo de veinte devs tocando el mismo repo; una allowlist ajustada a mano no. Eso es un trade-off, no un bug.

El callejón sin salida es la parte honesta. Ningún vendor va a hacer trivial correr el modelo de un competidor dentro de su CLI. Que el arreglo sea un único bloque model_provider — y no un fork ni un script wrapper — te dice que Codex trata a los providers como enchufables. La migración que importa es la que mantiene tus opciones abiertas.

Migrar tu tooling a Codex no debería significar renunciar a los modelos por los que migraste, y con un bloque de provider no lo hace.

La migración que importa no es el rename — es la que mantiene tus modelos enchufables, tu sandbox honesto y tus opciones abiertas.

• OpenAI Codex Configuration Reference
• OpenAI Codex Changelog
• OpenAI Codex Hooks Reference
• Claude Code Settings Reference

Sobre FACTA

FACTA es una consultora de IA. Diseñamos sistemas de agentes, construimos los flujos a su alrededor y ayudamos a los equipos a adoptar IA sin apostar todo a un solo vendor.

Escribimos estas guías porque la parte más difícil del tooling de IA rara vez es el modelo — es la config, el sandboxing y los contratos que firmas con tus herramientas. Una migración es buen momento para mirar esos contratos en vez de solo renombrarlos.

Si estás evaluando una migración Claude Code → Codex, o quieres un stack de agentes vendor-neutral que mantenga tus opciones abiertas, podemos ayudar.

Vendor-neutral por diseño. Enchufable por hábito.