Codex CLI: guía práctica del agente de OpenAI en la terminal

Codex CLI es el agente de programación de OpenAI que vive en tu terminal: entras a un repositorio, corres codex y describes la tarea. El agente inspecciona archivos, edita código, ejecuta comandos locales y automatiza trabajo repetible sin salir del prompt. No es un chat pegado al IDE: es un loop de terminal con sandbox, política de aprobaciones y un modo headless (codex exec) pensado para scripts y CI.

Esta guía cubre el flujo del hub Construir agentes: instalación, autenticación, primer tarea, sandbox/approvals, AGENTS.md y automatización. Si estás eligiendo entre superficies, contrástalo con Claude Code vs Codex. Para las reglas del repo usa AGENTS.md; para el modelo de permisos, sandboxing de agentes de código. El curso arranca en /curso/instalar-agente.

Instalación: script, Homebrew o npm

La documentación oficial da tres vías. El instalador standalone es el camino más corto en macOS y Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

El mismo comando actualiza. En Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Homebrew instala el cask:

brew install --cask codex
brew upgrade --cask codex

También existe npm install -g @openai/codex. En este sitio el estándar de repos Node es pnpm; si instalas el CLI global, no mezcles ese npm -g con el lockfile del proyecto. El binario que importa es codex en el PATH, no una copia local dentro de node_modules.

Tras instalar, abre el directorio del proyecto (idealmente la raíz git) y lanza:

codex

Autenticación: ChatGPT o API key

Codex admite dos caminos, documentados en Authentication:

1. Sign in with ChatGPT — consumo contra tu suscripción. En CLI corre codex login y completa el flujo del navegador. Es el default cuando no hay sesión válida.
2. API key — facturación de Platform a tarifas de API. Nunca pegues la key en el prompt ni en el historial del shell; pásala por stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

El método de login no es cosmética: con ChatGPT aplican permisos, RBAC y retención del workspace de ChatGPT; con API key aplican las políticas de la organización de Platform. Codex Cloud exige ChatGPT; CLI e IDE aceptan ambos.

Si el login se queda a medias en un entorno sin navegador, usa el flujo device/auth que imprima URL y código, completa desde el celular y verifica con el comando de status de la sesión. No copies tokens al chat.

Primer tarea y checkpoints git

Con la sesión abierta, pide algo acotado. El ejemplo oficial es suficiente:

Tell me about this project

Luego un cambio pequeño: un test que falla, un rename, un bug con stack trace. Antes y después de una tarea no trivial, crea un checkpoint git (commit o stash con mensaje) para poder revertir. Codex edita el working tree; tú decides cuándo entra al índice. No le pidas git add . ni --force.

Comandos útiles del día a día, según la CLI reference:

Acción	Cómo
Reabrir un chat	codex resume en el mismo repo
Imagen en el prompt	codex --image captura.png
Búsqueda web	codex --search cuando el dato es de releases actuales
MCP	codex mcp para listar/añadir servidores
Permisos de la sesión	/permissions
Review sin tocar el árbol	code review de uncommitted / commit / base branch

Sandbox y approvals: dos capas, no una

Por defecto el agente corre sin red y con escritura limitada al workspace. Hay dos controles que no se sustituyen, descritos en approvals & security y sandbox:

• Sandbox: qué puede hacer el proceso (dónde escribe, si hay red). En macOS usa Seatbelt; en Linux/WSL2 hace falta bubblewrap (sudo apt install bubblewrap o sudo dnf install bubblewrap); en Windows nativo, Windows Sandbox; en WSL2, el sandbox Linux.
• Approval policy: cuándo debe preguntarte antes de salir del sandbox, usar red o lanzar un comando fuera del set de confianza.

El preset Auto equivale a --sandbox workspace-write --ask-for-approval on-request: lee, edita y corre comandos en el directorio de trabajo; pide permiso para salir del workspace o para red. Si solo quieres planear, pasa a read-only con /permissions.

Red en workspace-write sigue apagada salvo que la enciendas:

[sandbox_workspace_write]
network_access = true

Encender red no es lo mismo que un proxy de destinos. features.network_proxy solo filtra tráfico después de que la red está on; con red off el proxy no hace nada. danger-full-access es para un runner aislado, no para tu laptop.

Las tools MCP con anotación destructiva piden aprobación aunque no sean un shell. El monitoreo de seguridad de modelos recientes puede pausar una tarea después del acto que la disparó: no reemplaza sandbox ni review del diff.

AGENTS.md: instrucciones que sí carga

Codex lee AGENTS.md antes de trabajar. El orden de descubrimiento es:

1. Global: ~/.codex/AGENTS.override.md si existe; si no, ~/.codex/AGENTS.md.
2. Proyecto: desde la raíz git hasta el cwd, un archivo por directorio (AGENTS.override.md, luego AGENTS.md).
3. Merge de raíz hacia abajo; lo más cercano al cwd gana porque va al final. Tope por defecto: 32 KiB (project_doc_max_bytes).

Pon en el repo lo operativo: pnpm only, PRs, nunca push a main, tests que debe correr. Lo global (~/.codex/AGENTS.md) son preferencias tuyas. Un override temporal global no borra el archivo base: se llama AGENTS.override.md.

codex exec: scripts y CI

Non-interactive mode es codex exec. Progreso a stderr; mensaje final a stdout. Default: sandbox read-only.

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec --sandbox workspace-write "fix the failing unit test without touching unrelated files"

--full-auto está deprecado (imprime warning); en scripts nuevos usa --sandbox workspace-write. --ephemeral no persiste rollouts. --json emite JSONL (thread.started, turn.*, item.*). --output-schema + -o dejan un JSON final validado para el siguiente paso del pipeline.

--ignore-user-config evita cargar $CODEX_HOME/config.toml. --ignore-rules salta execpolicy .rules. Si un MCP marcado required = true no arranca, codex exec sale con error: no continúa “a medias”.

danger-full-access solo en contenedor o runner aislado. En CI, el prompt va en el job; los secretos van en el secret store, nunca en el texto que ve el modelo.

Checklist operativo

1. Instala con el script oficial o el cask; confirma codex en PATH.
2. codex login (ChatGPT) o printenv OPENAI_API_KEY | codex login --with-api-key.
3. Arranca en la raíz git, no en un submódulo ajeno.
4. Deja AGENTS.md en el repo con reglas duras (package manager, git, tests).
5. Trabaja en workspace-write + on-request; red off salvo que la tarea lo pida.
6. Checkpoint git antes de un cambio grande; review del diff antes del commit.
7. Automatización: codex exec --sandbox …, no --full-auto.
8. Nunca danger-full-access en tu máquina de diario.
9. No pases tokens al contexto; stdin o el secret store.
10. Si el sandbox Linux falla, instala bubblewrap antes de “abrir” permisos.

FAQ

¿Codex CLI reemplaza a Claude Code o a Cursor? No. Es la superficie de OpenAI en terminal, con sandbox OS y codex exec. Claude Code es otro CLI con hooks y slash commands; Cursor es IDE. Elige por modelo, políticas de datos y si necesitas headless en CI.

¿Puedo usarlo solo con API key, sin ChatGPT Plus/Pro? Sí, con codex login --with-api-key. Pagos van a Platform. Cloud sigue exigiendo ChatGPT.

¿codex exec escribe archivos por defecto? No. El default es read-only. Para editar: --sandbox workspace-write.

¿Dónde pongo las reglas del equipo? AGENTS.md en la raíz del repo. Overrides por servicio en subdirectorios. No copies un system prompt de 4 000 tokens al chat de cada sesión.

Fuentes

Documentación oficial de Codex CLI, autenticación, codex exec, approvals/security, sandbox y AGENTS.md, verificada el 2026-09-07 (URLs learn.chatgpt.com/docs/...; las rutas antiguas developers.openai.com/codex/... redirigen ahí).