# Cómo usar Codex CLI: guía paso a paso URL: https://agentvera.dev/es/blog/how-to-use-codex-cli/ · Publicado: 2026-10-25 Cómo usar Codex CLI: instálalo, inicia sesión con ChatGPT, elige sandbox y modo de aprobación, escribe AGENTS.md, configura config.toml y MCP y retoma sesiones. **En resumen:** - Instala Codex CLI con el script oficial, npm o Homebrew, ejecuta codex en la carpeta de un proyecto e inicia sesión con tu cuenta de ChatGPT o una API key. - En el modo Auto, el predeterminado, Codex edita y ejecuta comandos dentro del proyecto y pregunta antes de salir de él o usar la red; /permissions cambia a solo lectura. - Las reglas del proyecto van en AGENTS.md, los ajustes en ~/.codex/config.toml, los servidores MCP se añaden con codex mcp add y codex resume retoma una sesión anterior. 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](/es/blog/claude-code-vs-codex/ "Claude Code vs Codex") y [Codex vs Gemini CLI](/es/blog/codex-vs-gemini-cli/ "Codex vs Gemini CLI") los comparan en detalle. En resumen, Codex es un [agente de programación](/es/glossary/coding-agent/ "Qué 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. | Plataforma | Comando | | --- | --- | | macOS, Linux | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | | Windows PowerShell | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` | | Cualquier plataforma con Node.js | `npm install -g @openai/codex` | | macOS (Homebrew) | `brew install --cask codex` | 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: ```bash codex --version ``` ## Paso 2: inicia sesión Entra en un proyecto y arranca Codex: ```bash 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](https://learn.chatgpt.com/docs/pricing "Precios de Codex") 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: ```text 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. | Modo | Flags | Qué puede hacer Codex | | --- | --- | --- | | Auto (predeterminado) | `--sandbox workspace-write --ask-for-approval on-request` | Leer, editar y ejecutar comandos dentro del proyecto; pregunta antes de salir de él o usar la red | | Solo lectura | `--sandbox read-only --ask-for-approval on-request` | Leer y responder; pregunta antes de cualquier edición o comando que cambie el estado | | No interactivo, solo lectura | `--sandbox read-only --ask-for-approval never` | Nunca pregunta; útil para comprobaciones de CI que no deben cambiar nada | | Acceso total | `--sandbox danger-full-access` | Sin sandbox; solo en una máquina que no te importe perder | 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](/es/blog/ai-coding-agent-security/ "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: ```markdown # 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](/es/blog/claude-md-agents-md/ "CLAUDE.md y 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: ```toml 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](/es/glossary/mcp/ "Qué es 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: ```bash 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 --url https://...`, y si usa OAuth, inicia sesión con `codex mcp login `. `codex mcp list` muestra lo que tienes configurado. Los mismos servidores se pueden escribir a mano en `config.toml`: ```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/blog/what-is-mcp-server/ "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](/es/glossary/context-window/ "Qué es la ventana de contexto"). ## Paso 8: los comandos que conviene conocer Los comandos slash funcionan dentro de una sesión: | Comando | Qué hace | | --- | --- | | `/init` | Genera un `AGENTS.md` para el proyecto | | `/model` | Elige el modelo y el esfuerzo de razonamiento | | `/permissions` | Alterna entre Auto y Read Only | | `/plan` | Primero planifica, luego implementa | | `/status`, `/usage` | Detalles de la sesión y límites restantes | | `/compact` | Resume la conversación para liberar contexto | | `/diff` | Muestra el diff actual de git | | `/review` | Pide a Codex que revise tu árbol de trabajo | | `/mcp` | Lista los servidores MCP y sus herramientas | | `/new`, `/clear` | Empieza una conversación nueva | | `/resume`, `/fork` | Continúa una sesión anterior o crea una rama | | `/copy` | Copia la última respuesta | Y algunos subcomandos desde la shell: | Comando | Qué hace | | --- | --- | | `codex exec "..."` | Ejecuta una tarea sin la interfaz interactiva, para scripts y CI | | `codex review --uncommitted` | Revisa los cambios sin commit (también `--base ` o `--commit `) | | `codex resume` | Elige una sesión reciente para continuar | | `codex fork --last` | Crea una rama de la sesión más reciente | | `codex -C ruta/a/carpeta` | Arranca en otra carpeta | | `codex doctor` | Comprueba tu instalación | 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](/es/blog/git-worktree-parallel-agents/ "Git worktrees para agentes en paralelo") 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](/es/agents/codex/ "Codex en AgentVera") para más detalles. - **[Workspace](/es/features/workspace/ "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](/es/features/git-and-github/ "Git y GitHub"), crea un worktree e inicia un agente en él con un clic. - **[Cambio de cuenta](/es/features/account-switching/ "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](/es/features/mcp-manager/ "Gestor de MCP"):** configura los servidores MCP una vez; se conectan a Codex en cada arranque. - **[Revisión de código](/es/features/code-review/ "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](/es/download/ "Descargar 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](/es/blog/how-to-use-gemini-cli/ "Cómo usar Gemini CLI"). ## Preguntas frecuentes **¿Codex CLI es gratis?** Instalar la CLI no cuesta nada. Para usarla inicias sesión con una cuenta de ChatGPT o con una API key de OpenAI. En el momento de escribir esto (octubre de 2026), Codex está incluido en ChatGPT Free, Go, Plus, Pro, Business, Edu y Enterprise, con límites de uso que crecen con el plan. Las API keys se facturan por token. **¿Codex CLI funciona en Windows?** Sí. Instálalo desde PowerShell con el script oficial o con npm. En Windows, Codex usa su propio sandbox, y dentro de WSL2 usa el sandbox de Linux. Los modos de aprobación, AGENTS.md y config.toml funcionan igual en todas las plataformas. **¿Cómo evito que Codex modifique archivos?** Ejecuta /permissions y elige Read Only, o arranca Codex con --sandbox read-only. Así Codex puede leer archivos y responder preguntas, pero pregunta antes de editar nada o de ejecutar comandos que cambien el estado. **¿Dónde guarda Codex CLI sus ajustes?** Los ajustes de usuario están en ~/.codex/config.toml. Un proyecto puede añadir su propio .codex/config.toml, que Codex solo carga en proyectos de confianza. Los flags de la línea de comandos y -c clave=valor sobrescriben ambos para una sola ejecución. **¿Cómo continúo una sesión anterior de Codex?** Ejecuta codex resume para elegir entre las sesiones recientes, o codex resume --last para entrar directamente en la última de la carpeta actual. Dentro de una sesión, /resume hace lo mismo y /fork abre una rama nueva a partir de la conversación actual. --- **Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/