Mini-masterclass de OpenAI Codex CLI: arma un juego para el navegador desde tu terminal

La mayoría conoce las herramientas de IA para programar a través de un chat: describes algo, te devuelve un muro de código y entonces tú terminas siendo la máquina de copy-paste que lo pega en los archivos y lo corre. Codex CLI le da la vuelta a eso. Es el agente de programación de OpenAI que corre localmente en tu terminal: lee y edita los archivos del directorio que le señales y ejecuta los comandos él mismo, contigo aprobando cada paso. Al terminar esta guía lo vas a tener instalado, con la sesión iniciada, y vas a haber armado un juego para el navegador jugable a partir de un solo prompt. Sin build tools, sin framework, sin copy-paste.

Vamos a ser claros: algunos detalles de precios y límites cambian rapidísimo, y donde la documentación oficial no es clara prefiero decírtelo antes que inventarme números. El punto de partida oficial es https://developers.openai.com/codex/cli/ (opens in new tab); guárdalo en favoritos.

01 · Qué es de verdad (y qué no es)

Codex CLI lo hace OpenAI y está escrito en Rust para que sea rápido. El modelo mental que importa: no es una ventana de chat que te pasa fragmentos, es un agente con manos. Lo abres dentro de una carpeta y esa carpeta pasa a ser su espacio de trabajo. Puede leer tus archivos para entender el proyecto, proponer cambios, escribir archivos nuevos y correr comandos como instalar una dependencia o levantar un dev server, deteniéndose a pedirte permiso según el modo de seguridad en el que estés.

Los propios ejemplos de OpenAI te dan una idea de para qué sirve: "Cuéntame sobre este proyecto", "Arma un juego clásico de Snake en este repo", "Busca y arregla bugs en mi código con cambios mínimos y de alta confianza", generar notas de release a partir de los commits o convertir datos crudos en una tabla de markdown. Es un compañero de programación que escribe en tu terminal, no una máquina expendedora de código.

Algo que no es: un bot que se conecta a Telegram o WhatsApp. Esa integración no existe en Codex CLI; si la viste mencionada junto a Codex en algún lado, es de otros productos completamente distintos. El mundo de Codex CLI es tu terminal y tu sistema de archivos, nada más.

02 · Requisitos, planes y la verdad sobre los precios

Codex CLI corre en macOS, Linux y Windows. En Windows funciona nativo en PowerShell (con su sandbox), o puedes usar WSL2 para tener un entorno Linux nativo. Si lo instalas con npm necesitas Node.js 18+ (mejor versiones más nuevas como Node 22; toma 18 como el mínimo confirmado). En macOS, Homebrew es una alternativa que se salta Node por completo.

Para usarlo te autenticas de una de dos maneras:

• Un plan de ChatGPT. Según el quickstart de OpenAI, "los planes ChatGPT Plus, Pro, Business, Edu y Enterprise incluyen Codex". Algunas fuentes secundarias mencionan un tier gratuito o "Go" de prueba, pero la página oficial del CLI solo lista esos planes de pago, así que no voy a darte por seguro un tier gratis. Revisa la página vigente de OpenAI antes de contar con uno.
• Una API key de OpenAI. Pagas por los tokens que consumas, ideal si no tienes (o no quieres) una suscripción de ChatGPT.

Sobre el dinero: en abril de 2026 OpenAI cambió el precio de Codex para alinearlo con el uso de tokens de la API en vez del precio por mensaje, para los planes Plus, Pro, Business y los nuevos Enterprise. El consumo cuenta para un "límite de uso agéntico" que se reinicia en una ventana móvil. Los números exactos (cuántas tareas por ventana, según el plan) salen de fuentes secundarias y cambian seguido, así que no los voy a fijar aquí: revisa la página de precios de OpenAI y, ya dentro de una sesión activa, escribe /status para ver lo que te queda.

03 · Instalar y verificar (elige un solo método)

Elige el único método que vaya con tu máquina. No corras varios a la vez.

Instalador standalone para macOS / Linux:

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

Instalador standalone para Windows (PowerShell):

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

npm (multiplataforma, necesita Node 18+):

npm install -g @openai/codex

Homebrew (macOS):

brew install --cask codex

Después verifica, siempre, antes de confiar en cualquier otra cosa:

codex --version

Resultado esperado: te imprime una cadena de versión, algo como codex 0.x.x. Si en cambio ves "command not found", lo más probable es que el directorio de binarios globales de npm no esté en tu PATH, o que tu Node sea más viejo que 18. Arregla el PATH (o actualiza Node) y vuelve a correr el comando de verificación.

04 · Inicia sesión

La autenticación es sencilla a propósito. Solo corre el comando sin argumentos:

codex

En el primer arranque te abre una interfaz de terminal a pantalla completa y te pide iniciar sesión. Elige cuenta de ChatGPT (si estás en Plus/Pro/Business/Edu/Enterprise) o API key. Y ya, ese es todo el flujo.

Para corridas con script o no interactivas puedes pasarle la API key en la misma línea, por ejemplo:

CODEX_API_KEY=tu_key_aqui codex exec --json "resume este repo"

05 · Cómo funciona una sesión (y los modos de seguridad)

Una vez dentro, escribes una tarea en lenguaje natural. Codex primero te explica su plan, luego te pide crear o editar archivos y correr comandos, y tú apruebas o rechazas ahí mismo. Vale la pena conocer algunos controles: con las flechas navegas el historial de tus borradores, Ctrl+R busca en el historial de prompts y al presionar Tab dejas en cola una instrucción de seguimiento mientras todavía está trabajando. Entre los comandos slash dentro de una sesión están /review (revisión de código), /model (cambiar de modelo), /status (uso y límites), /permissions (cambiar el modo de aprobación), además de /theme, /clear y /exit.

El modelo de seguridad es la parte que los principiantes se saltan y después lamentan, así que métetela en la cabeza desde ya. Codex tiene modos de sandbox que controlan qué puede tocar:

• read-only: el default. Puede mirar pero no cambiar nada.
• workspace-write: leer, editar dentro del workspace y correr comandos locales de rutina. Es el modo recomendado, el más cómodo, para trabajo local de verdad.
• danger-full-access: sin límites ni en el sistema de archivos ni en la red. Solo cuando de verdad sepas lo que haces.

Por encima de eso van las políticas de aprobación: untrusted, on-request o never. El preset local más sensato es workspace-write con on-request, que lo deja trabajar pero se detiene a pedirte el visto bueno en cualquier cosa relevante:

codex --sandbox workspace-write --ask-for-approval on-request

El equivalente en el archivo de config es sandbox_mode = "workspace-write" y approval_policy = "on-request". Para corridas no interactivas (donde no hay nadie ahí para aprobar) usarías más bien la política never, ya que "on-failure" quedó deprecada.

El modelo por defecto, según la página de features de OpenAI, es gpt-5.5 para la mayoría de las tareas. Puedes cambiarlo con /model dentro de una sesión o arrancar con --model gpt-5.5. La lista de modelos cambia con el tiempo, así que si algún nombre de esta guía ya no aparece, /model te mostrará qué hay disponible de verdad.

06 · El demo de principio a fin: un juego de Snake

Ahora lo divertido. Vamos de una carpeta vacía a un juego jugable.

1) Abre una terminal: Terminal de macOS, PowerShell de Windows o cualquier shell de Linux.

2) Crea una carpeta de proyecto y entra en ella:

mkdir snake-game
cd snake-game

3) Inicializa git para poder revertir. Codex modifica archivos, y tener un checkpoint de git significa que cualquier cambio queda a un comando de distancia de deshacerse. La documentación de OpenAI recomienda explícitamente crear checkpoints de Git:

git init

4) Lanza Codex (inicia sesión en el primer arranque si todavía no lo has hecho):

codex

5) Pega el prompt. El propio quickstart de OpenAI usa la versión mínima, "Build a classic Snake game in this repo". Funciona, pero aquí te dejo una variante más explícita y amigable para principiantes que deja bien clarito lo que quieres; cópiala tal cual:

Build a classic Snake game as a single self-contained index.html file using
HTML, CSS, and vanilla JavaScript on a canvas. Use arrow keys to move, grow the
snake when it eats food, show the score, and add a game-over screen with restart.
No build tools, no dependencies. I want to just double-click index.html to play.

6) Aprueba los pasos. Codex te muestra su plan y luego te pide crear index.html (y quizá un README pequeño). Aprueba la escritura de los archivos. En modo workspace-write lo hará sin estarte molestando en cada tecla, pero igual te avisará de cualquier cosa relevante.

7) Juégalo. Cuando termine, abre el archivo generado en tu navegador. En macOS:

open index.html

En Linux prueba xdg-open index.html; en Windows, start index.html, o simplemente dale doble clic al archivo. Resultado esperado: un juego de Snake en un canvas, flechas para dirigir, el score en vivo y una pantalla de game-over con reinicio.

¿Prefieres una corrida de una sola vez, sin interfaz? Codex tiene un modo no interactivo que hace todo en un solo comando:

codex exec "Build a classic Snake game as a single self-contained index.html with HTML/CSS/vanilla JS canvas, arrow-key controls, score, and game-over restart"

La forma codex exec (alias corto codex e) es la puerta al scripting: corre una tarea y termina, sin interfaz interactiva. Así es como conectas Codex a tus pipelines; por ejemplo codex exec "genera notas de release de los últimos 10 commits" | tee release-notes.md, o pasándole JSON y volcando el resultado a un archivo. El mismo motor, pero sin interfaz a pantalla completa.

07 · Tropiezos que les pasan factura a los principiantes

Una lista corta que te va a ahorrar un montón de tiempo:

• Paquete equivocado. De nuevo, porque es así de común: instala @openai/codex, nunca codex a secas.
• "command not found" después de instalar. Casi siempre es el PATH (el bin global de npm no está incluido) o un Node más viejo que 18.
• No estar en un repo git. Codex prefiere correr dentro de un repo para que los cambios se puedan revertir. O haces git init primero (hazlo) o le pasas --skip-git-repo-check si de verdad necesitas correr suelto.
• danger-full-access a la ligera. No. Quédate por defecto en workspace-write + on-request.
• Que los límites te agarren desprevenido. El uso de Codex te consume la cuota agéntica de tu plan. Revisa /status a mitad de sesión; para los números vigentes según el plan, la fuente de verdad es la página de precios de OpenAI, no un blog (este incluido).
• Confusión con el instalador de Windows. El one-liner de curl es solo para macOS/Linux. En Windows usa el instalador .ps1 de PowerShell o vete por WSL2.

Acabas de convertir una terminal y un solo prompt en un juego que funciona, y en el camino aprendiste las únicas tres cosas que de verdad importan con Codex: ábrelo dentro de la carpeta sobre la que debe trabajar, mantenlo en un sandbox sensato para que se mueva rápido sin hacer daño, y apóyate en codex exec en cuanto lo quieras dentro de un script en vez de en una sesión. El juego de Snake es un juguete, pero el ciclo (apúntalo a un directorio, describe el resultado, aprueba los pasos) es exactamente como le pedirías que arregle un bug en un repo real, redacte notas de release o levante la siguiente cosa que vayas a construir. Empieza por ahí.