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

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, npm o WSL son requisitos universales. Los métodos se contrastaron el 1 de septiembre de 2026 con la guía oficial de Codex CLI. Como las opciones, los comandos y la compatibilidad pueden cambiar, abre esa página antes de instalar si algo difiere.

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 en macOS o Linux, ejecuta el comando oficial actual:

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

El mismo comando actualiza una instalación hecha por esta ruta. Confirma que el dominio sea chatgpt.com y respeta la política de scripts de un equipo gestionado.

Si prefieres un gestor de paquetes, las rutas actuales son:

bash
npm install -g @openai/codex
brew install --cask codex

Esta elección permite actualizar desde el gestor que ya utilizas, pero hereda sus requisitos. 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 un instalador independiente en la documentación oficial. Abre PowerShell y ejecuta:

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

El mismo comando actualiza la instalación standalone. Si una política corporativa bloquea scripts o cambios de seguridad, no la desactives para forzar el proceso: utiliza la vía aprobada por el administrador.

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 exige que Node.js y npm estén disponibles en el mismo entorno desde el que ejecutarás Codex. No mezcles instalaciones entre PowerShell y WSL2: cada entorno tiene su sistema de archivos, paquetes, PATH, home y configuración.

Si el repositorio está en C:\\... y trabajas con PowerShell o herramientas nativas, instala en Windows. Si el repositorio y la toolchain ya viven en ~/code/... dentro de WSL2, entra en WSL y utiliza la ruta Linux. La guía oficial de WSL indica que WSL1 dejó de estar soportado desde Codex 0.115; en WSL2 conviene guardar el repositorio en el home Linux, no bajo /mnt/c, para reducir fricción de I/O y permisos.

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.

El documento oficial de autenticación separa dos propietarios: el acceso con ChatGPT sigue el plan y los permisos del workspace seleccionado; un API key factura el uso estándar en OpenAI Platform. No comparten saldo. Comprueba la ruta activa con codex login status. Si las credenciales se guardan en ~/.codex/auth.json, trata ese archivo como una contraseña y no lo subas al repositorio ni lo copies a un chat o ticket.

Empieza con un config.toml pequeño

La configuración de usuario vive en ~/.codex/config.toml. Un punto de partida prudente puede limitarse a permisos y búsqueda:

toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

workspace-write mantiene las escrituras ordinarias dentro del workspace y on-request conserva una aprobación cuando hace falta más acceso. No empieces con full access ni anulando el sandbox solo para evitar preguntas. Consulta la precedencia actual en Config basics y los campos en Configuration Reference.

En Windows nativo añade el sandbox preferido al nivel de usuario:

toml
[windows]
sandbox = "elevated"

La documentación del sandbox de Windows recomienda elevated, que configura usuarios restringidos, límites de archivos y reglas de firewall con aprobación administrativa. unelevated es un respaldo más débil cuando la política local o empresarial impide esa preparación.

Un repositorio de confianza puede tener .codex/config.toml para opciones propias del proyecto. Provider, auth, profile, notificaciones y telemetría son machine-local y se ignoran en esa capa. Para una prueba puntual, codex -c key=value prevalece solo en esa ejecución. Si un cambio no aparece, identifica usuario, CODEX_HOME, confianza del proyecto y override de CLI antes de borrar nada.

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. Antes del primer encargo, guarda la salida de git status --short y pide una explicación del proyecto sin modificar archivos. El resultado debe mencionar archivos reales y el segundo git status --short debe conservar el estado anterior.

La preparación completa exige además regresar a la CLI después del acceso y saber qué capa de configuración está activa. Anota plataforma, entorno native/WSL y método de instalación; ese dato reduce mucho el diagnóstico si una actualización cambia el ejecutable. Si fallan varias capas, el comando documentado codex doctor revisa instalación, configuración, autenticación, Git y runtime. Elimina rutas o secretos antes de compartir el informe.

Antes de repetir el proceso en otro equipo, vuelve a consultar las instrucciones oficiales vigentes. Si puedes identificar el ejecutable, el propietario de facturación, la configuración activa y el estado Git después de la primera tarea, la instalación y configuración inicial están completas. Si no, vuelve a la etapa concreta que falló y corrige solo esa capa.