Cómo Instalar la CLI de OpenAI Codex (Windows, macOS, Linux)

- Los comandos y las rutas de la documentación se contrastaron con la documentación oficial en la fecha de redacción (08/2026); el dominio de la documentación de Codex ya se mudó una vez (developers.openai.com → learn.chatgpt.com), así que verifica la documentación actual antes de ejecutarlos si esta página ya es antigua.

Antes de instalar la Codex CLI

Antes de instalar OpenAI Codex, ten listo lo siguiente:

• Un plan de ChatGPT compatible con Codex. Según la página de precios en la fecha de redacción, el acceso a la CLI es más claro a partir de Plus (Plus, Pro, Business, Enterprise) o mediante pago por uso con una clave de API; puede que Free/Go no lo incluyan - consulta los precios de Codex antes de instalar en vez de adivinar.
• Un sistema operativo: Windows, macOS o Linux - la Codex CLI funciona de forma nativa en los tres, sin necesidad de WSL2 en Windows y sin tener que pensar en compilaciones separadas para Apple Silicon o Intel (el instalador elige el binario correcto por ti).
• Una conexión que funcione con chatgpt.com para descargar el instalador e iniciar sesión - un proxy corporativo cautivo o una red muy restringida pueden bloquear la descarga aunque el resto de tu internet funcione bien.
• Node.js solo si eliges la vía de instalación con npm - los otros dos métodos (script de instalación, Homebrew) no tocan Node.

Con estos cuatro puntos listos, la instalación en sí es un comando más una breve espera de descarga - la parte que suele tardar más es elegir la cuenta de ChatGPT correcta para iniciar sesión, sobre todo si tienes tanto una cuenta personal como una proporcionada por la empresa (Business/workspace). Las dos pueden tener permisos de CLI distintos, así que, si una pantalla de inicio de sesión te resulta extraña o la CLI informa de un plan que no esperabas, comprueba con qué cuenta estás realmente autenticada antes de dar por hecho que algo se rompió.

Instalar la Codex CLI en macOS y Linux

La vía más rápida es el script de instalación oficial, ejecutado directamente en la terminal - descarga un binario nativo, sin necesidad de otro runtime:

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

Pasar curl directo a sh incomoda a algunas personas, y ese instinto es razonable en general - estás confiando en lo que la URL devuelva en ese momento. Si prefieres no ejecutar a ciegas un script que no has leído, descárgalo primero (curl -fsSL https://chatgpt.com/codex/install.sh -o install.sh), léelo y luego ejecuta sh install.sh. Para una instalación puntual en el dominio oficial de un proveedor conocido, la mayoría de los desarrolladores acepta el riesgo; para una máquina restringida o compartida, vale la pena el minuto extra de descargar y leer.

Dos alternativas si prefieres gestionarlo con un gestor de paquetes:

brew install --cask codex

npm install -g @openai/codex

La trampa más común: el nombre del paquete de npm es @openai/codex, no simplemente codex - ejecutar npm install -g codex instala el paquete equivocado (o da 404). Dos de las guías en inglés que leí señalan justo este error. Si vas por la vía de npm, usa una versión LTS actual de Node.js; las fuentes secundarias que contrasté no coinciden en la versión mínima exacta, así que, si npm lanza un error de versión, actualiza Node a la última LTS primero, o evita todo el asunto con el script de instalación o Homebrew de arriba. Consulta el README oficial en GitHub si necesitas comprobarlo.

¿Cuál elegir? Si es una instalación única y no te importan las actualizaciones manuales, usa el script de instalación - es el más rápido. Si tu máquina ya se apoya en Homebrew para todas las demás CLI, mantén esa costumbre (un brew upgrade posterior también actualiza Codex). La vía de npm solo tiene sentido si ya tienes Node.js instalado para otra cosa - no instales Node solo para usar esta opción.

Instalar la Codex CLI en Windows

En Windows, abre PowerShell y ejecuta exactamente este comando - yo misma lo ejecuté en vivo en mi propia máquina Windows mientras escribía esto:

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

1. Abre PowerShell (en la mayoría de las máquinas no hacen falta permisos de administrador).
2. Pega el comando completo de arriba y pulsa Enter.
3. La opción -ExecutionPolicy ByPass se aplica solo a esta ejecución - no cambia la política de tu máquina - solo permite que este script de instalación sin firmar se ejecute esta única vez.
4. Cierra la terminal antigua y abre una nueva para que el PATH actualizado surta efecto.
5. Ejecuta codex --version para confirmar.

Prefiere Windows Terminal a la antigua ventana de cmd.exe si lo tienes instalado - no es obligatorio, pero el prompt de PowerShell y cualquier salida en color que imprima Codex se ven de forma más fiable ahí, y es lo que usé en la ejecución en vivo de arriba.

La Codex CLI funciona de forma nativa en Windows - no se necesita WSL2. Si tu equipo ya estandarizó en WSL2 (por ejemplo, para compartir scripts con un pipeline de CI de Linux), todavía puedes instalar Codex dentro de WSL2 con el mismo comando curl de la sección de macOS/Linux de arriba; no hay un comando de WSL2 específico para Windows.

Si tu máquina Windows está gestionada por la empresa (un dispositivo bajo directiva de grupo), -ExecutionPolicy ByPass todavía puede bloquearse en la capa de directiva de la organización, no solo en la del usuario - en ese caso, TI tiene que relajarla y no hay solución del lado del usuario. Windows Defender SmartScreen también puede pedirte confirmación la primera vez que ejecutas un instalador recién descargado - es una advertencia normal para un archivo nuevo, no una señal de que algo esté roto.

Verificar la instalación

Ejecuta codex --version. Si te devuelve un número de versión, ya terminaste. Si la terminal dice que codex no se reconoce, casi siempre es un PATH desactualizado - cierra la terminal por completo (incluida la integrada de un IDE) y abre una ventana nueva antes de sospechar de otra cosa. Si probaste más de un método de instalación (por ejemplo, npm y luego el script de instalación) y codex --version muestra una versión inesperada, es probable que tengas dos copias en el PATH - comprueba cuál se ejecuta de verdad con where codex (Windows) o which codex (macOS/Linux) y elimina la que sobra.

Iniciar sesión en Codex

Ejecuta codex en tu terminal para lanzar la CLI y elige la opción de inicio de sesión con ChatGPT cuando te lo pida (el texto exacto en pantalla puede cambiar entre versiones - sigue lo que la CLI te muestre en el momento). El flujo suele abrir una pestaña del navegador para que confirmes el inicio de sesión y luego devuelve la sesión a la terminal automáticamente - sin pegar tokens a mano. Tu plan de ChatGPT determina qué modelo y qué límites de uso obtienes; consulta los precios de Codex por plan para los detalles en vez de adivinar cifras aquí. Si el inicio de sesión falla en silencio (la pestaña del navegador se cierra pero la terminal nunca confirma), la causa más común es una capa de SSO o proxy corporativo que intercepta la redirección - inténtalo de nuevo en una red sin restricciones antes de dar por hecho que la propia CLI está fallando.

Ejecutar tu primer comando de Codex

Entra con cd en una carpeta de proyecto de verdad (no una vacía - Codex necesita código real para leer y trabajar) y luego ejecuta:

codex

Prueba algo concreto, como: "Lee el README y enumera 3 formas de ejecutar las pruebas en este repositorio." O algo más pequeño para calentar: "Enumera los 5 archivos más grandes de este repositorio por número de líneas." Si Codex necesita ejecutar un comando o editar un archivo, se detendrá y pedirá aprobación primero (según tu approval_policy) y te mostrará el comando o el diff exacto que quiere ejecutar para que lo apruebes o lo rechaces - ese es el flujo normal de aprobación, no un error; la sección de configuración de abajo explica por qué se detiene y cómo aflojarlo o apretarlo. Una primera ejecución exitosa suele terminar con Codex imprimiendo un breve resumen de lo que leyó o cambió, además de alguna sugerencia de próximo paso - si, en cambio, recibes un error inmediato antes de que haga nada, eso casi siempre apunta de vuelta al paso de inicio de sesión de arriba, no a este.

Nociones básicas de ~/.codex/config.toml

Tu configuración de usuario vive en ~/.codex/config.toml; un proyecto puede sobrescribirla con un .codex/config.toml en la raíz del repositorio. Precedencia (de mayor a menor, según la documentación oficial de configuración): flags de la CLI > .codex/config.toml del proyecto > perfil (--profile) > ~/.codex/config.toml del usuario. En la práctica, eso significa: si tu ~/.codex/config.toml personal establece approval_policy = "on-request" como un valor global sensato, pero el .codex/config.toml de un repositorio concreto establece approval_policy = "untrusted" para un flujo más estricto, el archivo del proyecto gana siempre que trabajes dentro de ese repositorio - y una flag puntual --approval-policy en la CLI les gana a ambos, para una sola ejecución.

Estos tres son los que más vale la pena ajustar primero: model equilibra calidad, velocidad y coste; sandbox_mode decide qué puede tocar Codex de verdad (también hay una opción más segura read-only y una danger-full-access que no deberías usar como valor por defecto); approval_policy decide con qué frecuencia tienes que aprobar manualmente. Pon los tres en un único ~/.codex/config.toml y queda así:

model = "gpt-5.6"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Esta es solo la capa básica. La siguiente capa - enseñarle a Codex las convenciones propias de tu proyecto (comandos de prueba/compilación, reglas que no se pueden romper) - está en AGENTS.md para Codex.

Errores comunes de instalación y soluciones

La mayoría de los problemas de instalación se reducen a una de cuatro cosas: un nombre de paquete mal escrito, un PATH desactualizado, la política de scripts por defecto de Windows o una carpeta cuyos permisos Codex no puede resolver de forma limpia. Aquí tienes cada una, con la solución de verdad en vez de un genérico "reinstala y reza":

Atención: dos comandos de instalación "curl ... | sh" diferentes

Si más adelante te topas con instrucciones para curl -fsSL https://agentkit.best/install.sh | sh, eso es una herramienta totalmente distinta - AgentKit (la CLI ak), un kit de pago que se instala encima de Codex o Claude Code, no parte del propio Codex. Los dos comandos son casi idénticos (mismo formato curl -fsSL <domain>/install.sh | sh), así que, si guardas cualquiera de ellos en notas o en el historial del shell para después, etiquétalo con el dominio - no copies y pegues un script creyendo que es el otro.

Un hábito más que vale la pena adoptar pronto: la Codex CLI se actualiza rápido, y tanto el dominio de instalación como algunas flags de la CLI ya cambiaron una vez desde el lanzamiento. Volver a ejecutar el comando de instalación de vez en cuando (o la vía de actualización del método que usaste) es un seguro barato contra seguir ejecutando, sin darte cuenta, una compilación antigua.

Preguntas frecuentes

¿Instalar la Codex CLI es gratis?

La CLI en sí es de código abierto y gratuita de instalar, y el binario no caduca ni te da la lata. Para iniciar sesión y usarla de verdad, necesitas un plan de ChatGPT compatible con Codex (más claro a partir de Plus, según la página de precios en la fecha de redacción) o una clave de API facturada por uso.

¿Necesito una clave de API?

No, si inicias sesión con un plan de ChatGPT compatible con Codex - esa es la vía por defecto para la mayoría de los desarrolladores individuales. Una clave de API solo hace falta si quieres pagar por token (útil para automatización/CI, donde iniciar sesión de forma interactiva no es práctico) en vez de usar un plan de ChatGPT.

¿Puedo instalarla sin Node.js?

Sí. El script de instalación oficial (curl ... | sh en macOS/Linux, PowerShell en Windows) y Homebrew no requieren Node.js en absoluto. Solo la vía npm install -g @openai/codex necesita Node, ya que el propio npm viene con Node.js.

¿Necesita WSL en Windows?

No. La Codex CLI funciona de forma nativa en Windows, con su propio instalador y su propio binario. WSL2 solo es útil si quieres específicamente compartir un pipeline de Linux existente o scripts de shell con tu equipo.

¿Cómo la actualizo?

Vuelve a ejecutar el mismo método de instalación que usaste al principio (el script de instalación, brew upgrade o npm install -g @openai/codex) y sobrescribe la versión antigua con la más reciente - no hace falta un paso de desinstalación aparte antes.

¿Añadir AgentKit después de instalar Codex?

La Codex CLI en sí es gratuita (se apoya en el plan de ChatGPT que ya tienes). AgentKit es una capa aparte y de pago que instalas encima de Codex para tener skills/subagents/workflows listos en vez de armar los tuyos: ak kit init engineer --target codex --global, confirma la pantalla de vista previa, abre una nueva sesión de Codex y luego ejecuta $ak:cook ... para empezar. Nada de esto cambia el comando base codex que acabas de instalar - solo le da a ese comando cosas más estructuradas para ejecutar. Esta es la misma configuración de gate que yo misma uso tanto en Claude Code como en Codex, no un anuncio de relleno - los detalles están en AgentKit in Codex. Si hoy solo estás tanteando Codex, sáltate este paso por completo y vuelve cuando de verdad sientas la fricción de reexplicar tu flujo de trabajo en cada sesión - ese es el punto en el que un kit ya armado empieza a valer la pena.