Cómo instalar Codex CLI y ejecutar tu primera tarea

Codex CLI es un agente de programación para terminal de OpenAI, escrito en Rust. Se ejecuta localmente, trabaja con el código de tu repositorio y realiza tareas en un entorno aislado. Puedes instalarlo con el instalador independiente, npm, el cask de Homebrew o un binario de GitHub Releases.

Después de instalarlo, mantén separadas las dos vías de conexión: el inicio de sesión oficial de OpenAI mediante ChatGPT o una API Key de OpenAI, y un proveedor personalizado con tu propia API Key. Ambas usan el mismo comando codex; no necesitas instalar otro cliente.

Requisitos previos

Requisitos básicos del sistema según la guía oficial de instalación:

• macOS: 12 (Monterey) o posterior.
• Linux: Ubuntu 20.04+ / Debian 10+.
• Windows: Windows 11 mediante WSL2; Windows nativo tiene documentación propia.

Node.js es necesario solo si instalas mediante npm. El instalador independiente, el cask de Homebrew y el archivo de GitHub Releases proporcionan un ejecutable listo para usar.

El inicio de sesión oficial con ChatGPT requiere una cuenta de ChatGPT, mientras que el acceso oficial a la API necesita una clave de platform.openai.com. Un proveedor personalizado requiere tu propia cuenta de BetterToken, una API Key y un Model ID vigente. Node.js solo es necesario para la instalación con npm o para el script automático de configuración del proveedor.

Instala Codex CLI

macOS y Linux — instalador independiente

Es el método más sencillo y no requiere Node.js:

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

Cuando termine la instalación, comprueba el comando:

codex --version

Si aparece un número de versión, el comando está disponible.

¿Codex ya está instalado? Conecta tu API Key siguiendo la guía vigente. Consulta primero los Docs actuales y crea una cuenta de BetterToken si todavía no tienes tu propia clave.

macOS — cask de Homebrew

brew install --cask codex

npm — macOS, Linux y Windows

Necesitas Node.js y un npm funcional. Consulta la versión mínima de Node.js en el campo engines del paquete en npmjs.com/@openai/codex.

npm install -g @openai/codex

Si no se encuentra el comando codex después de instalarlo, el directorio global de npm no está en tu PATH. Averigua la ruta correcta:

npm config get prefix

Compara ese directorio con el PATH de tu shell y reinicia la terminal. No añadas /bin a ciegas: la ubicación de los ejecutables globales depende del sistema operativo y de cómo se instaló Node.js.

Linux — binario de GitHub Releases

En github.com/openai/codex/releases hay archivos de Linux listos para usar:

• codex-x86_64-unknown-linux-musl.tar.gz — para x86_64
• codex-aarch64-unknown-linux-musl.tar.gz — para arm64

Extrae el archivo, cambia el nombre del ejecutable a codex y colócalo en un directorio de tu PATH en el que puedas escribir.

Windows

Codex CLI puede ejecutarse de forma nativa en Windows o dentro de WSL2. La documentación actual de Windows recomienda Windows 11 para el uso nativo; una instalación de Windows 10 totalmente actualizada se admite con carácter de mejor esfuerzo.

Windows nativo (PowerShell). Instalador oficial:

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

Cuando se ejecuta de forma nativa, Codex aísla las tareas mediante Windows Sandbox. El modo se define en ~/.codex/config.toml:

[windows]
sandbox = "elevated"

• "elevated": recomendado; utiliza un usuario de sandbox dedicado y reglas de firewall.
• "unelevated": aplica restricciones ACL al usuario actual sin crear un usuario de sandbox específico.

WSL2. Instala la versión para Linux de Codex CLI dentro de WSL2 siguiendo las instrucciones de Linux. Para las herramientas de Linux, OpenAI recomienda guardar el proyecto en el sistema de archivos de WSL en vez de hacerlo bajo /mnt/.

Conecta el mismo Codex CLI a la API de BetterToken

BetterToken no sustituye Codex CLI por otra aplicación. El ejecutable oficial codex sigue funcionando, mientras que ~/.codex/config.toml selecciona un proveedor personalizado. Las solicitudes de Codex usan OpenAI Responses mediante la Base URL `https://www.bettertoken.ai/v1%60.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk

Paso 1 — crea tu cuenta y tu clave

Crea tu propia cuenta de BetterToken y una API Key exclusiva. No utilices una clave compartida ni copies una clave en un artículo, una captura de pantalla o un comando.

Paso 2 — copia la configuración vigente

Abre la guía actual de BetterToken para Codex, elige la superficie que utilizas y copia el Model ID y los campos del proveedor que muestra. Detén Codex por completo antes de modificar la configuración. El Model ID y los campos de autenticación son dinámicos: no los deduzcas de un ejemplo antiguo.

Paso 3 — limpia, aplica, reinicia y verifica

Elimina primero las variables antiguas de OpenAI que podrían prevalecer sobre config.toml.

macOS y Linux:

unset OPENAI_API_KEY
unset OPENAI_BASE_URL

Windows PowerShell:

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")

Configuración automática del proveedor BetterToken

El script configura únicamente el proveedor BetterToken; no instala Codex CLI. Requiere Node.js. Si no pasas una API Key ni un modelo como argumento, los solicita en una terminal interactiva, así que no pongas el secreto en la línea de comandos.

macOS y Linux:

curl -fsSL https://www.bettertoken.ai/install-codex-provider.sh?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk | bash

Windows PowerShell:

iwr https://www.bettertoken.ai/install-codex-provider.ps1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"

Los campos de autenticación y el almacenamiento de credenciales varían según la superficie de Codex y la versión del cliente. Por eso, este artículo no fija valores booleanos concretos para la autenticación ni mezcla el inicio de sesión oficial con un proveedor personalizado en un mismo ejemplo.

Aplica solo los campos indicados en los Docs actuales, transmite el secreto mediante el método documentado y reinicia Codex por completo. Después, ejecuta una tarea pequeña de solo lectura y comprueba en el Dashboard de BetterToken que la nueva solicitud, el modelo y el uso de tokens de entrada, salida y caché aparecen en el historial.

Autenticación oficial de OpenAI

Los siguientes comandos se aplican a la conexión oficial de OpenAI. Con el proveedor personalizado de BetterToken, codex login status no verifica la API de BetterToken; ejecuta una tarea de prueba y comprueba la respuesta.

Inicia sesión con ChatGPT

Ejecuta:

codex login

Se abrirá un navegador. Completa el inicio de sesión con tu cuenta de ChatGPT. Codex guarda la sesión localmente, por lo que no tendrás que volver a iniciar sesión en las siguientes ejecuciones.

Si ejecutas codex sin argumentos antes de autenticarte, la interfaz también te pedirá que inicies sesión. La forma principal de iniciar el proceso es codex login.

Inicia sesión con una API Key

No pases la clave como argumento ni la muestres con echo: su valor quedaría guardado en el historial del shell.

Define OPENAI_API_KEY en el entorno actual o mediante un gestor de secretos. No incluyas el valor en el artículo, el comando ni la salida. Cuando la variable esté definida, pásala por stdin:

printenv OPENAI_API_KEY | codex login --with-api-key

El valor de la clave no se muestra en pantalla ni entra en el historial de comandos.

Verifica la autenticación

Después de iniciar sesión, comprueba el estado:

codex login status

El comando muestra el método de autenticación actual o indica que no has iniciado sesión.

Si no aparece ninguna autenticación, repite el inicio de sesión con el método correspondiente.

Para cerrar la sesión y eliminar las credenciales guardadas:

codex logout

El archivo ~/.codex/auth.json contiene el token de acceso: trátalo como una contraseña. No lo borres manualmente; utiliza siempre codex logout para limpiarlo.

Documentación de autenticación: developers.openai.com/codex/auth. Referencia de subcomandos y opciones de inicio de sesión: developers.openai.com/codex/cli/reference.

Tu primera tarea en un repositorio de prueba

Empieza en un repositorio de prueba para no afectar al código de trabajo. Clona cualquier repositorio público, por ejemplo el propio Codex:

git clone https://github.com/openai/codex codex-test
cd codex-test

Ejecuta una tarea de solo lectura:

codex --sandbox read-only "Explain the entry point of this project"

La opción --sandbox read-only limita los comandos generados por el modelo a operaciones de lectura. Si Codex devuelve una descripción útil de la estructura sin modificar archivos, la primera ejecución ha terminado.

Para continuar en la TUI con la misma restricción, ejecuta:

codex --sandbox read-only

Escribe en la interfaz: What files are in this project and what does each do?

Si utilizas la conexión oficial de OpenAI, confirma que la autenticación sigue activa:

codex login status

Si utilizas el proveedor BetterToken, una respuesta normal confirma la conexión. También puedes abrir el Dashboard de BetterToken y comprobar que la solicitud, el modelo y el uso de tokens de entrada, salida y caché aparecen en el historial.

Solución de problemas

codex: command not found después de instalar con npm

Ejecuta npm config get prefix, compara el resultado con PATH y reinicia la terminal. La ruta exacta del ejecutable depende del sistema operativo y de cómo se instaló Node.js, así que no añadas /bin a ciegas.

El navegador no se abre al iniciar sesión con ChatGPT

En un servidor remoto sin interfaz gráfica, prueba primero el flujo oficial de código de dispositivo (beta):

codex login --device-auth

Antes debes habilitarlo en la configuración de seguridad de ChatGPT o en los permisos del Workspace. Si no está disponible, utiliza el inicio de sesión mediante API Key:

printenv OPENAI_API_KEY | codex login --with-api-key

La guía oficial de autenticación explica el callback, el código de dispositivo y las alternativas.

Codex no responde después de conectarlo a BetterToken

Comprueba cinco elementos: base_url es https://www.bettertoken.ai/v1%60,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-044&utm_content=ustanovit-codex-cli-pervyy-zapusk wire_apisigue siendoresponses, el Model ID, los campos del proveedor y la autenticación coinciden con la guía actual de la superficie elegida, y las variables antiguas OPENAI_API_KEYoOPENAI_BASE_URLno prevalecen sobre la configuración. Después de editarconfig.toml`, cierra Codex por completo y reinícialo en una terminal nueva.

codex login status muestra Not logged in

• Inicio de sesión con ChatGPT: vuelve a ejecutar codex login y completa el proceso en el navegador.
• Inicio de sesión mediante API Key: comprueba que OPENAI_API_KEY esté definida en el entorno de trabajo y repite printenv OPENAI_API_KEY | codex login --with-api-key.
• No borres ~/.codex/auth.json manualmente; utiliza codex logout.

---

Documentación de Codex CLI: developers.openai.com/codex/cli. Conecta el mismo Codex CLI a la API de BetterToken: docs.bettertoken.ai/en/ai-tools/codex.