Cómo usar Codex CLI: guía paso a paso

Para usar Codex CLI, instálalo con un solo comando, ejecuta codex dentro de la carpeta de un proyecto, inicia sesión con tu cuenta de ChatGPT y describe en lenguaje natural el cambio que quieres. Codex lee el código, edita archivos y ejecuta comandos dentro del proyecto, y pregunta antes de salir de la carpeta o de usar la red.

Ese es el ciclo básico. Esta guía cubre el resto: los modos de aprobación y sandbox, el archivo AGENTS.md, config.toml, los servidores MCP, los comandos que usarás a diario, cómo retomar sesiones y algunos hábitos que hacen a Codex más fiable. Todo sigue la documentación oficial de Codex de OpenAI a octubre de 2026.

Qué es Codex CLI

Codex CLI es el agente de programación de OpenAI para la terminal. Se ejecuta en local, trabaja sobre la carpeta desde la que lo lanzas y puede ejecutar tus tests, tus linters y git. El mismo Codex existe también como extensión para el IDE, app de escritorio y versión en la nube, y todos comparten tu inicio de sesión. Si estás decidiendo qué agente usar, Claude Code vs Codex y Codex vs Gemini CLI los comparan en detalle. En resumen, Codex es un agente de programación, no un autocompletado: le das una tarea, la planifica y la lleva a cabo.

Paso 1: instala Codex CLI

OpenAI ofrece un script de instalación para cada plataforma, y la CLI también está en npm y Homebrew.

Para actualizar, vuelve a ejecutar el mismo script, ejecuta codex update o usa tu gestor de paquetes (brew upgrade --cask codex). Comprueba que ha funcionado:

codex --version

Paso 2: inicia sesión

Entra en un proyecto y arranca Codex:

cd mi-proyecto
codex

La primera vez, Codex te pregunta cómo quieres iniciar sesión:

• Sign in with ChatGPT: usa tu plan de ChatGPT y el uso cuenta contra sus límites. Es la opción habitual y la única que también da acceso a Codex cloud.
• API key: usa una API key de OpenAI y se factura por token. Útil para CI o si prefieres pagar por uso.

También puedes gestionarlo desde la shell. codex login abre el inicio de sesión en el navegador, codex login --device-auth te da un código de dispositivo para una máquina remota o sin pantalla, codex login status te dice si has iniciado sesión y codex logout borra las credenciales guardadas. Para iniciar sesión con una key sin escribirla, pásala por una tubería: printenv OPENAI_API_KEY | codex login --with-api-key.

En el momento de escribir esto, Codex está incluido en ChatGPT Free, Go, Plus, Pro, Business, Edu y Enterprise. Los planes superiores dan límites más altos; consulta la página de precios de Codex de OpenAI para ver las cifras actuales. Dentro de una sesión puedes ver en qué punto estás en cualquier momento con /status o /usage.

Paso 3: tu primera tarea

Empieza con algo pequeño y real para ver cómo trabaja Codex:

Explica cómo funciona la autenticación en este proyecto y luego añade un test
para el flujo de restablecimiento de contraseña. Ejecuta los tests al terminar.

Codex lee los archivos relevantes, cuenta qué piensa hacer, edita el código y ejecuta los tests. Algunas cosas lo hacen más fluido:

• Escribe @ para buscar un archivo y adjuntarlo al prompt.
• Empieza una línea con ! para ejecutar tú mismo un comando de shell, por ejemplo !git status.
• Mientras Codex trabaja, pulsa Enter para añadir instrucciones al turno actual, o Tab para dejar en cola un mensaje para cuando termine.
• Pulsa Esc dos veces con la entrada vacía para editar tu mensaje anterior y continuar desde ahí.
• /diff muestra qué ha cambiado, incluidos los archivos sin seguimiento.

Para capturas de pantalla o maquetas de diseño, adjunta imágenes con codex --image ruta/al/archivo.png o pégalas en el prompt.

Paso 4: modos de aprobación y sandbox

Esta es la parte que conviene entender antes de darle a Codex trabajos más grandes. Codex combina dos ajustes: un sandbox, que limita lo que los comandos pueden hacer técnicamente, y una política de aprobación, que decide cuándo se detiene a preguntarte.

Dentro de una sesión, /permissions alterna entre Auto y Read Only. En el sandbox workspace-write el acceso a la red está desactivado por defecto; puedes activarlo en config.toml (lo verás más abajo) si tus tests lo necesitan.

Si Codex necesita escribir en una segunda carpeta, por ejemplo una librería compartida junto a tu proyecto, usa --add-dir en lugar de pasar a acceso total. OpenAI desaconseja explícitamente --dangerously-bypass-approvals-and-sandbox (alias --yolo) fuera de una máquina virtual dedicada y aislada.

El sandbox es un aislamiento real del sistema operativo: Seatbelt en macOS, bubblewrap con seccomp en Linux y un sandbox nativo en Windows. Dentro de WSL2, Codex usa el sandbox de Linux. Para ver el panorama completo de lo que puede salir mal con los agentes y cómo limitarlo, lee seguridad de los agentes de programación con IA.

Paso 5: escribe un AGENTS.md

AGENTS.md es un archivo Markdown con instrucciones que Codex lee antes de ponerse a trabajar. Ahí va lo que, si no, repetirías en cada prompt: cómo compilar y probar, el estilo de código, las carpetas que no hay que tocar.

Ejecuta /init en una sesión y Codex genera una primera versión. Una buena es corta y concreta:

# AGENTS.md

## Comandos
- Instalar: pnpm install
- Test: pnpm test (ejecútalo antes de dar una tarea por terminada)
- Lint: pnpm lint

## Convenciones
- TypeScript en modo strict, nada de any.
- Las rutas nuevas de la API van en src/routes y necesitan un test.

## No hagas
- No edites archivos en src/generated.
- No añadas dependencias sin preguntar.

Codex busca estos archivos en un orden fijo:

1. Global: ~/.codex/AGENTS.md (o AGENTS.override.md para sustituirlo temporalmente). Úsalo para tus preferencias personales.
2. Proyecto: desde la raíz de git hasta la carpeta en la que estás, Codex toma como máximo un archivo por directorio; primero busca AGENTS.override.md y luego AGENTS.md.

Los archivos se unen de la raíz hacia abajo, así que las instrucciones de una subcarpeta llegan después y prevalecen sobre las generales. El tamaño combinado está limitado a 32 KiB por defecto (project_doc_max_bytes), otro motivo para mantenerlos breves. Como AGENTS.md es un formato compartido, otros agentes también lo leen; CLAUDE.md vs AGENTS.md explica cómo mantener un único conjunto de reglas para varias herramientas.

Paso 6: config.toml

Los ajustes de Codex viven en archivos TOML:

• ~/.codex/config.toml para tus ajustes de usuario;
• .codex/config.toml dentro de un proyecto, que Codex solo carga después de que marques el proyecto como de confianza.

Un ejemplo pequeño:

model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

model fija el modelo predeterminado (ejecuta /model en una sesión para ver qué ofrece tu cuenta). model_reasoning_effort controla cuánto piensa el modelo. web_search puede ser cached (el valor por defecto), live o disabled; el flag --search activa la búsqueda en vivo para una ejecución.

Los ajustes se aplican en este orden, de mayor a menor prioridad: flags de la línea de comandos y -c clave=valor, la configuración del proyecto, un perfil con nombre que eliges con --profile, tu configuración de usuario y, por último, la del sistema. Así, codex -c model_reasoning_effort="high" cambia el esfuerzo para una ejecución sin tocar tus archivos. Si no tienes claro qué valor ha ganado, /debug-config muestra las capas.

Paso 7: conecta servidores MCP

MCP permite a Codex usar herramientas externas: búsqueda en documentación, un navegador, tu gestor de incidencias, una base de datos. Añade un servidor con un solo comando:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Todo lo que va después de -- es el comando que arranca el servidor. Pasa variables de entorno con --env VAR=valor. Para un servidor remoto, usa codex mcp add <nombre> --url https://..., y si usa OAuth, inicia sesión con codex mcp login <nombre>. codex mcp list muestra lo que tienes configurado.

Los mismos servidores se pueden escribir a mano en config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Dentro de una sesión, /mcp lista los servidores activos y sus herramientas. Si el concepto es nuevo para ti, qué es un servidor MCP es una buena introducción. Mantén la lista corta: cada servidor añade descripciones de herramientas a la ventana de contexto.

Paso 8: los comandos que conviene conocer

Los comandos slash funcionan dentro de una sesión:

Y algunos subcomandos desde la shell:

Para automatizar, el que hay que recordar es codex exec. Imprime el resultado y termina, acepta --json para una salida legible por máquinas y --output-last-message para guardar la respuesta final en un archivo. En CI, combínalo con un sandbox, por ejemplo codex exec --sandbox workspace-write "corrige los errores de lint".

Paso 9: retoma y bifurca sesiones

Codex guarda tus conversaciones en local, así que cerrar la terminal no te hace perder trabajo:

• codex resume abre un selector con las sesiones anteriores.
• codex resume --last entra directamente en la última de la carpeta actual; añade --all para buscar en todas las carpetas.
• codex fork (o /fork en una sesión) copia una conversación en otra nueva, para probar otro enfoque sin perder la original.
• En ejecuciones no interactivas, codex exec resume --last continúa la última sesión de exec.

Bifurcar viene muy bien cuando Codex ya ha acumulado buen contexto sobre un problema y quieres probar dos soluciones desde el mismo punto de partida.

Consejos para obtener mejores resultados

• Haz commit antes y después. La propia OpenAI recomienda crear un punto de control en git antes y después de cada tarea. Si un cambio sale mal, git restore es más rápido que discutir con el agente.
• Di cómo verificarlo. “Ejecuta pnpm test y corrige los fallos” da mejores resultados que “haz que funcione”.
• Planifica los cambios grandes. Usa /plan para todo lo que toque más de un par de archivos y lee el plan antes de que Codex empiece a editar.
• Una tarea por conversación. Empieza de cero con /new entre tareas sin relación; el contexto viejo cuesta tokens y confunde al modelo.
• Compacta las sesiones largas. /compact conserva lo importante y descarta el resto.
• Usa un worktree para el trabajo en paralelo. Dos agentes en la misma carpeta se pisan. Los git worktrees dan a cada uno su propia copia.

Cuando una terminal no basta

Cuando Codex forme parte de tu día a día, querrás más de una sesión en marcha: una arreglando un bug, otra escribiendo tests, quizá una segunda cuenta cuando la primera llegue a su límite. Ahí es donde una sola terminal se vuelve incómoda.

AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Codex (y otros agentes CLI) en terminales reales, una al lado de otra. Usa el login de Codex que ya tienes. Consulta la página de Codex en AgentVera para más detalles.

• Workspace: una cuadrícula de agentes por proyecto, de 1×1 a 5×4. Elige el modelo y el esfuerzo por agente; la lista se lee en vivo de Codex. Los agentes vuelven a su conversación tras reiniciar.
• Permisos por agente: en el diálogo “New agent”, elige Ask, Auto o Full access en lugar de recordar flags.
• Worktrees: en el panel Git, crea un worktree e inicia un agente en él con un clic.
• Cambio de cuenta: cada cuenta de Codex tiene su propia carpeta de inicio, los límites restantes aparecen en la barra de estado y, en Pro y Team, una cadena de cuentas pasa a la siguiente cuando se agota el límite de 5 horas o el semanal.
• Gestor de MCP: configura los servidores MCP una vez; se conectan a Codex en cada arranque.
• Revisión de código: haz que otro agente revise lo que cambió Codex antes de fusionar.

La cuadrícula, los worktrees, la revisión de código y el gestor de MCP están en el plan gratuito. Descarga AgentVera y pruébalo en tu propio repositorio.

Conclusión

Instala Codex, ejecuta codex, inicia sesión con ChatGPT y empieza con una tarea pequeña y real. Déjalo en modo Auto y cambia a solo lectura con /permissions cuando solo quieras respuestas. Pon las reglas del proyecto en AGENTS.md y tus valores por defecto en config.toml, y añade servidores MCP solo cuando los necesites. Haz commit antes y después de cada tarea y usa codex resume para seguir donde lo dejaste. Si también quieres probar el agente de Google, lee cómo usar Gemini CLI.