Codex CLI: cómo usar el agente de OpenAI desde la terminal
Codex CLI es el agente de programación de OpenAI para la terminal. Puede leer tu repositorio, modificar archivos, ejecutar comandos, correr tests, revisar código, utilizar Git, conectarse mediante MCP, cargar Skills y Plugins, trabajar con imágenes, buscar información actualizada y funcionar tanto de forma interactiva como dentro de scripts y CI/CD.
¿Qué es Codex CLI?
Codex CLI es una aplicación de terminal
que permite trabajar con el agente de programación
de OpenAI directamente sobre los archivos
de tu computadora.
Ejecutas
codex
dentro de un proyecto
y el agente puede inspeccionar código,
editar archivos,
ejecutar herramientas instaladas,
correr tests,
revisar diffs
y completar tareas
de ingeniería.
También existe
codex exec
para scripts,
pipelines
y automatización sin interfaz interactiva.
Qué puedes hacer con Codex CLI
Programar
Leer, crear y modificar archivos desde terminal.
Ejecutar comandos
Tests, linters, builds, Git y herramientas locales.
Sandbox
Restringir filesystem, red y acciones que requieren aprobación.
Imágenes
Adjuntar screenshots, diseños y diagramas.
Web Search
Consultar información reciente cuando la tarea lo requiere.
Automatización
Ejecutar Codex
desde scripts
mediante
codex exec.
Tu terminal se convierte en un entorno agentic
Describe la tarea
Explica qué quieres conseguir.
Codex explora
Lee archivos, AGENTS.md y estructura del proyecto.
Codex actúa
Edita, ejecuta comandos y utiliza herramientas.
Comprueba
Tests, build, lint y revisión del resultado.
Codex CLI trabaja directamente en tu computadora
Al ejecutar Codex CLI dentro de una carpeta, esa carpeta se convierte en el contexto principal del proyecto. El agente puede utilizar las herramientas instaladas en tu propio entorno de desarrollo.
Leer archivos del repositorio.
Buscar funciones y referencias.
Modificar múltiples archivos.
Ejecutar herramientas locales.
Trabajar con Git.
Comprobar los resultados.
Cómo instalar Codex CLI
OpenAI ofrece instaladores nativos y también distribución mediante npm y Homebrew.
curl -fsSL https://chatgpt.com/codex/install.sh | shpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"npm install -g @openai/codexbrew install --cask codex
En
/como-instalar-codex-cli/
veremos Windows,
macOS,
Linux,
npm,
Homebrew,
binarios,
actualizaciones
y solución de errores.
Ejecuta Codex desde el proyecto
cd mi-proyecto
codexTambién puedes indicar explícitamente el directorio:
codex --cd /ruta/al/proyectoCodex CLI considera el directorio desde el que se inicia como el proyecto del chat.
Iniciar sesión en Codex CLI
Cuenta de ChatGPT
codex loginCompleta el inicio de sesión desde el navegador.
OpenAI API key
printenv OPENAI_API_KEY | codex login --with-api-keyEl consumo se factura mediante OpenAI API.
El método de autenticación determina facturación, políticas de datos y disponibilidad de determinadas funciones cloud.
La interfaz interactiva de Codex CLI
Cuando ejecutas
simplemente
codex,
se abre
la interfaz interactiva
de terminal.
Desde ella
puedes conversar
con el agente,
ver comandos,
revisar cambios,
seleccionar modelos
y controlar permisos.
codexComandos importantes dentro de Codex CLI
| Comando | Función |
|---|---|
/init |
Crear instrucciones AGENTS.md |
/status |
Mostrar configuración actual de la sesión |
/permissions |
Cambiar los permisos activos |
/model |
Elegir modelo y esfuerzo de razonamiento |
/review |
Revisar cambios y buscar problemas |
/new |
Comenzar un chat nuevo |
/resume |
Retomar conversaciones guardadas |
/mcp |
Ver servidores MCP activos |
/plugins |
Abrir el explorador de Plugins |
/theme |
Cambiar el tema de la TUI |
Comprueba cómo está configurada tu sesión
/statusResulta útil para revisar parámetros relevantes de la sesión actual antes de ejecutar una tarea importante.
Cambiar modelo y esfuerzo de razonamiento
/modelPara cambios pequeños puedes priorizar velocidad. Para debugging difícil, arquitectura, migraciones o revisiones complejas, aumentar el esfuerzo puede mejorar el resultado.
codex --model NOMBRE_MODELO/permissions controla cuánta autonomía tiene Codex
/permissions| Sandbox | Uso |
|---|---|
read-only |
Inspección sin escritura normal del workspace |
workspace-write |
Trabajo normal dentro del proyecto |
danger-full-access |
Acceso amplio; úsalo solo en entornos controlados |
Para desarrollo normal,
una combinación
como
workspace-write
con aprobación
on-request
permite trabajar
con autonomía
dentro del proyecto
y pedir autorización
cuando Codex
necesita superar
esos límites.
El aislamiento se aplica a los comandos ejecutados por Codex
Seatbelt
Utiliza mecanismos nativos de sandboxing de macOS.
bwrap + seccomp
Utiliza aislamiento del sistema operativo.
Sandbox Linux
Usa la implementación Linux dentro de WSL2.
Sandbox nativo
Codex también dispone actualmente de aislamiento nativo en Windows.
OpenAI recomienda
disponer de
bubblewrap
para el sandbox Linux.
sudo apt install bubblewrapconfig.toml: el archivo central de Codex CLI
La configuración principal se guarda normalmente en:
~/.codex/config.tomlTambién puedes utilizar configuración específica del proyecto:
.codex/config.tomlCodex no carga todas las capas de configuración de un proyecto que esté marcado como no confiable.
Configuración básica de Codex CLI
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
[sandbox_workspace_write]
network_access = false
Mantener
network_access = false
reduce la superficie
de riesgo
cuando la tarea
solamente necesita
trabajar
con archivos locales.
Cambia una opción solo para una ejecución
codex --config sandbox_workspace_write.network_access=trueTambién puedes seleccionar directamente un modelo:
codex --model NOMBRE_MODELOGuarda configuraciones distintas para cada workflow
Desarrollo diario.
Automatización.
Revisión de seguridad.
Investigación read-only.
codex --profile ci
Los perfiles
pueden vivir
junto a
config.toml
con nombres
como:
~/.codex/ci.config.tomlGuarda instrucciones permanentes del repositorio
/initPuedes usar este comando como punto de partida para crear instrucciones específicas para Codex.
# AGENTS.md
## Stack
PHP 8.2
MySQL
JavaScript
## Reglas
- Usa PDO.
- Usa prepared statements.
- No cambies APIs públicas sin aprobación.
- No añadas dependencias innecesarias.
- Ejecuta tests después de cada cambio.
## Verificación
composer test
vendor/bin/phpcsAGENTS.md puede cambiar según el directorio
mi-proyecto/
├── AGENTS.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.mdEl frontend puede tener reglas diferentes al backend, mientras la raíz mantiene instrucciones comunes.
Activa búsqueda web cuando necesites información reciente
codex --searchActívala cuando Codex necesite comprobar versiones, documentación reciente, cambios de APIs o comportamiento externo actual.
Adjunta screenshots e imágenes a Codex CLI
codex -i screenshot.png "Explica este error y encuentra la corrección mínima"Para comparar varias imágenes:
codex --image before.png,after.png "Compara ambos estados y enumera las regresiones"Puedes entregar una captura del diseño esperado y pedir que Codex compare el resultado después de implementar.
Retoma un trabajo anterior con codex resume
codex resumeCodex puede mostrar conversaciones guardadas asociadas a tus proyectos para continuar una tarea anterior.
También puedes
utilizar
/resume.
Usa un chat nuevo para objetivos distintos
/newMantén autenticación, migraciones, debugging y otras tareas importantes en chats separados cuando no compartan el mismo objetivo.
/review analiza tus cambios sin modificar el working tree
/reviewComparar con una rama base.
Revisar cambios sin commit.
Revisar un commit concreto.
Usar instrucciones personalizadas.
Una revisión separada ayuda a detectar bugs, regresiones y riesgos antes de integrar los cambios.
Conecta Codex CLI con herramientas externas
codex mcp add context7 -- npx -y @upstash/context7-mcpcodex mcp listDentro de la TUI:
/mcpCodex CLI, la app de escritorio y la extensión IDE pueden utilizar los servidores MCP configurados para el mismo host.
Explora Plugins directamente desde Codex CLI
/pluginsBuscar Plugins.
Instalarlos.
Activarlos o desactivarlos.
Explorar distintos marketplaces.
inicia una sesión nueva para que sus Skills y herramientas estén disponibles.
Invoca workflows reutilizables desde Codex
Codex utiliza
Agent Skills
para encapsular
procesos,
instrucciones
y recursos
especializados.
También puedes
invocarlas
explícitamente
mediante
$nombre-skill.
$security-review revisa los cambios actualesAbre tu editor favorito con Ctrl+G
Para instrucciones
largas,
Codex puede abrir
el editor definido
mediante
VISUAL
o
EDITOR.
Guardas el texto
y vuelves
automáticamente
al editor de prompts.
En vez de escribir una feature compleja en una sola línea, puedes editar cómodamente una especificación extensa.
Autocompletado para tu shell
codex completion zshTambién existen opciones para otros shells, incluido PowerShell.
Cambiar el tema visual de Codex CLI
/theme
La selección
puede guardarse
en
tui.theme
dentro de
config.toml.
codex exec: Codex sin la interfaz interactiva
codex exec
permite ejecutar
una tarea
desde scripts,
cron,
CI/CD
o pipelines
sin abrir la TUI.
codex exec "Analiza la estructura del repositorio y enumera las cinco áreas con mayor riesgo"codex exec comienza de forma conservadora
codex exec
utiliza
un sandbox
read-only.
Para permitir modificaciones del workspace:
codex exec --sandbox workspace-write "Corrige los tests que están fallando"OpenAI mantiene esa opción por compatibilidad, pero la documentación actual recomienda declarar explícitamente el sandbox necesario.
Combina Codex con pipes
npm test 2>&1 \
| codex exec "Resume los tests fallidos y propone la corrección mínima"Para analizar logs:
tail -n 200 app.log \
| codex exec "Encuentra la causa raíz y los tres siguientes pasos de debugging"También puedes entregar el prompt completo mediante stdin
cat prompt.txt | codex exec -Un script puede construir dinámicamente la instrucción completa y enviarla directamente a Codex.
Obtén eventos estructurados para scripts
codex exec --json "Resume la estructura del repositorio" | jqPuedes capturar eventos como inicio del thread, comandos, cambios de archivos, mensajes, MCP, búsquedas web y finalización del turno.
Fuerza una estructura estable con JSON Schema
codex exec "Extrae metadatos del proyecto" \
--output-schema ./schema.json \
-o ./resultado.jsonTu siguiente paso automatizado puede esperar campos concretos en vez de interpretar texto libre.
Ejecuta una tarea sin guardar la sesión
codex exec --ephemeral "Analiza el repositorio y sugiere siguientes pasos"Es útil para jobs que no necesitan conservar historial local.
Continúa una ejecución anterior
codex exec "Revisa el cambio buscando race conditions"
codex exec resume --last "Corrige los problemas que encontraste"También puedes reanudar un ID de sesión específico.
codex exec espera trabajar dentro de un repositorio Git
Codex exige normalmente que el trabajo automatizado se ejecute dentro de un repositorio Git.
Existe una opción para saltarse esa comprobación:
codex exec --skip-git-repo-check "Analiza estos archivos"Git aporta una capa muy útil para revisar y revertir cambios realizados por agentes.
Codex también dispone de modo OSS
codex --ossLa configuración avanzada permite trabajar con proveedores locales compatibles, como Ollama o LM Studio, según la configuración de tu entorno.
No entregues todos tus secretos a cada comando
Codex permite controlar qué variables de entorno reciben los comandos que ejecuta.
[shell_environment_policy]
inherit = "core"
[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"Tests, package scripts y dependencias también pueden leer variables disponibles en el proceso.
Evita exponer API keys a código no confiable
No conviene dejar una API key disponible como variable global del job cuando el workflow ejecuta código controlado por el repositorio.
Para GitHub, OpenAI proporciona una Codex Action específica que reduce la exposición directa de credenciales.
Debugging de un bug con Codex CLI
Tenemos un error en el login.
Síntoma:
el usuario inicia sesión correctamente,
pero vuelve a la pantalla de login.
Antes de modificar código:
1. reproduce el error
2. encuentra el flujo completo de autenticación
3. identifica dónde se crea la sesión
4. revisa redirects
5. encuentra la causa raíz
Después:
6. escribe un test que reproduzca el bug
7. aplica la corrección mínima
8. ejecuta los tests
9. revisa git diff
No ocultes el error.
Corrige la causa raíz.Revisión antes de commit
Revisa git diff.
Busca:
- bugs
- regresiones
- problemas de seguridad
- cambios accidentales
- debugging temporal
- secretos
- tests faltantes
Ejecuta los tests relevantes.
No modifiques código
hasta terminar el informe.Codex CLI también encaja muy bien con WordPress
Analiza este plugin WordPress.
Identifica:
- archivo principal
- actions
- filters
- shortcodes
- AJAX handlers
- REST routes
- cron
- tablas propias
- WooCommerce integrations
- nonces
- capabilities
No modifiques nada todavía.
Crea primero
un mapa de arquitectura.
desarrollaremos
/codex-para-wordpress/
con WP-CLI,
WooCommerce,
AJAX,
REST,
PHP
y MySQL.
Logs y diagnóstico de Codex CLI
Para depuración avanzada
puedes utilizar
variables como
RUST_LOG
y configurar
un directorio
explícito
de logs.
codex -c log_dir=./.codex-logCodex CLI se desarrolla públicamente
El repositorio
oficial
openai/codex
está disponible
públicamente
y utiliza
licencia Apache 2.0.
El cliente y determinados componentes pueden ser abiertos, mientras los modelos OpenAI siguen siendo servicios separados.
Codex CLI, IDE, Desktop o Cloud
Buenas prácticas para trabajar con Codex CLI
Ejecuta Codex desde la raíz correcta del proyecto.
Configura AGENTS.md con reglas persistentes.
Mantén Git limpio antes de cambios grandes.
Usa el mínimo nivel de permisos necesario.
Activa Internet solo cuando la tarea lo necesite.
Define cómo debe verificarse cada cambio.
Utiliza /review antes de cambios importantes.
Usa codex exec para procesos repetibles.
Documentación recomendada
Codex CLI
Instalación, TUI, review, búsqueda, imágenes y sesiones.
Ver Codex CLI →Sandbox
Permisos, filesystem, red y seguridad.
Ver Sandbox →Non-interactive
codex exec, JSON, CI y pipelines.
Ver codex exec →openai/codex
Código fuente e instaladores oficiales.
Ver GitHub →Guías relacionadas
FAQ sobre Codex CLI
Codex CLI es el cliente de terminal del agente de programación de OpenAI. Puede leer y modificar proyectos locales, ejecutar comandos, utilizar Git, correr tests y trabajar con herramientas externas.
OpenAI ofrece instaladores para macOS, Linux y Windows. También puedes instalarlo mediante npm con npm install -g @openai/codex o mediante Homebrew en macOS.
Sí. Codex puede ejecutarse actualmente de forma nativa en Windows y también dentro de WSL2. El método de sandbox depende del entorno utilizado.
No necesariamente. Puedes iniciar sesión con tu cuenta de ChatGPT. También puedes autenticar Codex CLI mediante una API key de OpenAI para workflows locales.
AGENTS.md permite almacenar instrucciones persistentes para Codex, como arquitectura, convenciones, comandos de test, restricciones y reglas específicas del proyecto.
Abre el selector de permisos y permite controlar el nivel de acceso que Codex tiene al sistema, al workspace y a determinadas operaciones.
Ejecuta una revisión especializada de cambios. Puedes revisar cambios sin commit, un commit concreto o comparar contra una rama base sin modificar el working tree.
Sí. Puedes utilizar –image o -i para adjuntar capturas de pantalla, diagramas y otras referencias visuales al prompt.
Sí. Puedes iniciar una ejecución con –search cuando necesites que Codex consulte información web actualizada.
codex exec ejecuta Codex en modo no interactivo. Está pensado para scripts, pipelines, CI/CD y automatizaciones donde no quieres abrir la interfaz interactiva de terminal.
Sí. La opción –json devuelve una secuencia JSONL con eventos de la ejecución. También puedes utilizar –output-schema para obtener una respuesta final compatible con un JSON Schema.
Sí. Puedes configurar servidores MCP desde la CLI o config.toml, y utilizar /plugins para explorar e instalar Plugins compatibles.
Sí. OpenAI desarrolla Codex CLI públicamente en GitHub bajo licencia Apache 2.0.
Cómo usar Codex desde cero
Ya conoces las principales herramientas de Codex CLI. Ahora veremos cómo utilizarlas dentro de un workflow real: dar contexto, investigar, planificar, programar, depurar, verificar y revisar el resultado.
Aprender a usar Codex →