Cómo instalar Codex CLI en macOS, Linux y Windows

Instalar Codex CLI no consiste solo en conseguir que la terminal reconozca el comando codex. Para dar la tarea por terminada deben encajar tres piezas: el ejecutable tiene que estar instalado y localizable, la CLI debe abrirse dentro del proyecto correcto y el método de acceso disponible para tu cuenta debe completar su flujo y devolverte a la terminal.

Esta guía te ayuda a elegir una vía de instalación sin asumir que Node.js o npm son requisitos universales. Los métodos se contrastaron el 15 de agosto de 2026 con la guía oficial de primeros pasos de Codex CLI. Como las opciones, los comandos y la compatibilidad pueden cambiar, conviene abrir esa página antes de instalar y utilizar allí la descarga o instrucción vigente.

Elige el método por tu equipo, no por costumbre

La documentación oficial ofrece instaladores independientes para macOS y Linux, un instalador para Windows y alternativas mediante npm y Homebrew. La diferencia importa: un instalador independiente evita añadir un gestor de paquetes solo para obtener Codex, mientras que npm o Homebrew pueden encajar mejor si ya forman parte de tu entorno y quieres gestionar la herramienta junto al resto de dependencias.

• Instalador independiente de tu plataforma. Es la ruta más directa si no necesitas gestionar Codex con otras herramientas. Antes de empezar, comprueba la arquitectura y la versión del sistema indicadas en la descarga oficial.
• npm. Encaja si ya mantienes herramientas globales con Node.js. Confirma que node y npm funcionan en esa misma terminal y que el directorio de ejecutables globales está en PATH.
• Homebrew. Es una opción práctica si lo utilizas habitualmente en macOS. Verifica que brew funciona y que su directorio de binarios está en PATH.
• Instalador oficial para Windows. Es la opción específica para Windows, especialmente relevante en equipos administrados. Revisa los permisos de instalación y las políticas del equipo o del espacio de trabajo.

PATH es la lista de ubicaciones en las que el sistema busca ejecutables cuando escribes un comando. Si la instalación termina pero codex aparece como «comando no encontrado» o «no se reconoce como un comando», el problema suele estar entre la ubicación del ejecutable y el PATH; no demuestra que el paquete o el instalador sean incorrectos.

Evita empezar por npm solo porque una guía antigua lo presenta como la única vía. También evita instalar Node.js si no lo necesitas para tu trabajo ni para el método elegido. Una dependencia propia de una alternativa no debe convertirse en un requisito ficticio para todas las instalaciones.

Instala Codex CLI en macOS o Linux

Para una instalación independiente, entra en la sección oficial de instalación de Codex CLI, elige la descarga que corresponda a tu sistema y arquitectura y sigue las indicaciones de esa versión. Usa la ubicación sugerida por la guía o una carpeta de ejecutables que ya esté incluida en tu PATH.

Si prefieres un gestor de paquetes, utiliza la instrucción vigente que la misma página muestra para Homebrew o npm. Esta elección tiene una ventaja operativa: las actualizaciones y la desinstalación se realizan desde el gestor que ya utilizas. A cambio, heredas sus requisitos y su configuración. Antes de atribuir un fallo a Codex, comprueba primero el gestor elegido:

bash
node --version
npm --version

Esos dos comandos solo son pertinentes si has elegido npm. Para Homebrew, la comprobación equivalente es:

bash
brew --version

Al terminar, cierra y abre una terminal nueva. Así evitas que una sesión antigua conserve un PATH anterior. Después comprueba que el sistema encuentra el ejecutable:

bash
command -v codex

Si el comando devuelve una ruta, la terminal puede localizar codex. Aún falta arrancarlo desde un proyecto y completar el acceso; encontrar el archivo no prueba esas dos capas.

Instala Codex CLI en Windows

Windows dispone de su propio instalador independiente según la documentación oficial de primeros pasos. Descárgalo desde la fuente oficial, ejecuta el proceso con una cuenta que tenga los permisos necesarios y abre una terminal nueva cuando termine.

En PowerShell puedes comprobar si el ejecutable es visible con:

powershell
Get-Command codex

Si PowerShell muestra la ubicación del comando, la instalación está expuesta a esa terminal. Si no lo encuentra, comprueba primero que el instalador finalizó y después revisa si su carpeta se añadió a PATH. En un equipo corporativo, una política de aplicaciones o un antivirus gestionado puede impedir la instalación o la ejecución; en ese caso, repetir el instalador sin revisar el aviso no suele aportar información nueva.

La alternativa con npm también exige que Node.js y npm estén disponibles en el mismo entorno desde el que ejecutarás Codex. No mezcles sin querer instalaciones entre PowerShell, otra terminal de Windows y un entorno Linux: cada entorno puede tener su propio sistema de archivos, sus paquetes y su PATH. Instalar en uno no garantiza que el comando exista en los demás.

Haz la prueba que realmente importa: abrir un proyecto

La comprobación oficial posterior a la instalación consiste en abrir un directorio de proyecto y ejecutar el comando codex. Después, escoge el inicio de sesión con ChatGPT u otro método que aparezca disponible en el primer arranque. No hagas la primera prueba desde una carpeta aleatoria: Codex utiliza el directorio abierto como contexto de trabajo.

En macOS o Linux:

bash
cd /ruta/a/tu/proyecto
pwd
codex

En PowerShell:

powershell
Set-Location C:\ruta\a\tu\proyecto
Get-Location
codex

Sustituye las rutas de ejemplo por la carpeta real de tu proyecto. El segundo comando te permite verificar visualmente dónde estás antes de iniciar la CLI.

Separa la comprobación en dos hitos. La instalación local está resuelta cuando se cumplen estas señales:

1. La terminal reconoce codex sin necesitar una ruta manual al ejecutable.
2. La CLI se abre desde el directorio de proyecto esperado.

Después comprueba la primera sesión autenticada: debe aparecer una opción de acceso válida para tu cuenta, el flujo debe completarse y la CLI debe recuperar el control en esa misma terminal. En el acceso con ChatGPT, la documentación oficial de autenticación indica que Codex abre una ventana del navegador y devuelve las credenciales a la CLI después de autenticarte. Mantén abierta la terminal mientras completas el proceso y vuelve a ella al terminar.

Que la CLI arranque demuestra que la instalación local es funcional; que el acceso termine demuestra que ese método ha funcionado en ese momento. Ninguna de las dos comprobaciones garantiza por sí sola que todos los modelos o funciones estén disponibles para una cuenta, red, organización o región concretas. Las opciones mostradas también pueden variar según la versión, la cuenta o las políticas del espacio de trabajo.

Diagnostica el fallo por la etapa en la que ocurre

Reinstalar es razonable cuando faltan archivos o el instalador no termina. Para el resto de casos, localiza primero el punto exacto de ruptura.

La terminal no encuentra codex

Abre una terminal nueva y repite command -v codex en macOS/Linux o Get-Command codex en PowerShell. Si sigue sin aparecer:

• confirma que instalaste Codex en ese mismo sistema o entorno;
• revisa el mensaje final del instalador o gestor de paquetes;
• localiza el directorio donde se guardan los ejecutables y comprueba que forme parte de PATH;
• si utilizaste npm, verifica que no estés alternando entre distintas instalaciones de Node.js.

No modifiques PATH copiando una ruta de otra persona: la ubicación depende del sistema, la arquitectura, el gestor y la configuración local.

codex abre, pero estás en el proyecto equivocado

Sal de la CLI, entra en la carpeta correcta con cd o Set-Location, confirma la ubicación y vuelve a ejecutar codex. Este fallo no requiere reinstalación. Es una diferencia de contexto de trabajo.

El navegador se abre, pero el acceso no vuelve a la CLI

Comprueba que la terminal original siga abierta y observa si muestra un mensaje accionable. Completa el flujo en el navegador que se abrió, sin iniciar varias solicitudes a la vez. Si el navegador termina pero la terminal no recibe las credenciales, revisa restricciones de red, enlaces locales o políticas de la cuenta antes de borrar la instalación.

La autenticación termina, pero no puedes iniciar una sesión

En este punto, el ejecutable y el acceso pueden estar correctamente configurados. El bloqueo puede pertenecer a la cuenta, la organización, la red o la disponibilidad del servicio. Conserva el mensaje exacto y consulta al administrador del espacio de trabajo o al canal oficial de soporte que corresponda. Cambiar de instalador no resuelve una política de cuenta.

Cierra la instalación con una comprobación reproducible

La instalación queda verificada cuando puedes abrir una terminal nueva, entrar en un proyecto real y ejecutar codex sin indicar la ruta del archivo. La preparación para la primera sesión exige además completar una opción de acceso disponible y regresar a la CLI. Anota qué plataforma y método utilizaste; ese dato reduce mucho el tiempo de diagnóstico si más adelante falla una actualización o cambia tu entorno.

Antes de repetir el proceso en otro equipo, comprueba de nuevo el método que corresponde a tu plataforma. Después, vuelve a consultar las instrucciones oficiales vigentes. Si ahora mismo codex se abre dentro del proyecto correcto y el acceso devuelve el control a la CLI, ya tienes la señal observable buscada. Si no, vuelve a la etapa concreta que falló —ejecutable, directorio o autenticación— y corrige solo esa capa.