Solución de problemas al instalar Codex CLI: PATH, acceso y WSL
Si la instalación termina pero tu terminal muestra codex: command not found, el problema no es la autenticación: la terminal no puede localizar el ejecutable. Si Codex abre y luego se atasca durante la autenticación del navegador, la instalación ya está completa. Trátalos como dos fallos separados.
Comprueba la instalación en un solo comando
Abre una terminal nueva y ejecuta:
codex --version
Un número de versión confirma que esa terminal puede encontrar y ejecutar Codex. Si el problema es solo la autenticación, salta al apartado de inicio de sesión. Si el comando no aparece, verifica si instalaste Codex en el mismo entorno que estás usando ahora. Una discrepancia común es instalarlo en PowerShell y luego buscar el comando en WSL, o al revés.
Verifica qué terminal ejecutó el instalador
En macOS, Linux o WSL, ejecuta el script oficial dentro de esa terminal:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Para Windows nativo, abre PowerShell —no una ventana de WSL— y ejecuta:
irm https://chatgpt.com/codex/install.ps1 | iex
Si ya tienes instalado Node.js y npm, el paquete de npm es otra opción compatible:
npm install --global @openai/codex
Después de completar cualquier método, cierra todas las terminales, abre una nueva y ejecuta codex --version. Usa un solo método de instalación. Varios ejecutables pueden dejar una versión antigua antes que la nueva en PATH, y ya no queda claro qué versión estás usando.
El instalador independiente coloca el ejecutable en ~/.local/bin en macOS y Linux, y en %LOCALAPPDATA%\Programs\OpenAI\Codex\bin en Windows.
Si el archivo existe pero el comando no, compara la carpeta de instalación con PATH.
En macOS, Linux o WSL:
ls -l ~/.local/bin/codex
printf '%s\n' "$PATH" | tr ':' '\n'
Si ~/.local/bin no está presente, ejecuta export PATH="$HOME/.local/bin:$PATH" en la terminal actual y prueba de nuevo. Una vez que funcione, agrega la misma línea a ~/.zshrc o ~/.bashrc.
En Windows PowerShell:
Test-Path "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin\codex.exe"
$env:Path -split ';'
Si el ejecutable existe pero la carpeta está ausente, agrega %LOCALAPPDATA%\Programs\OpenAI\Codex\bin a tu variable de entorno de usuario de Windows Path, luego reinicia PowerShell.
Mantén las instalaciones de Windows y WSL separadas
PowerShell y WSL son entornos de ejecución separados. Por defecto, WSL agrega las carpetas de Windows a $PATH, por lo que puede llegar a iniciar un programa de Windows como codex.exe. Eso no significa que el ejecutable de Linux codex esté instalado en WSL. Si trabajas dentro de WSL, instala la versión Linux allí.
Para configurar WSL2, ejecuta esto en un PowerShell elevado o en Windows Terminal:
wsl --install
Reinicia Windows si se te solicita. Completa la configuración inicial del usuario Linux, luego entra en WSL:
wsl
Dentro de la terminal de Linux, instala Codex con el script de Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Abre una terminal nueva de WSL y confirma con codex --version. La documentación actual de Codex recomienda WSL2; WSL1 dejó de ser compatible a partir de Codex 0.115. Guardar los proyectos en el directorio personal de WSL, como ~/code/..., en lugar de /mnt/c/..., también evita muchos problemas de sistema de archivos y permisos.
Si te quedas en PowerShell, mantén solo la instalación de Windows. Si usas WSL, mantén la instalación, la ejecución y los archivos del proyecto en el lado de WSL.
Si el inicio de sesión del navegador no vuelve a la terminal
Cuando Codex se inicia pero la autenticación no termina, reinicia el flujo de inicio de sesión estándar:
codex login
Después de iniciar sesión en ChatGPT en el navegador, Codex debería recibir las credenciales. Verifica el estado actual de autenticación con:
codex login status
En una máquina remota o sin interfaz gráfica —o en una red corporativa que bloquee el callback local—, el navegador puede completar la autenticación mientras el terminal sigue esperando. En ese caso, usa el flujo de código de dispositivo, todavía en fase beta. Las cuentas personales deben habilitar primero la autorización por código de dispositivo en la configuración de seguridad de ChatGPT; los espacios de trabajo gestionados requieren que un administrador lo permita.
codex login --device-auth
Para cambiar de cuenta o limpiar una caché de autenticación sospechosa, cierra sesión y comienza de nuevo. codex logout elimina las credenciales almacenadas, así que úsalo solo cuando estés listo para autenticarte nuevamente.
codex logout
codex login
Un espacio de trabajo gestionado de ChatGPT puede restringir los métodos de inicio de sesión o los espacios de trabajo permitidos. Si Codex sigue rechazando una cuenta personal, verifica la política de la organización antes de reinstalar.
Si la instalación y el inicio de sesión parecen estar en orden
Cuando la versión y el estado de autenticación son correctos pero Codex aún no puede iniciar, ejecuta el resumen de diagnóstico:
codex doctor --summary
Este comando comprobará la instalación local, la configuración, las credenciales y el entorno de ejecución. Al solicitar ayuda, incluye el sistema operativo, la terminal, la salida de codex --version, el método de instalación y el elemento del diagnóstico que falló. Nunca pegues un token de acceso o el contenido de ~/.codex/auth.json.