CLI de OpenAI Codex: instalación, comandos, config.toml y codex exec

La CLI de OpenAI Codex es un agente de programación bajo licencia Apache-2.0 desarrollado por OpenAI que se ejecuta localmente en su terminal. Utilice codex de forma interactiva para explorar repositorios, modificar archivos, utilizar herramientas locales y revisar código, o ejecute codex exec de manera no interactiva en scripts y entornos de integración continua (CI). Lee ~/.codex/config.toml y los archivos .codex/config.toml del proyecto, carga instrucciones desde AGENTS.md y delimita la ejecución mediante entornos aislados (sandboxes) y políticas de aprobación.

Dónde encaja la CLI de Codex junto al resto de interfaces de OpenAI

OpenAI ofrece Codex a través de diversas modalidades complementarias:

• Codex CLI (codex): agente de programación local ligero en su terminal para trabajar sobre su repositorio y herramientas locales.
• Extensiones para IDE: disponibles para VS Code, Cursor y Windsurf. La CLI y las extensiones comparten los mismos niveles de configuración.
• Aplicación de escritorio (codex app): ejecute codex app o visite la sección Codex App en chatgpt.com.
• Codex Web (chatgpt.com/codex): agente en la nube. codex cloud permite examinar conversaciones en la nube, enviar tareas a un entorno configurado y aplicar los resultados en local.

Instalar y actualizar la CLI de OpenAI Codex

Instale la CLI de Codex mediante el script de instalación independiente, un gestor de paquetes o los binarios de GitHub Releases.

Instaladores independientes en macOS, Linux y Windows

En macOS o Linux, instale o actualice desde su shell:

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

En Windows, ejecute en PowerShell para instalar o actualizar:

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

Los instaladores descargan los paquetes desde https://releases.openai.com/codex y recurren a GitHub Releases si la descarga no estuviera disponible. Para forzar GitHub Releases, defina CODEX_INSTALLER_USE_RELEASES_OPENAI_COM como false (también son válidos 0 o no):

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

Gestores de paquetes y binarios de GitHub Releases

• npm: ejecute npm install -g @openai/codex para instalar.
• Homebrew: ejecute brew install --cask codex para instalar.
• GitHub Releases: descargue codex-aarch64-apple-darwin.tar.gz o codex-x86_64-apple-darwin.tar.gz (macOS), o bien codex-x86_64-unknown-linux-musl.tar.gz o codex-aarch64-unknown-linux-musl.tar.gz (Linux). Descomprima el ejecutable y cámbiele el nombre a codex.

Iniciar sesión y comenzar una tarea

Ejecute codex dentro de un repositorio Git. En el primer inicio, elija Sign in with ChatGPT (cuentas Plus, Pro, Business, Edu o Enterprise) o configure una clave de API. Genere puntos de control con Git antes y después de cada sesión para poder revertir cambios con total seguridad.

Comandos interactivos de la CLI y flujos en terminal

Gestione el contexto, las revisiones, las herramientas y los permisos desde su shell o en una sesión interactiva:

Dos flujos de trabajo integrados asisten en modificaciones de mayor envergadura:

• Revisión de código local: revisa cambios sin confirmar, un commit o una rama base e informa de hallazgos priorizados sin alterar su árbol de trabajo.
• Subagentes: delega investigaciones concretas en subagentes especializados y devuelve los resultados a la sesión principal.

Configurar Codex con config.toml

Codex almacena sus preferencias personales en ~/.codex/config.toml y las opciones del proyecto en .codex/config.toml (accesible también en la extensión del IDE pulsando el icono del engranaje en Codex Settings > Open config.toml).

Codex carga las capas .codex/ de proyecto (configuración, hooks y reglas) únicamente en proyectos de confianza; los repositorios no verificados utilizan exclusivamente la configuración del usuario y del sistema.

Prioridad de configuración

De mayor a menor prioridad:

• Opciones de la CLI y parámetros --config (-c)
• Archivos .codex/config.toml del proyecto, desde la raíz del repositorio hasta el directorio actual (el más cercano prevalece, solo en proyectos de confianza)
• Archivos de perfil mediante --profile profile-name (~/.codex/profile-name.config.toml)
• Configuración del usuario (~/.codex/config.toml)
• Valores de config.toml gestionados en la nube para el espacio de trabajo
• Configuración del sistema (/etc/codex/config.toml en Unix)
• Opciones predeterminadas integradas

En equipos corporativos administrados, las organizaciones pueden imponer restricciones con requirements.toml, como impedir approval_policy = "never" o sandbox_mode = "danger-full-access".

Opciones habituales y funciones en config.toml

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "none"

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

[features]
prefer_mxc = true

Opciones principales en config.toml:

• Modelo y razonamiento: model define el modelo predeterminado de la CLI y del IDE; model_reasoning_effort calibra la profundidad de razonamiento.
• Aprobaciones y aislamiento: approval_policy establece las confirmaciones para comandos (valores como "on-request" o "never"; "untrusted" ha sido retirado). sandbox_mode define límites en el sistema de archivos y la red (como "workspace-write"). También se admiten perfiles predefinidos (:read-only, :workspace, :danger-full-access) y tablas personalizadas [permissions.<name>].
• Búsqueda web: web_search se ajusta por defecto a "cached" (caché de OpenAI, reduciendo riesgos de inyección en prompts). Emplee "indexed" para limitar el acceso al índice de búsqueda, "live" para páginas en tiempo real (idéntico a --search, y opción por defecto en sandboxes de acceso total como --yolo), o "disabled".
• Estilo de comunicación: personality = "none" prescinde de la sección de prompt Personality predefinida manteniendo las instrucciones personalizadas (friendly, pragmatic y /personality han quedado obsoletos).
• Atajos de TUI y registros: [tui.keymap.global], [tui.keymap.composer] y [tui.keymap.chat] personalizan los atajos de teclado (una lista vacía elimina la asignación). log_dir especifica la carpeta de registros y activa codex-tui.log en texto plano.
• Entorno de shell: bajo [shell_environment_policy], ignore_default_excludes es true por defecto. Defina false para omitir variables con KEY, SECRET o TOKEN, o configure [shell_environment_policy.filters].
• Opciones avanzadas: [features] permite activar apps, goals, hooks, fast_mode, memories (desactivado por defecto), multi_agent, remote_plugin, shell_snapshot, shell_tool y unified_exec, o pasando codex --enable feature_name.

Incorporar instrucciones personalizadas con AGENTS.md

Codex procesa su cadena de instrucciones AGENTS.md una sola vez al comenzar la sesión:

• Instrucciones globales: en ~/.codex (o CODEX_HOME), Codex carga AGENTS.override.md en primer lugar, recurriendo a AGENTS.md si no existe.
• Instrucciones del proyecto y anidadas: recorriendo desde la raíz del proyecto (habitualmente la raíz de Git) hasta su directorio actual, Codex carga como máximo un archivo con contenido por carpeta: AGENTS.override.md, luego AGENTS.md y finalmente los indicados en project_doc_fallback_filenames.
• Orden de combinación y límite de tamaño: los archivos se concatenan desde la raíz hacia abajo para que las reglas más próximas prevalezcan, hasta un máximo de project_doc_max_bytes (32 KiB por defecto en config.toml).

Para auditar los archivos leídos, ejecute codex -c log_dir=./.codex-log y examine ./.codex-log/codex-tui.log.

Ejecutar scripts y pipelines de CI con codex exec

Ejecute Codex de forma no interactiva con codex exec:

codex exec "summarise the repository structure and list the top 5 risky areas"

Comportamientos esenciales de codex exec:

• Salida estándar y de errores: el progreso se transmite por stderr, mientras que únicamente el mensaje de cierre se imprime en stdout para facilitar pipes o guardado con -o <path> (--output-last-message <path>). Utilice --ephemeral para evitar guardar archivos de sesión en disco.
• Entrada por tubería (stdin): los datos recibidos sirven de contexto al combinarse con un prompt, o representan la instrucción íntegra si se omite el argumento o se pasa codex exec -.
• Aislamiento en sandbox: de forma predeterminada opera en modo solo lectura. Pase --sandbox workspace-write para modificar archivos, o --sandbox danger-full-access exclusivamente en entornos aislados controlados. (--full-auto está retirado; use --sandbox workspace-write, o --approve-for-me para aprobación automática con workspace-write.)
• Automatización limpia: --ignore-user-config omite $CODEX_HOME/config.toml, --ignore-rules ignora archivos .rules y --skip-git-repo-check prescinde del requisito de repositorio Git. Si un servidor MCP marcado con required = true no logra inicializarse, codex exec finaliza con código de error.
• Salida estructurada: --json emite eventos JSON Lines en tiempo real (thread.started, turn.started, item.*, turn.completed, turn.failed, error). --output-schema ./schema.json exige la validación mediante un esquema JSON.
• Reanudar tareas: ejecute codex exec resume --last "<prompt>" o codex exec resume <SESSION_ID> "<prompt>".
• Autenticación en CI: pase CODEX_API_KEY=<api-key> codex exec ... en la misma línea para una sola orden en lugar de como variable global en entornos que ejecutan código del repositorio, o emplee openai/codex-action@v1 en GitHub Actions, que levanta un proxy seguro para la clave de API.

Aislamiento en Windows: mxc, elevated y unelevated

En Windows, Codex puede ejecutarse de forma nativa en PowerShell utilizando un sandbox de Windows, prescindiendo de WSL o de máquinas virtuales. Se aconseja Windows 11. Windows 10 se admite de forma secundaria y requiere la versión 1809 o más reciente para ConPTY. Debe contarse con la herramienta winget.

En Codex CLI 0.162.0 o superior, evalúe la compatibilidad de mxc sin modificar su configuración:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK

Supervisar sesiones de Codex CLI en un teclado o teléfono con Orbtile

Al ejecutar múltiples terminales con codex, scripts con codex exec y conversaciones en la aplicación de escritorio, Orbtile presenta cada sesión en un Logitech MX Creative Keypad, un iPhone o un teléfono Android (Android 8.0 o superior con Orbtile Mobile), vinculado a macOS 14.0 Sonoma o posterior (Apple silicon) o Windows 11 (x64).

• Detección sin instalaciones adicionales: Orbtile lee directamente los archivos de hilos de Codex y sus señales nativas. Cada sesión de terminal codex, codex exec y aplicación de escritorio cuenta con su propia tecla o casilla indicando estado, herramientas en uso, tiempos de espera y texto del asistente.
• Colores y prioridades: las sesiones activas lucen en azul sereno y pasan a magenta-violeta cuando aguardan respuesta. Las sesiones en espera pasan al frente de manera automática, y la tecla 9 permite desplazarse a la primera de ellas.
• Aprobaciones desde el pad: en chats de escritorio compatibles, presione Deny o mantenga Allow (0,6 s) para confirmar comandos y responder preguntas de opción múltiple. Las sesiones en terminal con codex ofrecen Allow en las teclas (la cancelación se realiza en la terminal). Las ejecuciones con codex exec no solicitan confirmación de comandos (Codex 0.159.0), y otras esperas indican Answer on computer para que acuda al equipo.
• Hooks opcionales y SSH: para compactar el estado y recibir avisos con menor latencia, instale hooks opcionales en Settings > Agents > Codex y acéptelos en Codex bajo Settings > Hooks. Orbtile también supervisa sesiones remotas de la CLI de Codex vía SSH junto a Claude Code y ZCode. Consulte Sepa cuándo una tarea de Codex está esperando su atención y Watch Claude Code and Codex running on a remote server over SSH.