El CLI oficial de OpenAI para agentes de codificación. Instalación, autenticación, modos de autonomía y cómo se compara con Claude Code — todo en 30 minutos.

OpenAI distribuye su propio CLI de agente de codificación. Codex CLI es el equivalente de OpenAI al Claude Code de Anthropic: construido sobre GPT-5 (o la línea o1/o3), ofrece ejecución autónoma de shell, edición de múltiples archivos y un flujo de planificación y ejecución.

Esta guía configura Codex CLI y — asumiendo que ya usas Claude Code o Cursor — explica qué tareas le corresponden a Codex. ¿Empezando desde cero? Lee esto junto a la configuración de Claude Code.

TL;DR

Node.js 20+ → npm install -g @openai/codex → codex → autenticación en el navegador
Usar una clave API de OpenAI o suscripción a ChatGPT Plus/Pro
El modo predeterminado es el modo de aprobación (confirmar cada comando); --auto-edit / --full-auto aumentan la autonomía
Elegir un modelo: --model gpt-5 o o3 (equilibrio rendimiento vs. coste)
División de roles con Claude Code: ver §5

Requisitos previos

Node.js 20+ (mac/dev-toolchain o windows/initial-setup)
Cuenta de OpenAI — platform.openai.com o ChatGPT Plus/Pro
Un proyecto gestionado con git

1. Dónde encaja Codex CLI en el flujo de trabajo

Es el CLI de agente de codificación de primera parte de OpenAI. A diferencia de herramientas de terceros (Cursor, Aider, Continue) que llaman a modelos de OpenAI, Codex CLI es la solución oficial de OpenAI.

Similitudes con Claude Code

Se ejecuta de forma autónoma en el terminal
Edición de múltiples archivos · comandos de shell · integración con git
Contexto del proyecto (Codex lo almacena en un directorio .codex/)
Flujo de trabajo planificar → ejecutar → verificar

Diferencias

Aspecto	Codex CLI	Claude Code
Modelo	GPT-5 · o3 · o4	Claude Opus / Sonnet / Haiku
Ventana de contexto	200K (varía según el modelo)	1M (Opus/Sonnet 4)
Flags de autonomía	`--auto-edit`, `--full-auto`	modo de permiso + hooks
Autenticación	Clave API o suscripción a ChatGPT	Clave API o suscripción Pro/Max
Precio	Basado en tokens o Plus($20)/Pro($200)	Basado en tokens o Pro($20)/Max($100/$200)
Soporte MCP	Parcial (en progreso)	Completo
Integración con IDE	Extensión IDE separada	VS Code · JetBrains · CLI

Para quién es

Usuarios de ChatGPT Plus/Pro: Codex CLI está incluido
Usuarios del ecosistema de OpenAI: comparten claves con Embeddings, DALL·E, etc.
Quienes necesitan la ventaja de razonamiento de o3/o4 para tareas de pensamiento largo
Quienes necesitan multimodal de GPT-5: imágenes y diagramas como entrada

2. Instalar Codex CLI

2.1 Instalación global con npm

npm install -g @openai/codex
codex --version

Si la instalación falla o hay errores de permisos, ver la configuración de Claude Code §1.1 para la solución de prefijo npm.

2.2 Primera ejecución

cd ~/projects/my-repo
codex

Se abre una pestaña del navegador para el inicio de sesión de OpenAI → conceder acceso → volver al CLI. El token se almacena en el keychain del SO.

2.3 Opciones de autenticación

Tres caminos:

# A. ChatGPT Plus/Pro (suscripción)
codex auth login --use-chatgpt
 
# B. Clave API de OpenAI
codex auth login --use-api
# → lee OPENAI_API_KEY o pregunta
 
# C. Cuenta dedicada en Codex.com (beta)
codex auth login --use-codex

Verificar:

codex auth status
# Account: <email>
# Plan: ChatGPT Plus / API tier 2

3. Modos de autonomía

El modo predeterminado es conservador: confirma cada comando de shell y edición. Niveles disponibles:

Flag	Comportamiento	Riesgo
(predeterminado)	Preguntar antes de cada comando y edición	Bajo
`--auto-edit`	Las ediciones son automáticas, el shell sigue preguntando	Medio
`--full-auto`	Todo automático (peligroso)	Alto

Recomendación: permanecer en el modo predeterminado hasta ganar confianza en la herramienta y, después, cambiar a --auto-edit en repositorios conocidos.

codex --auto-edit
> Refactorizar el módulo de autenticación en archivos más pequeños

4. Comandos principales

4.1 Iniciar sesión

codex
> Plan: añadir una función de restablecimiento de contraseña

Prompt en lenguaje natural → Codex propone un plan → aprobación → ejecución.

4.2 Slash commands

Dentro de una sesión:

/help — lista de comandos
/init — analizar el proyecto y crear AGENTS.md
/model gpt-5 — cambiar de modelo
/clear — restablecer el contexto
/exit — salir

4.3 `AGENTS.md` — guía del proyecto para Codex

El equivalente de CLAUDE.md en Codex. En la raíz del proyecto:

# AGENTS.md
 
## Stack
- Next.js 16 + TypeScript strict
- Supabase + Postgres
- pnpm 11
 
## Comandos
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
 
## Convenciones
- Sin tipos `any`
- Rutas: kebab-case
- Commits: `[Proyecto] tipo: descripción`
 
## Principios de trabajo
- Planificar antes de 5+ cambios de archivos
- Tests + lint + build deben pasar antes de "completado"
- Nunca hacer commit de secretos

Se carga automáticamente al inicio de la sesión. Funcionalmente casi idéntico a CLAUDE.md.

Al usar ambos junto con Claude Code: duplica el contenido entre CLAUDE.md y AGENTS.md, o mantén solo AGENTS.md y referéncialo desde CLAUDE.md con @AGENTS.md.

5. Claude Code vs. Codex CLI: mapeo de tareas

Tarea	Elegir	Por qué
Trabajo multi-archivo con contexto de 1M	Claude Code	Ventana de 1M de Opus/Sonnet 4
Razonamiento largo (depuración, arquitectura)	Codex CLI (o3)	Ventaja del modelo de razonamiento
Código + imagen (análisis de capturas de pantalla)	Codex CLI (GPT-5 multimodal)	Entrada de imágenes
Verificación autónoma tras cambios	Claude Code	Sistema hooks + verify
Integración con el ecosistema de OpenAI (embeddings, etc.)	Codex CLI	Claves unificadas
Servidores MCP (Linear, Notion, etc.)	Claude Code	MCP completo
Minimizar costes	El que ya tienes en suscripción	Evitar tokens de API

Ambos funcionan en el mismo repositorio sin conflictos (los dos están basados en git).

6. Precios (mayo de 2026)

API (Codex CLI)

Modelo	Entrada	Salida	Coste por 1k
GPT-5	$1.25 / 1M	$10 / 1M	Bajo coste de entrada
o3	$2 / 1M	$8 / 1M	Optimizado para razonamiento
o4-mini	$0.3 / 1M	$1.2 / 1M	Mejor relación calidad-precio

Suscripciones de ChatGPT

Plan	Precio	Uso de Codex CLI
ChatGPT Plus	$20/mes	GPT-5 limitado, algo de o3
ChatGPT Pro	$200/mes	Casi ilimitado

El gasto real varía. Promedio aproximado para un desarrollador fullstack en API: 30–100 $/mes. Los usuarios intensivos salen mejor parados con Pro.

7. Verificar

# 1. Instalado
codex --version
 
# 2. Autenticación
codex auth status
 
# 3. Archivos del proyecto
ls -la AGENTS.md .codex/
 
# 4. Prueba del primer comando
echo "create a hello.py that prints 'hello'" | codex --auto-edit

Los cuatro pasando = configuración completa.

8. Solución de problemas

`codex: command not found`

Verificar el prefijo de npm: el directorio /bin de npm config get prefix debe estar en PATH.
Abrir un terminal nuevo e intentarlo de nuevo.

La autenticación en el navegador no se abre

Entorno sin cabeza (WSL2/SSH): copiar la URL que muestra el CLI en un navegador.
Si sigue fallando, eliminar ~/.codex/auth.json y usar codex auth login --use-api con una clave.

"Insufficient quota"

Se alcanzó el límite de uso de OpenAI: platform.openai.com/usage.
El nivel gratuito es muy restrictivo. El Nivel 1+ (activado tras un prepago de 10 $) es el mínimo práctico.

Codex y Claude Code editan el mismo archivo simultáneamente

Ejecutar uno a la vez, o hacer que el segundo espere.
O añadir un archivo centinela como .codex-lock a .gitignore para coordinarlos.

`--full-auto` actuó de forma demasiado agresiva

Ctrl+C inmediatamente.
git reset --hard HEAD o git stash para recuperar el estado anterior.
Permanecer en --auto-edit a partir de entonces.

El servidor MCP no se conecta

A mayo de 2026, el soporte MCP de Codex CLI es parcial (beta).
Para integración MCP completa, usar Claude Code.

9. Qué sigue

Configuración de Claude Code — /ai-agents/claude-code
Configuración de Cursor — /ai-agents/cursor-setup
Configuración de Copilot — /ai-agents/github-copilot
Flujo de trabajo multi-herramienta — /ai-agents/multi-tool-workflow

Referencias

Registro de cambios

2026-05-16: Primer borrador. Instalación de Codex CLI + tres métodos de autenticación + modos de autonomía + AGENTS.md + tabla comparativa con Claude Code + seis casos de solución de problemas.

Configuración de OpenAI Codex CLI — comparativa con Claude Code y Cursor