4. Instalación y configuración inicial

Objetivo del tema

Dejar el CLI instalado, comprobar que los binarios están disponibles en el PATH y completar el primer inicio de sesión para comenzar a trabajar con el agente.

4.1 Instalación vía npm

Si ya cuentas con Node.js, instalar el paquete global es la ruta más directa.

  1. Actualiza npm para evitar incompatibilidades:
    npm install -g npm
  2. Instala Codex CLI:
    npm install -g @openai/codex
  3. Verifica el binario:
    codex --version

versión actual de codex

Si usas administradores de versiones como nvm o fnm, recuerda que las instalaciones globales dependen de cada versión de Node. Crea alias o ejecuta el comando en las versiones que utilices con frecuencia.

4.2 Instalación con Homebrew

En macOS y distribuciones Linux compatibles, Homebrew distribuye un fórmula oficial.

brew update
brew install codex

Para actualizaciones posteriores utiliza brew upgrade codex. Si Homebrew instala el binario fuera de tu PATH, agrega la ruta indicada en el mensaje posterior a la instalación.

4.3 Descarga de binarios precompilados

Otra alternativa es descargar el ejecutable de la releases page. Cada publicación incluye artefactos para macOS (Intel y Apple Silicon) y Linux (x86_64 y arm64). Descomprime el archivo, coloca el binario en una carpeta del PATH y renómbralo a codex si es necesario.

4.4 Primer inicio y autenticación

Al ejecutar codex por primera vez, el programa abre la interfaz TUI y solicita autenticación.

  1. Selecciona la opción Sign in with ChatGPT y completa el proceso en el navegador.
  2. Si tu organización usa inicio de sesión corporativo, sigue las redirecciones SSO habituales.
  3. Una vez confirmado, regresa a la terminal. El CLI indicará que la sesión está activa.

Para entornos con facturación por uso, define CODEX_API_KEY antes de ejecutar el binario o configura el archivo ~/.codex/config.toml con la sección [profiles] que prefieras.

4.5 Comprobaciones esenciales

Antes de delegar trabajo al agente, revisa que los comandos fundamentales funcionen.

Comandos iniciales
Comando Propósito Señal de éxito
codex --version Confirma que el binario está instalado y en el PATH. Imprime la versión instalada sin errores.
codex --help Muestra las banderas disponibles para sesiones interactivas. Listado de opciones como --model, --cd, --sandbox.
codex exec --help Detalla los switches del modo automatizado. Incluye banderas como --json, --output-last-message y --full-auto.
codex resume --last Verifica que la autenticación permita retomar sesiones recientes. Abre la última conversación; si no existen, indica que no hay sesiones previas.
codex completion bash Genera scripts de autocompletado para integrarlo en tu shell. Produce instrucciones para cargar el autocompletado en tu configuración.

4.6 Solución de problemas frecuentes

  • Si la terminal no encuentra el comando, revisa el PATH. En macOS, agrega /usr/local/bin o /opt/homebrew/bin a tu shell.
  • En Windows, utiliza WSL2 cuando necesites compatibilidad con scripts POSIX o lanza PowerShell como administrador para la primera instalación global.
  • Cuando el inicio de sesión no abre el navegador, copia la URL que el CLI muestra en la terminal y pégala manualmente en el navegador de tu preferencia.
  • Si el binario queda dañado durante una actualización, reinstala con npm install -g @openai/codex@latest o brew reinstall codex.
  • Para restablecer credenciales, elimina ~/.codex/auth.json y repite el proceso de autenticación desde codex.

Conclusión: Tras instalar el binario, comprobar los comandos básicos y autenticar tu cuenta, Codex CLI queda listo para trabajar tanto en modo interactivo como automatizado. Los símbolos de verificación temprana evitan sorpresas cuando empieces a delegar tareas reales al agente.

Retornar