Lección 06: Codex CLI — El Agente de OpenAI en Terminal
- Codex CLI es el agente de código de OpenAI que opera directamente en la terminal, sin necesidad de IDE.
- Proyecto open source en GitHub, con sandbox de seguridad que aísla la ejecución de código.
- Tres modos de operación: suggest, auto-approve y full-auto, con control granular sobre la autonomía.
- Funciona con modelos de OpenAI como codex-mini y GPT-4o, requiere API key con crédito activo.
Qué es Codex CLI
Codex CLI es el agente de desarrollo de OpenAI para la terminal. Lanzado en 2025 como proyecto open source, representa una apuesta directa por un paradigma diferente: en lugar de integrar IA dentro de un editor, lleva el editor a la terminal. Le das una instrucción en lenguaje natural y el agente lee tu código, propone cambios y puede ejecutarlos de forma autónoma.
# Codex CLI en acción: corregir un bug $ codex "find and fix the authentication bug in auth.js" Analyzing auth.js... Found issue: token expiration check uses wrong comparison operator Proposed fix: - if (token.exp > Date.now()) + if (token.exp < Date.now()) Apply changes? [y/n]
A diferencia de herramientas como GitHub Copilot o Cursor, que trabajan dentro de un editor visual, Codex CLI no tiene interfaz gráfica. Es una herramienta de línea de comandos pura. Esto lo hace especialmente útil para desarrolladores que ya viven en la terminal y prefieren flujos de trabajo basados en texto.
Instalación y Configuración
La instalación es directa a través de npm. Necesitas Node.js 22 o superior y una API key de OpenAI con crédito disponible. El proceso completo toma menos de dos minutos.
# Instalar Codex CLI globalmente $ npm install -g @openai/codex # Configurar la API key $ export OPENAI_API_KEY="sk-..." # Verificar instalación $ codex --version codex 1.0.7 # Primera ejecución $ codex "explain this project structure"
La API key se puede configurar de forma permanente en tu archivo .bashrc o .zshrc. Cada llamada a Codex CLI consume tokens de la API de OpenAI, por lo que el coste depende del uso. El modelo por defecto es codex-mini, optimizado para tareas de código con buena relación velocidad-coste.
Modos de Ejecución
La característica más distintiva de Codex CLI son sus tres niveles de autonomía. Cada modo define cuánto control tiene el agente sobre tu código y tu sistema. Esta granularidad es clave para mantener la seguridad sin sacrificar productividad.
Suggest
El agente propone cambios pero no ejecuta nada. Tú revisas y apruebas cada acción manualmente.
Ideal para: Código de producción, revisiones críticas
Auto-approve
Aprueba automáticamente lecturas y ediciones de archivos. Pide confirmación para comandos de terminal.
Ideal para: Refactoring, generación de tests
Full-auto
Ejecución totalmente autónoma dentro del sandbox aislado. Sin confirmaciones intermedias.
Ideal para: Tareas repetitivas, prototipos rápidos
# Modo suggest: revisión manual completa $ codex --suggest "add input validation to the signup form" # Modo auto-approve: ediciones automáticas $ codex --auto-approve "refactor utils.js to use ES modules" # Modo full-auto: ejecución autónoma total $ codex --full-auto "write unit tests for all functions in api/"
El modo suggest es el predeterminado y el más recomendable para empezar. A medida que ganes confianza con la herramienta y entiendas sus límites, puedes escalar hacia auto-approve para tareas de bajo riesgo como generación de tests o documentación.
Arquitectura de Seguridad: El Sandbox
Lo que diferencia a Codex CLI de otros agentes es su modelo de seguridad por defecto. Toda ejecución de código ocurre dentro de un sandbox aislado que limita el acceso al sistema. No es una promesa, es una restricción técnica real.
El sandbox opera con tres restricciones fundamentales: sistema de archivos restringido al directorio del proyecto, red completamente deshabilitada para evitar exfiltración de datos, y procesos confinados que no pueden escalar privilegios. En macOS usa mecanismos nativos de sandboxing; en Linux utiliza contenedores.
Codex CLI vs Claude Code
Codex CLI y Claude Code son los dos principales agentes de código en terminal de 2025-2026. Aunque comparten el paradigma de trabajar desde la línea de comandos, sus filosofías y capacidades difieren de forma significativa.
| Característica | Codex CLI | Claude Code |
|---|---|---|
| Desarrollador | OpenAI (open source) | Anthropic (código cerrado) |
| Modelo base | codex-mini / GPT-4o | Claude Opus / Sonnet |
| Contexto máximo | ~192K tokens | ~1M tokens |
| Sandbox nativo | Sí, por defecto | Permisos manuales |
| Modos autonomía | 3 niveles (suggest/auto/full) | 2 niveles (ask/auto-accept) |
| Coste | API de OpenAI (pago por uso) | Suscripción o API Anthropic |
| Open source | Sí (Apache 2.0) | No |
| Edición multi-archivo | Sí | Sí |
| Ejecución de comandos | Dentro del sandbox | Con permisos del usuario |
Si la seguridad por defecto y la transparencia del código abierto son tu prioridad, Codex CLI tiene ventaja. Si necesitas trabajar con proyectos muy grandes que requieren un contexto extenso, la ventana de 1M de tokens de Claude Code marca una diferencia notable en la calidad de las respuestas.
Casos de Uso Principales
Codex CLI brilla en escenarios donde necesitas automatizar tareas repetitivas de código sin salir de la terminal. Estos son los cuatro casos donde el agente aporta más valor.
Corrección de bugs
Describe el error en lenguaje natural y Codex localiza el archivo, identifica la causa y propone la solución exacta.
Refactoring
Migra funciones, renombra variables o reestructura módulos completos en múltiples archivos con un solo comando.
Generación de tests
En modo full-auto, genera suites completas de unit tests para funciones existentes, incluyendo edge cases.
Generación de código
Crea funciones, endpoints, componentes o scripts completos a partir de descripciones en lenguaje natural.
# Refactoring multi-archivo $ codex "migrate all CommonJS requires to ES module imports in src/" # Generación de tests con cobertura $ codex --full-auto "write Jest tests for api/users.js covering all edge cases" # Documentación automática $ codex "add JSDoc comments to all exported functions in lib/" # Análisis de código $ codex "find potential security vulnerabilities in this project"
El patrón común es claro: cuanto más específica y acotada sea la instrucción, mejores resultados obtendrás. Las tareas amplias como "mejora todo el proyecto" producen resultados inconsistentes. Las tareas concretas como "añade validación al endpoint POST /users" funcionan de forma predecible.
Para quién es Codex CLI
Codex CLI encaja mejor con desarrolladores que ya trabajan en terminal, prefieren herramientas open source y quieren un control explícito sobre la autonomía del agente. Si vienes de un entorno donde usas vim, tmux y git desde la línea de comandos, Codex CLI se integra de forma natural en tu flujo de trabajo sin añadir interfaces que no necesitas.
Preguntas Frecuentes
Dudas habituales sobre Codex CLI
OPENAI_API_KEY antes de usar la herramienta. Sin crédito activo en la cuenta, los comandos no se ejecutarán.