Instalar Codex CLI no termina cuando el gestor deja de mostrar errores. El resultado útil tiene tres partes: la terminal encuentra el ejecutable, Codex se abre en la carpeta del proyecto y la sesión usa el método de autenticación que esperabas.
La ruta corta es esta:
- Elige uno de los canales oficiales que encaje con tu sistema y tus herramientas actuales.
- Ejecuta su comando de instalación.
- Abre la carpeta de un proyecto y ejecuta
codex. - Completa el acceso con ChatGPT o con una clave de API, según corresponda a tu caso.
- Ejecuta
codex login statuspara comprobar el método activo.
Los comandos de esta guía se comprobaron el 16 de agosto de 2026 en la documentación oficial de Codex CLI y en la guía oficial de autenticación. Son las rutas documentadas en esas fuentes en esa fecha, no una promesa de que todos los equipos, redes o cuentas obtendrán el mismo resultado.
Antes de instalar: elige la superficie correcta
Codex CLI es el ejecutable que se abre desde una terminal dentro de una carpeta de trabajo. No es lo mismo que la extensión para un IDE, la aplicación de escritorio ni las experiencias web o cloud de Codex.
Si quieres escribir codex en una terminal y trabajar sobre un repositorio local, estás en la guía correcta. Si querías una interfaz dentro de VS Code u otro IDE, o una tarea ejecutada en cloud, instalar el CLI no convierte automáticamente tu entorno en esa otra superficie.
También conviene separar la instalación de la forma de acceso:
- Inicio de sesión con ChatGPT: utiliza el flujo de acceso asociado a ChatGPT y queda sujeto a la elegibilidad, los controles y las condiciones de esa cuenta o workspace.
- Inicio de sesión con clave de API: utiliza acceso basado en API y consumo medido por uso. No debes asumir que una suscripción de ChatGPT incluye crédito de API.
La disponibilidad concreta de planes, funciones, workspace o región depende de la cuenta y del entorno. La existencia de ambos métodos no garantiza que cualquiera de ellos esté habilitado para ti.
Instalar Codex CLI por el canal oficial adecuado
Elige un canal principal. Instalar la misma herramienta por varios gestores puede dejar ejecutables duplicados en distintas rutas y hacer que la terminal abra una versión diferente de la que acabas de actualizar.
| Elige este canal | Cuando encaja con tu entorno | Cómo se actualiza |
|---|---|---|
| Instalador independiente | Quieres la ruta oficial para macOS/Linux o Windows sin administrar el paquete mediante npm | Vuelve a ejecutar el instalador de tu plataforma |
| npm | Ya gestionas herramientas globales con npm | Repite npm install -g @openai/codex |
| Homebrew | Ya utilizas Homebrew en macOS | Ejecuta brew upgrade --cask codex |
La tabla sirve para elegir una ruta, no para declarar una opción universalmente mejor. Si tu equipo está administrado o tu red aplica restricciones, el comando oficial aún puede quedar bloqueado por permisos, políticas o conectividad.
Instalador independiente para macOS y Linux
OpenAI documenta este comando para el instalador independiente:
bashcurl -fsSL https://chatgpt.com/codex/install.sh | sh
La misma fuente indica volver a ejecutar el comando para actualizar ese canal. Esta ruta no pasa por npm, pero el comando documentado no demuestra compatibilidad universal con todas las distribuciones, arquitecturas, políticas de red o configuraciones de shell.
Instalador independiente para Windows
En PowerShell, la documentación oficial muestra:
powershellpowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Volver a ejecutar el mismo comando es la ruta documentada para actualizar esta instalación. En un equipo administrado, una política de PowerShell, un proxy o los permisos corporativos pueden impedir la ejecución; el comando oficial no equivale a una garantía para cada dispositivo.
npm en macOS, Linux o Windows
Si ya administras herramientas globales con npm, el paquete oficial es @openai/codex:
bashnpm install -g @openai/codex
La actualización usa el mismo comando. La documentación revisada confirma el paquete y la instrucción, pero no establece una versión mínima universal de Node.js para esta ruta. No necesitas instalar Node.js si has elegido el instalador independiente o Homebrew.
Homebrew en macOS
Si Homebrew ya forma parte de tu flujo, puedes instalar el cask oficial:
bashbrew install --cask codex
Para actualizarlo:
bashbrew upgrade --cask codex
Que Homebrew sea una opción documentada no significa que sea preferible para todas las personas. Mantener el mismo canal para instalar y actualizar reduce la ambigüedad.
Primera ejecución: abre Codex dentro de un proyecto
Una vez terminada la instalación, entra en la carpeta sobre la que quieres trabajar:
bashcd /ruta/a/tu/proyecto codex
El segundo comando es la primera comprobación útil: si la terminal no encuentra codex, todavía tienes un problema de instalación o de resolución de la ruta. Abrir otra ventana de terminal puede ser necesario después de que un instalador modifique el entorno, pero no conviene empezar a copiar arreglos de PATH de terceros sin saber qué canal instalaste y qué ejecutable intenta resolver tu shell.
Si codex se abre, el binario está disponible desde esa terminal. Aún falta comprobar la autenticación.
En el primer arranque, la guía oficial permite elegir Sign in with ChatGPT u otro método disponible. Esa pantalla no cambia la distinción entre acceso de ChatGPT y acceso por API: elige según la cuenta, el workspace y la modalidad de facturación que realmente pretendes usar.
Iniciar sesión y comprobar el método activo
Para abrir el flujo de autenticación de ChatGPT desde el CLI:
bashcodex login
Normalmente este flujo continúa en el navegador. Que el comando se abra no garantiza que una cuenta concreta tenga permiso, que una red permita completar el proceso o que un workspace habilite las mismas funciones.
Si tu caso requiere una clave de API, la documentación oficial muestra esta entrada por stdin en un shell compatible con printenv:
bashprintenv OPENAI_API_KEY | codex login --with-api-key
Este ejemplo presupone que OPENAI_API_KEY ya existe de forma segura en el entorno. Si tu shell no dispone de printenv, consulta la misma guía oficial para adaptar la entrada sin exponer el secreto. No pegues la clave en un prompt, una captura, un repositorio ni un equipo que no controles. Tampoco conviertas un secreto en un argumento visible solo para resolver más rápido el inicio de sesión.
Después de cualquiera de los flujos, consulta el estado:
bashcodex login status
Esta es la señal que separa «Codex se abrió» de «Codex reconoce una autenticación activa». Lee el método mostrado y confirma que coincide con tu intención:
- Si querías utilizar el acceso asociado a ChatGPT, no des por hecho que has iniciado una sesión de API.
- Si querías consumo basado en API, no interpretes una suscripción de ChatGPT como saldo o crédito para la API.
- Si trabajas en una organización, las políticas y controles del workspace siguen aplicándose después del login.
Para retirar las credenciales almacenadas por Codex:
bashcodex logout
La comprobación completa en tres estados
En lugar de considerar suficiente el mensaje final del instalador, valida cada estado por separado.
| Estado | Acción | Señal que buscas | Si falla |
|---|---|---|---|
| Ejecutable disponible | Ejecuta codex desde la terminal | Codex se abre en lugar de aparecer «comando no encontrado» | Revisa el canal usado, abre una terminal nueva y evita instalaciones duplicadas |
| Contexto de trabajo correcto | Ejecuta codex dentro de la carpeta del proyecto | La sesión parte del proyecto que quieres inspeccionar | Sal, entra en la carpeta correcta y vuelve a abrir Codex |
| Autenticación activa | Ejecuta codex login status | Se muestra un método de acceso activo y coherente con tu elección | Repite codex login o revisa la configuración segura de la clave de API |
Este protocolo no intenta demostrar que cualquier petición futura tendrá éxito. Cuenta, workspace, red, permisos, políticas y disponibilidad de funciones pueden introducir límites después de una instalación y autenticación válidas.
Cómo localizar el fallo sin reinstalar a ciegas
Cuando algo no funciona, identifica primero el estado que falta.
La terminal no encuentra codex
El problema está antes de la autenticación. Confirma qué canal elegiste y evita ejecutar inmediatamente todos los instaladores disponibles. Si utilizaste npm, el ejecutable global debe quedar en una ruta que tu shell pueda resolver; esta guía no fija un PATH universal porque cambia entre sistemas y configuraciones.
codex se abre, pero el login no termina
La instalación ya superó la comprobación del binario. El siguiente diagnóstico pertenece al navegador, la cuenta, el workspace, la red o el método de acceso. Ejecuta codex login status antes de reinstalar: así sabrás si no existe una sesión, si quedó activa otra modalidad o si el problema aparece después de autenticar.
La clave de API no se reconoce
No la pegues en lugares públicos para comprobarla. Verifica en tu propio entorno que la variable esperada esté disponible para el proceso y vuelve a usar la entrada por stdin. Si el acceso sigue fallando, trata la credencial como un secreto y sigue la documentación de la cuenta o la API; una reinstalación del CLI no crea permisos ni saldo.
Instalaste el CLI, pero esperabas el IDE, la app o cloud
No es un fallo de instalación. Son superficies distintas. Conserva el CLI si quieres trabajar desde la terminal local; si tu objetivo era otro, vuelve a la página oficial de Codex y elige la superficie correspondiente sin asumir que comparten instalación, funciones o modalidad de ejecución.
Actualizar sin cambiar de canal
Usa la instrucción correspondiente al canal que ya elegiste:
- Instalador independiente de macOS/Linux: vuelve a ejecutar el script oficial.
- Instalador independiente de Windows: vuelve a ejecutar el comando oficial de PowerShell.
- npm: vuelve a ejecutar
npm install -g @openai/codex. - Homebrew: ejecuta
brew upgrade --cask codex.
Si no recuerdas cómo instalaste Codex, averígualo antes de alternar entre canales. El objetivo no es acumular copias, sino mantener un único ejecutable reconocible y actualizarlo por la ruta que lo administra.
Qué significa «instalación terminada»
Codex CLI está listo para tu primera tarea cuando puedes abrir codex desde la terminal en la carpeta prevista y codex login status muestra el método de autenticación que querías utilizar. Eso confirma el ejecutable, el contexto inicial y la sesión; no confirma por sí solo elegibilidad regional, acceso a todas las funciones, permisos de workspace ni precios concretos.
Para volver a comprobar comandos o cambios posteriores, usa siempre la documentación oficial de Codex CLI y la documentación oficial de autenticación como referencia vigente.
