Codex CLI: la referencia técnica definitiva

TL;DR: Codex es un agente de programación que opera en múltiples superficies: lee tu base de código, ejecuta comandos en un sandbox a nivel del sistema operativo, modifica archivos y delega tareas en la nube. Domina cinco sistemas —config.toml, el modelo de sandbox y aprobaciones, AGENTS.md, MCP y skills— y se convertirá en un multiplicador de productividad. GPT-6-Astra es el nuevo modelo predeterminado recomendado (lanzado el 3 de septiembre de 2026; incluido como opción predeterminada de CLI desde la versión v0.153.4). OpenAI anunció que el despliegue había finalizado el 4 de septiembre (incluidas las cuentas Plus y Business esa misma tarde), pero el acceso todavía es desigual en la práctica. Por eso, las cuentas que aún no lo tengan habilitado deben fijar GPT-5.6 Sol (la opción «Power», con razonamiento medio) como alternativa estable; GPT-5.5, el modelo insignia de la generación anterior, ofrece un contexto de 400K en Codex y de 1M en API.^{83117145146148149} ¿Es tu primera vez aquí? Ve directamente a Instalación y Inicio rápido. ¿Estás siguiendo los lanzamientos? La versión estable más reciente es la v0.153.4 (4 de septiembre de 2026)¹⁴⁷¹⁴⁸. Consulta los Aspectos destacados de las versiones para conocer la evolución de las versiones recientes y el Registro de cambios para ver todas las actualizaciones.¹¹⁶

Codex funciona como un agente de programación que opera en múltiples superficies, no como un chatbot que escribe código. CLI lee tu base de código, ejecuta comandos en un sandbox, modifica archivos, se conecta con servicios externos mediante MCP y delega en la nube las tareas de larga duración. Se ejecuta localmente, pero piensa de forma global; la misma inteligencia impulsa cinco superficies distintas según tu forma de trabajar, incluida la extensión para navegadores (Chrome, Edge, Brave, Opera y Vivaldi), que ejecuta Codex en tu navegador sin tomar el control.⁹⁰¹²⁷

La diferencia entre usar Codex de manera ocasional y hacerlo con eficacia se reduce a cinco sistemas fundamentales. Domínalos y Codex se convertirá en un multiplicador de productividad:

1. Sistema de configuración: controla el comportamiento mediante config.toml
2. Modelo de sandbox y aprobaciones: regula lo que Codex puede hacer
3. AGENTS.md: define los acuerdos operativos del proyecto
4. Protocolo MCP: amplía las capacidades mediante servicios externos
5. Sistema de skills: agrupa conocimientos especializados y reutilizables

Pasé meses usando Codex junto con Claude Code en bases de código de producción, procesos de CI/CD y flujos de trabajo en equipo. Esta guía condensa esa experiencia en la referencia completa que me habría gustado tener cuando empecé. Cada función incluye la sintaxis exacta, ejemplos reales de configuración y los casos límite que causan problemas incluso a usuarios experimentados.

Puntos clave

• Cinco interfaces, un solo cerebro: CLI, la aplicación de escritorio, la extensión para IDE, las tareas en la nube y la extensión para navegadores (Chrome, Edge, Brave, Opera y Vivaldi) comparten la misma inteligencia GPT-5.x-Codex, así que elige la interfaz que mejor se adapte a tu flujo de trabajo.⁹⁰
• Aislamiento a nivel del sistema operativo: Codex aplica restricciones al sistema de archivos y a la red en el nivel del kernel (Seatbelt en macOS, Landlock + seccomp en Linux), no dentro de contenedores.
• AGENTS.md funciona con distintas herramientas: las instrucciones de tu proyecto funcionan en Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed y más de 60.000 proyectos de código abierto. Escríbelas una vez y úsalas en todas partes.
• Los perfiles reducen el costo de cambiar de contexto: define configuraciones preestablecidas con nombre (fast, careful, auto) y alterna entre ellas con --profile.
• La gestión del contexto es importante: la familia GPT-5.6 (Sol, Terra, Luna) admite una ventana de contexto de 272K; GPT-5.5, el modelo insignia de la generación anterior, ofrece 400K en Codex y 1M en la API. Usa /compact, instrucciones específicas y referencias @file para administrar de forma proactiva el presupuesto de tokens.⁸³¹¹²

Cómo usar esta guía

Esta es una referencia de más de 3.300 líneas; comienza por la sección que corresponda a tu nivel de experiencia:

La tarjeta de referencia rápida que aparece al final ofrece un resumen fácil de consultar de todos los comandos principales.

Aspectos destacados de las versiones: cambios recientes

Un recorrido versión por versión para quienes siguen el ciclo de lanzamientos de Codex. ¿Eres nuevo aquí? Omite esta sección y vuelve después de Inicio rápido: nada de lo que contiene es necesario para comenzar a trabajar de forma productiva.

GPT-6-Astra es el modelo recomendado de Codex: se lanzó el 3 de septiembre de 2026 mediante un despliegue gradual (primero para un conjunto limitado de organizaciones, comenzando por los socios del programa de ciberseguridad), que OpenAI anunció como prácticamente concluido al día siguiente. Una publicación de OpenAI en X (4 de septiembre) afirma que Astra «ya está disponible para todos los usuarios Pro, Enterprise y Business Premium en ChatGPT Work y Codex» y «activo en la API»; esa misma noche, Tibo Sottiaux, responsable de Codex, añadió que «Astra ya se ha desplegado también para todos los usuarios Plus y Business». En la práctica, el acceso todavía es desigual: informes de la comunidad del 5 de septiembre muestran cuentas Plus que solo ven modelos GPT-5.6 en Codex, y la documentación de modelos aún indica que la disponibilidad «depende del despliegue, el método de inicio de sesión y el cliente». Por eso, GPT-5.6 Sol (la configuración «Power», con razonamiento medio y ajustable hacia Smarter o Faster) sigue siendo la recomendación estable para las cuentas en las que Astra aún no responde; GPT-5.5 (23 de abril de 2026: contexto de 400K en Codex, 1M en la API, $5/$30 por MTok y 82,7 % en Terminal-Bench 2.0, SOTA) es el modelo insignia de la generación anterior.^{83117145146149} v0.153.3 y v0.153.4 (4 de septiembre de 2026) son parches estables publicados el mismo día que incorporan el lanzamiento de GPT-6-Astra a la CLI; la etiqueta npm latest ahora corresponde a 0.153.4. La comparación rust-v0.153.2…rust-v0.153.4 contiene exactamente cuatro PR más un incremento de versión. v0.153.3 (19:01 UTC): GPT-6-Astra se incorpora a los catálogos de Amazon Bedrock (#42805: las rutas globales y estadounidenses de Mantle y Runtime; GPT-5.6 Sol continúa siendo el modelo predeterminado de Bedrock), y se corrige la orientación sobre aclaraciones asíncronas de Astra (#42809, solo texto). v0.153.4 (23:25 UTC): la visibilidad del catálogo de modelos incluido cambia de oculto a visible y, gracias a la prioridad que GPT-6-Astra ya tenía en el catálogo, este se convierte en el modelo predeterminado incluido cuando no se configura uno explícitamente (#42874, la promoción visible para el usuario de la preparación que la línea 0.154.0-alpha incorporó como #42607), y la orientación sobre preguntas asíncronas queda condicionada por la disponibilidad de herramientas (#42878). Astra puede configurarse mediante la API desde v0.153.1 (-m gpt-6-astra) y aparece en el selector de modelos y como opción predeterminada incluida a partir de v0.153.4; no se documenta una versión mínima de la CLI, así que considera esas versiones como los mínimos efectivos. Advertencia operativa: en la CLI 0.153.4 y posteriores, una cuenta que todavía no forme parte del despliegue tendrá un modelo predeterminado incluido que nunca eligió, mientras que el modelo realmente servido dependerá de sus permisos de acceso; fija model = "gpt-5.6-sol" en config.toml (o pasa -m) para obtener una selección determinista durante el despliegue.^145146147148 v0.153.1 y v0.153.2 (3 de septiembre de 2026) son parches estables publicados el mismo día. El cambio principal de v0.153.1 no aparece en el cuerpo de su versión y solo puede demostrarse mediante la comparación rust-v0.153.0…rust-v0.153.1: la evaluación de uso de computadora de Guardian ahora respeta los requisitos del modelo. La evaluación de Guardian exclusiva para uso de computadora y las decisiones rápidas de aprobación solo se ejecutan cuando el modelo activo establece node_repl_auto_review_required; además, las evaluaciones anteriores o en curso se invalidan cuando un cambio de modelo omite la evaluación, de modo que volver a un modelo ya revisado no pueda reactivar una decisión de aprobación obsoleta. El cambio enumerado de v0.153.1 incorpora mediante backport una entrada de GPT-6-Astra en el catálogo de modelos, configurable únicamente mediante la API; en ese momento se trataba de preparación del catálogo, no de un lanzamiento: el modelo predeterminado y el selector de modelos permanecieron sin cambios hasta que v0.153.4 modificó el valor predeterminado incluido al día siguiente. v0.153.2 contiene una única corrección estética: cambia el texto descriptivo del nivel Fast de GPT-6-Astra de «1.5x» a «2x speed, increased usage»; es solo texto de la interfaz. Ninguno de los elementos observados en 0.154.0-alpha se incorpora en la comparación rust-v0.153.0…rust-v0.153.2; más allá de 0.153.0, la diferencia estable consta exactamente de estos tres cambios.¹⁴²¹⁴³ A partir de la CLI v0.153.0 (estable, 3 de septiembre de 2026), el modo Vim incorpora deshacer y rehacer: u deshace y Ctrl+R rehace borradores completos del editor, incluidos contenido pegado y archivos de imagen adjuntos, con pasos de edición agrupados y una acción de asignación de teclas configurable vim_normal.redo; la CLI de plugins puede enumerar, instalar y eliminar plugins de marketplaces remotos (las entradas de catálogos remotos aparecen en codex plugin list con su origen, versión, política de instalación y política de autenticación en la salida JSON); tui.auto_recap = false desactiva los resúmenes automáticos, pero mantiene disponible /recap de forma manual; y los planes Plus y Team reciben antes una advertencia sobre el límite de uso cuando queda menos de la mitad de la cuota en una ventana de uso de aproximadamente cinco horas (los demás planes conservan los umbrales existentes de 75/90/95 %). El alcance de Guardian ahora sigue el modo de aprobación: Full Access omite las revisiones de Guardian para acciones que solo requieren confirmación, y el modo User approval omite la evaluación y el precalentamiento de Guardian en segundo plano, mientras que las comprobaciones de acciones sensibles y las solicitudes de información al usuario conservan su comportamiento actual. Una nueva superficie de configuración features.context_management.experimental_mode (desactivada de forma predeterminada) habilita contexto con presupuesto de tokens, notas del historial y la herramienta new_context para sesiones de ChatGPT Plus, Pro y Pro Lite que cumplan los requisitos en el backend de Codex; siguen excluidas las sesiones con clave de API, los proveedores personalizados y los hilos estructurados temporales; además, tui.disable_paste_burst sustituye la clave de nivel superior (la ubicación anterior continúa funcionando como alternativa). Correcciones: las sesiones de TUI vuelven a conectarse después de que se interrumpa una conexión externa con app-server, conservando borradores y transcripciones; el historial de revisiones de Guardian sobrevive a la compactación, los reinicios y las bifurcaciones creadas por el usuario; las aprobaciones recordadas de herramientas de MCP quedan limitadas a la cuenta seleccionada de la aplicación y las rutas relativas de ejecutables de MCP se inician de forma más confiable en macOS; la compresión del despliegue incluye historiales compartidos; y los metadatos de hilos de app-server incorporan los campos anulables model y reasoningEffort, además de preguntas asíncronas estructuradas mediante request_user_input_async cuando el catálogo de modelos lo habilita.¹⁴⁰ A partir de la CLI v0.152.0 (estable, 1 de septiembre de 2026), se publica la lista completa de trece elementos observados en 0.152-alpha, con una reversión: update_plan llegó como función opcional, no activada de forma predeterminada. El estado final es #41744, «Make the update_plan tool opt-in»: tools.update_plan.enabled tiene false como valor predeterminado y, mientras la herramienta está desactivada, la orientación incluida sobre update_plan se elimina de los prompts del modelo, el modo de colaboración, multi-agent, la compactación, el precalentamiento y la continuación de objetivos (consulta Modo Plan y colaboración). El resto de la versión incluye: movimientos de búsqueda de Vim (búsqueda literal local al borrador mediante / y ?, con coincidencias resaltadas y navegación repetida con n/N, combinable con los operadores c/d/y; los borradores nuevos de Vim ahora comienzan en modo Insert), avisos procesables sobre límites de uso en la TUI (consultar uso, administrar créditos, restablecer límites y gestionar planes, filtrados según la cuenta autenticada), progreso de actualización de credenciales en la TUI y codex exec, incluida la reautenticación de Amazon Bedrock, nombres de servidores de MCP con formato de paquete (:, @, / y . ahora son válidos, por lo que nombres como npm:@modelcontextprotocol/server-sequential.thinking funcionan en los comandos de la CLI, los espacios de nombres de herramientas en tiempo de ejecución y la búsqueda de credenciales de OAuth), solicitudes de formulario openai/elicitation de MCP, output_token_limit por herramienta de MCP, con truncamiento uniforme al reanudar sesiones, credenciales de tareas en la nube restringidas a orígenes de confianza, con redirecciones desactivadas, tiempos de espera configurables para thread/shellCommand, incluidos plazos superiores a una hora, y presupuestos de tokens habilitados de forma predeterminada mediante los metadatos del modelo. v0.152.1 (1 de septiembre) es un parche estable con una única corrección: la revisión de aprobaciones de Guardian obtiene su política de Node REPL de los metadatos del modelo.¹³⁸¹³⁹ A partir de la CLI v0.151.0 (estable, 29 de agosto de 2026), se publica la lista completa de elementos observados durante el ciclo 0.150-alpha; el cuerpo de la versión NO representa la versión completa: solo enumera los PR posteriores al corte de la rama, #41183-#41209, mientras que la comparación rust-v0.150.1…rust-v0.151.0 contiene 164 commits sin ninguna reversión (la versión estable queda un commit por detrás de 0.151.0-alpha.6, y ese único commit es el incremento de versión propio de la alpha). Se incorporaron los diez elementos observados: /recap resume la conversación actual cuando se solicita, y Codex genera automáticamente el mismo resumen para conversaciones elegibles que estén inactivas y sin foco; los hosts del modo de código eliminan el transporte WebSocket (solo quedan stdio y gRPC; WebSocket sobrevive exclusivamente como flujo opcional de trazas OTLP sin procesar); los hilos duraderos usan de forma predeterminada el historial paginado cuando su almacenamiento admite las APIs paginadas (los hilos efímeros y los almacenamientos incompatibles conservan el comportamiento anterior); llega el esfuerzo de razonamiento persistent, con herramientas de reloj y orientación proactiva incluida; los valores predeterminados de Guardian v2 pasan a usar revisiones de uso de computadora con imágenes; Vim incorpora los movimientos de búsqueda hasta el carácter f/F/t/T, además de los saltos de búfer gg/G; app server acepta actualizaciones de configuración en vivo limitadas al turno, incluida una anulación del nivel de servicio por turno; se incorporan un analizador de configuración de worktrees y metadatos de propiedad del hilo para worktrees administrados; la configuración de Amazon Bedrock se incorpora al proceso de incorporación de la TUI (protegida por una función experimental); y la entrada enviada a terminales con privilegios elevados puede exigir una aprobación nueva (write_stdin_approval, desactivada de forma predeterminada, con un límite de 8.000 bytes para la entrada revisada). Entre las incorporaciones propias de la versión se encuentran un periodo de gracia configurable para descubrir herramientas de servidores opcionales de MCP (mcp_optional_startup_grace_ms, 1.000 ms de forma predeterminada), la posibilidad de que las extensiones inspeccionen o sustituyan los resultados de herramientas de MCP antes de que lleguen al modelo y catálogos de plugins que combinan la configuración de cada repositorio, al tiempo que informan sobre marketplaces de proyecto no válidos sin ocultar los plugins válidos. Las correcciones mantienen la disponibilidad de herramientas y el esfuerzo de razonamiento correctos al cambiar de modelo o recurrir a alternativas, mejoran la aplicación remota del sandbox mediante el directorio de inicio, el sistema operativo y las convenciones de rutas reales del ejecutor, contabilizan el uso de tokens de subagentes anidados en los presupuestos de objetivos raíz, impiden que clasificaciones obsoletas de Guardian autoricen acciones después de cambiar los permisos y evitan que /cd debilite las restricciones del sandbox al conservar los perfiles de permisos restaurados.¹³⁴¹³⁵ A partir de la CLI v0.150.0 (estable, 26 de agosto de 2026), hooks incorpora un evento Interrupt —la duodécima entrada de HOOK_EVENT_NAMES, que ejecuta comandos o controladores de MCP cuando se interrumpe un turno activo de nivel superior (tiempo de espera predeterminado de 1 segundo, máximo de 3 segundos y nunca para subagentes)—; /copy abre un selector que abarca la respuesta completa, bloques de código individuales y citas en bloque; las tareas pueden referenciarse desde la terminal (menciona otras tareas de Codex con @, permite que los agentes lean, creen o envíen mensajes a tareas y obtén títulos descriptivos automáticos para tareas sin nombre, con /rename sugiriendo uno editable); los enlaces Markdown se muestran como etiquetas en las que se puede hacer clic en terminales compatibles; los atajos pueden alternar entre modos de permisos y el modo Vim incorpora la repetición con .; y los proyectos que no son de confianza dejan de proporcionar instrucciones de AGENTS.md a nivel de proyecto. features.network_proxy.credential_broker y review_scope.computer_use_only de Guardian v2 se incorporan como superficies configurables y desactivadas de forma predeterminada (v0.151.0 activó posteriormente los valores predeterminados de Guardian v2). La versión también corrige la ocultación de credenciales de app-server, la búsqueda remota de tokens de portador y el inicio de servidores obligatorios de MCP, el sandbox elevado de Windows con rutas de usuario Unicode, los bloqueos al apagar Unix provocados por procesos desvinculados y la compatibilidad de Amazon Bedrock con la compactación y multi-agent.¹³² v0.150.1 (27 de agosto) es un parche con una única corrección (la etiqueta npm latest hasta v0.151.0): la compactación remota ahora contabiliza de forma predeterminada las imágenes conservadas dentro de su presupuesto de tokens y elimina las más antiguas cuando es necesario; el valor predeterminado de 0.151-alpha (#40994) se incorporó mediante backport a la versión estable (#41003).¹³³ A partir de la CLI v0.149.0 (estable, 20 de agosto de 2026), se retira la política de aprobación untrusted —las configuraciones que todavía la mencionen deben migrar a on-request— y la versión incorpora como publicadas todas las funciones de la lista de seguimiento alpha: un panel interactivo codex agents (buscar, iniciar, abrir, renombrar y detener tareas, con atajos configurables); /cd, /pwd y /cwd para administrar el directorio de trabajo dentro de las sesiones de la TUI; codex queue para enviar mensajes a sesiones locales o remotas existentes; más movimientos de cambio de Vim (cw, c$, cc y sustitución de caracteres); un codex doctor que ahora diagnostica la protección de endpoints, fallos de red o proxy, el estado de la aplicación de escritorio y la conectividad de actualizaciones; y esfuerzos de razonamiento max/ultra en las SDKs, con anulaciones exactas en la configuración de la CLI. Los hilos reanudados y bifurcados también restauran su perfil de permisos activo en vez de volver silenciosamente a los valores predeterminados. v0.149.1 (24 de agosto) es un parche estable de cinco commits que incorpora codex exec --thread-source <SOURCE> (clasifica los hilos recién creados o bifurcados como user, subagent, memory_consolidation o con el nombre de una función; usa user si se omite; threadSource en las SDK de TypeScript), junto con backports de compactación de imágenes en sesiones remotas y consolidación de memoria; fue la etiqueta npm latest hasta v0.150.1.¹²⁰¹²⁶ Por otra parte, OpenAI redujo el precio de GPT-5.6 Sol más de un 20 % durante tres meses a partir del 21 de agosto (al menos hasta el 21 de noviembre de 2026): disminuyen tanto los precios de la API como el consumo de créditos de Codex; la tabla publicada de tarifas por créditos ahora indica 100 créditos por 1M de tokens de entrada para Sol (10 en caché y 500 de salida), frente a 125/12,5/750.¹²¹ A partir de la CLI v0.148.0 (estable, 18 de agosto de 2026), las conversaciones completas de la TUI pueden exportarse a Markdown con /export (al portapapeles o a un archivo nuevo); codex exec fork bifurca sesiones desde la línea de comandos, con opciones de archivar y restaurar en el selector de reanudación de la TUI; /status, las líneas de estado y los títulos de terminal muestran los créditos o el costo estimados del hilo en espacios de trabajo elegibles; Amazon Bedrock Runtime se convierte en un proveedor integrado (compatibilidad con perfiles y regiones de AWS, y enrutamiento de GPT-5.6); hooks puede ejecutar comandos de forma asíncrona e invocar herramientas de MCP; y las restricciones del sandbox ahora se cierran ante fallos en rutas denegadas o ilegibles tanto en Linux como en Windows. La TUI también acepta prompts redactados mientras se inicializa.¹¹⁸ A partir de la CLI v0.147.0 (estable, 7 de agosto de 2026), se elimina codex exec --full-auto (obsoleto desde v0.128): los scripts que todavía lo pasen ahora producirán un error; sustitúyelo por --sandbox workspace-write junto con una opción de aprobación o un perfil. v0.147.0 también incorpora --approve-for-me (los prompts de aprobación se resuelven mediante una revisión automática), Agent Plugins portátiles con búsqueda en catálogos locales, personales, del espacio de trabajo y remotos, el protocolo opcional MCP 2026-07-28 (descubrimiento paginado, solicitudes de varias rondas e inicio no bloqueante de servidores) y secciones de conversación para organizar transcripciones extensas.¹¹⁶ v0.146.0 (estable, 29 de julio) hizo que los proxies configurados abarcaran todas las capas de transporte, añadió manifiestos de Agent Plugins junto con los marketplaces de Amazon Bedrock y Claude Code, nombres de sesión con fijación de hilos y skills proporcionadas por el ejecutor; v0.146.1 (5 de agosto) reforzó los valores predeterminados de revisión automática para modelos con capacidades cibernéticas.¹¹⁴¹¹⁵ A partir de la CLI v0.145.0 (estable, 21 de julio de 2026), /import permite migrar desde Cursor además de Claude Code —configuración, servidores de MCP, plugins, sesiones, comandos y memorias limitadas al proyecto—; la voz regresa como conversaciones V3 en tiempo real y por streaming, con entradas de audio y salidas de audio de herramientas en formatos locales habituales; la experiencia opcional multi-agent v2 se estabiliza, con modelos, niveles de razonamiento y concurrencia configurables para los subagentes; un historial experimental paginado de hilos permite reanudar y buscar con eficiencia, conservar nombres y admitir subagentes y memorias; se publica el inicio de sesión experimental de Amazon Bedrock, con compatibilidad para endpoints y autenticación personalizados (GPT-5.6 Sol es el modelo predeterminado de Bedrock); y las selecciones incluidas de modelos GPT-5.4 migran a las variantes GPT-5.6 Terra y Luna. v0.144.6 (18 de julio) corrigió las ventanas de contexto de GPT-5.6 Sol/Terra/Luna a 272.000 tokens.¹¹¹¹¹² A partir de la CLI v0.140.0 (estable, 15 de junio de 2026), /usage muestra la actividad diaria, semanal y acumulada de tokens de la cuenta; las sesiones pueden eliminarse permanentemente mediante codex delete / /delete (con medidas de confirmación); /import migra de forma selectiva la configuración inicial, la configuración del proyecto y los chats recientes desde Claude Code; escribir @ abre de forma predeterminada un menú unificado de menciones para archivos, plugins y skills; y se incorpora la autenticación administrada de Amazon Bedrock mediante clave de API, junto con almacenamiento local cifrado para las credenciales de OAuth de la CLI y MCP. Los controles experimentales de voz /realtime se eliminaron de la TUI (la voz regresó después en v0.145.0 como streaming en tiempo real V3).¹⁰²¹¹² A partir de la CLI v0.139.0 (estable, 9 de junio de 2026), el modo de código puede invocar directamente la búsqueda web independiente (incluso desde llamadas anidadas de herramientas de JavaScript) y recibir resultados en texto sin formato; los esquemas de entrada de herramientas y conectores ahora conservan las estructuras oneOf/allOf para mejorar la compatibilidad con esquemas grandes y MCP; codex doctor incorpora detalles del entorno del editor y el paginador (ocultando los valores sensibles en JSON); y el marketplace de plugins muestra los orígenes en codex plugin marketplace list --json, con una enumeración más rápida mediante catálogos almacenados en caché.¹⁵⁵ v0.138.0 (8 de junio) añadió /app para transferir una sesión de la CLI a la aplicación de escritorio en macOS y Windows, expuso al modelo las rutas de imágenes locales, flexibilizó la selección del esfuerzo de razonamiento y proporcionó a la automatización de plugins una salida JSON estructurada. También comenzó a cifrar el texto de las tareas enviadas del agente principal a los subagentes en multi-agent v2, por lo que las instrucciones de delegación dejaron de aparecer como texto sin formato en los registros de sesiones locales (consulta Multi-Agent).¹⁵⁶¹⁰⁸ v0.137.0 (4 de junio) publicó multi-agent v2 (tiempo de ejecución conservado por hilo, valores predeterminados más limpios para seguimientos y metadatos, y hide_spawn_agent_metadata establecido en true de forma predeterminada), combinaciones de teclas F13–F24 para la TUI y una extensión v1 de skills con resolución del catálogo en cada turno.¹⁵⁷ A partir de la CLI v0.135.0 (28 de mayo de 2026), codex doctor informa un inventario más completo del entorno, Git, la terminal, app-server y los hilos; /status muestra detalles de la conexión remota y la versión del servidor cuando la TUI está conectada mediante un servicio remoto; el modo vim incorporó edición de objetos de texto, mejoró el comportamiento de las palabras y los finales de línea y añadió una interrupción de turno configurable; /permissions ahora reconoce perfiles de permisos con nombre y muestra los personalizados; las compilaciones empaquetadas de Codex detectan y utilizan el auxiliar parcheado de zsh incluido en las versiones compatibles de macOS; y las SDK de Python exponen ajustes predefinidos de Sandbox fáciles de usar para las APIs de hilos y turnos.¹⁵⁹ v0.134.0 (26 de mayo de 2026) introdujo la búsqueda en el historial de conversaciones locales, con coincidencias de contenido sin distinción entre mayúsculas y minúsculas y vistas previas de resultados; convirtió --profile en el selector principal de perfiles para la CLI, los permisos de la TUI y los flujos del sandbox (las configuraciones de perfiles heredadas se rechazan con orientación para migrarlas); mejoró la configuración de MCP mediante selección de entorno por servidor y opciones de OAuth para servidores HTTP transmisibles; aumentó la confiabilidad de los esquemas de herramientas de conectores conservando $ref/$defs locales y compactando esquemas excesivamente grandes; permitió que las herramientas de solo lectura de MCP se ejecutaran de forma concurrente cuando anuncian readOnlyHint; e incorporó más contexto para extensiones y hooks, incluido el historial de conversaciones para las herramientas de extensiones.¹⁰¹ v0.133.0 (21 de mayo de 2026) habilitó los objetivos de forma predeterminada con almacenamiento y seguimiento del progreso dedicados; codex remote-control incorporó preparación y estado en primer plano, además de inicio y detención al estilo de un daemon; los perfiles de permisos añadieron APIs de enumeración, herencia, requirements.toml administrado, actualización en tiempo de ejecución y una integración más sólida con el sandbox de Windows; el descubrimiento de plugins muestra las versiones instaladas, las raíces de marketplaces y las colecciones remotas; y las extensiones pueden observar el inicio y la detención de subagentes, la ejecución de herramientas, los metadatos de turnos y el procesamiento asíncrono de aprobaciones y turnos. La actualización del 21 de mayo de la aplicación Codex añadió Appshots para las ventanas de Mac en primer plano, disponibilidad general del modo Goal en la aplicación, el IDE y la CLI, mejoras en las anotaciones del navegador integrado y Computer Use bloqueado opcionalmente para usuarios de Mac elegibles.⁹⁹¹⁰⁰ v0.132.0 (20 de mayo de 2026) incorporó autenticación de primera clase para las SDK de Python, APIs de turnos más simples y exclusivamente textuales, un TurnResult más completo, codex exec resume --output-schema, un inicio más rápido de la TUI, registro de ejecutores remotos respaldado por autenticación y conservación de la fidelidad de imágenes en los turnos de app-server. Usa opciones explícitas de sandbox y aprobación o perfiles de permisos: el antiguo --full-auto se eliminó a partir de v0.147.0; js_repl sigue eliminado.^{86878991969798116}

Nota de estabilidad: Las funciones marcadas como [EXPERIMENTAL] o under development pueden cambiar entre versiones. A partir de v0.133.0 (21 de mayo de 2026), los objetivos están habilitados de forma predeterminada, los perfiles de permisos son una superficie administrada de primera clase, el descubrimiento de plugins ofrece mayor visibilidad y remote-control puede ejecutarse con más facilidad como comando de app-server en primer plano o como daemon. Codex Cloud y el modo de código siguen siendo experimentales o están en desarrollo, mientras que la CLI principal, el sandbox, AGENTS.md, config.toml, Skills, hooks, las herramientas multi-agent, los plugins, Browser, Computer Use y Appshots son superficies estables o documentadas para el usuario según la plataforma y el plan. v0.132.0 completa la autenticación de las SDK de Python y la automatización estructurada de reanudación; v0.131.0 añadió codex doctor, búsqueda unificada de menciones con @, comandos de la CLI para marketplaces, uso compartido de plugins que tiene en cuenta la versión, remote-control administrado por un daemon con activación y desactivación en tiempo de ejecución, entornos respaldados por un registro y más refuerzos para el sandbox de Windows.⁹⁶⁹⁷⁹⁸ El antiguo --full-auto se eliminó en v0.147.0 (estaba obsoleto desde v0.128) y js_repl sigue eliminado.^8687116 La lista de seguimiento alpha de 0.149.0 se publicó en la versión estable v0.149.0 (20 de agosto de 2026): se retiró la política de aprobación untrusted, codex agents pasó a ser un verdadero comando de panel, codex doctor abarca la protección de endpoints y los diagnósticos de red, escritorio y actualizaciones, y las SDKs exponen los esfuerzos de razonamiento max/ultra.¹²⁰ La lista de seguimiento alpha de 0.150.0 se dividió al publicarse: de los nueve elementos observados, cinco llegaron a la versión estable v0.150.0 (26 de agosto de 2026) —el evento de hook Interrupt, el selector /copy, la omisión de AGENTS.md en proyectos que no son de confianza, features.network_proxy.credential_broker y el alcance de revisión review_scope.computer_use_only de Guardian v2 (una superficie configurable; el valor predeterminado resuelto continúa siendo el alcance estándar)— y cinco pasaron a la línea 0.151.0-alpha: /recap con generación automática de resúmenes, la eliminación de WebSocket del modo de código (los endpoints ws:// todavía funcionan en 0.150.0), el historial paginado de hilos como valor predeterminado para hilos duraderos (ThreadHistoryMode todavía tiene legacy como valor predeterminado en 0.150.0), el esfuerzo de razonamiento persistent y Guardian v2 configurado de forma predeterminada para revisar el uso de computadora con imágenes (transcript.include_images tiene false como valor predeterminado en 0.150.0). La contabilización de imágenes conservadas en el presupuesto de compactación se puso al día de inmediato: el valor predeterminado de la alpha (#40994) llegó a la versión estable mediante el backport de 0.150.1 (#41003).¹³²¹³³ Esa lista de seguimiento de 0.151.0-alpha se resolvió limpiamente: los diez elementos llegaron a la versión estable v0.151.0 (29 de agosto de 2026) sin ninguna reversión, algo que solo puede demostrarse mediante la comparación rust-v0.150.1…rust-v0.151.0 (164 commits), porque el cuerpo de la versión solo enumera los PR posteriores al corte de la rama, #41183-#41209.^137134135 La lista de seguimiento de 0.152.0-alpha que vino después (¹³⁶) se resolvió como una promoción completa con una reversión: los trece elementos llegaron a la versión estable v0.152.0 (1 de septiembre de 2026), pero update_plan se publicó como función opcional en lugar de estar habilitada de forma predeterminada. El cambio de comportamiento observado (el estado habilitado de forma predeterminada de #41630) fue revertido mediante #41744, «Make the update_plan tool opt-in», antes del corte de la rama; por ello, tools.update_plan.enabled tiene false como valor predeterminado y la salvedad de la nota de seguimiento anterior («un cambio de comportamiento si llega a la versión estable») se resolvió sin cambios en el valor predeterminado.¹³⁶¹³⁸ La versión estable v0.153.0 (3 de septiembre de 2026) llegó dos días después, y los parches del mismo día v0.153.1 y v0.153.2 incorporaron una corrección de los requisitos del modelo de Guardian, un backport de GPT-6-Astra al catálogo y una corrección estética de la descripción; la comparación rust-v0.153.0…rust-v0.153.2 no promueve ninguno de los elementos observados en la alpha.^140142143 Después, los parches estables v0.153.3 y v0.153.4 (4 de septiembre de 2026; npm latest = 0.153.4) incorporaron el lanzamiento de GPT-6-Astra: la comparación rust-v0.153.2…rust-v0.153.4 consta exactamente de cuatro PR más un incremento de versión, y resuelve dos elementos observados como promovidos mediante backports de correcciones urgentes en la línea 0.153, no mediante el ciclo 0.154: el catálogo incluido de GPT-6-Astra (#42607, promovido como el cambio de oculto a visible de #42874 en v0.153.4, que convierte a Astra en el modelo predeterminado incluido) y los catálogos de Amazon Bedrock (#42619, promovidos como #42805 en v0.153.3).¹⁴⁷¹⁴⁸ Nota de análisis: developers.openai.com/codex/ ahora redirige mediante 308 a learn.chatgpt.com/docs/; considera learn.chatgpt.com el host canónico de la documentación de Codex en futuros análisis.¹⁴⁶ La siguiente versión en el ciclo es la línea 0.154.0-alpha, que avanzó hasta 0.154.0-alpha.6 (publicada el 7 de septiembre de 2026; existen las etiquetas intermedias alpha.4 y alpha.5 sin versiones publicadas; la dist-tag alpha de npm corresponde a 0.154.0-alpha.6) y es una versión preliminar. Nada de ella se documentará en el cuerpo de esta guía hasta que llegue a la versión estable, y los cuerpos de las versiones de esta línea alpha son marcadores vacíos, así que las comparaciones constituyen la única fuente: la comparación rust-v0.154.0-alpha.3…rust-v0.154.0-alpha.6 contiene 147 commits. Elementos observados que avanzaron en esa diferencia: la creación de worktrees administrados (#42196) se amplió hasta convertirse en una superficie completa de worktrees (compatibilidad con exec, #42652; sesiones interactivas y bifurcaciones, #43069; comandos de sesión en la TUI, #43120; worktrees vinculados en el descubrimiento, #43279; un explorador de worktrees en la TUI, #43286; aplazamiento de transiciones, #43298); los mensajes asíncronos de formato libre del usuario (#42354) crecieron hasta formar un conjunto completo en la TUI (#42677, #42889, #42891, #42894, #42897, #42903); el runtime nativo de voz experimentó una actividad intensa (inicialización de GStreamer, #42631; negociación de WebRTC, #42676; audio local opcional, #43079; RTP del micrófono, #43090; una API de sesión en tiempo real, #43097; exportación de SDK, #43099; RTP Opus acotado, #43100; reproducción, #43244 y #43248; una cadena de herramientas Bazel, #43083-#43144); continuó el conjunto de aprovisionamiento del sandbox de Windows (#42801, #42833, #42835; un adaptador MXC nativo, #42841; cierre de sockets, #43308); la configuración de razonamiento duradero incorporó trabajo adyacente protegido por funciones experimentales (#43110); y las preferencias de la TUI recibieron trabajo relacionado (#42791, #42674). Sin avances: el modo de sustitución de Vim (#42194), el estado en vivo de compactación del contexto (#42319) y la corrección de confianza del espacio de trabajo para los auxiliares de PATH (#42324); los elementos de seguridad, refuerzo y contexto de Guardian de alpha.3 siguen bajo observación como se registró en ¹⁴⁴. Nuevos elementos observados en la diferencia de alpha.6: el comando obsoleto codex mcp-server se elimina en la línea alpha (#42993), un cambio incompatible con esta guía, que documenta el comando como obsoleto pero funcional; si la eliminación llega a la versión estable 0.154.0, se convierte en una eliminación documentada, por lo que debe verificarse de nuevo antes de promoverla; una revisión profunda de Guardian v2 de aproximadamente 25 commits (políticas de revisión proporcionadas por el modelo, #42744; aprobaciones limitadas a la solicitud, #42807; identificadores de respuestas superiores en sustitución de tickets, #43002; motivos de fallos y tiempos, #43005; contexto del hilo trasladado a la configuración de guardianv2, #43104; un modo de contexto centralizado, #43458; eliminación de las rutas heredadas de revisión de aprobaciones de Guardian, #43462; rechazo de aprobaciones obsoletas, #43442); mejoras de Astra en la TUI (selector de modelos, #42879; destello, #42842; orientación para la entrada, #42824 y #42836; valores predeterminados de modelos proporcionados por el servidor para inicios nuevos y sesiones en segundo plano, #43177 y #43261; una advertencia de anulación, #42639); verificación experimental del usuario de MCP (#43265, #43289, #43352); perfiles de permisos remotos (selección por nombre en la TUI, #43340; conservación al reanudar y bifurcar, #43330); administración experimental del contexto protegida por la capacidad del modelo al iniciar la sesión (#43147, la misma superficie features.context_management); y un concepto de elegibilidad para «Daybreak» ausente de toda la documentación de OpenAI al momento de escribir este texto (avisos de rechazo cibernético en la TUI adaptados a la elegibilidad para Daybreak, #42667; preferencias de Daybreak conservadas en los metadatos del hilo, #42854), que constituye por sí mismo un elemento de seguimiento. Elementos menores: ampliación de /copy (#43055), jemalloc en compilaciones musl (#42850) y una vista de solo lectura al reanudar un hilo que tiene un proceso de escritura activo (#43253). Las comparaciones alpha se superponen con incorporaciones selectivas a la versión estable, por lo que cada elemento observado debe volver a verificarse frente a la comparación estable cuando se promueva.^141144150

Cómo funciona Codex: el modelo mental

Antes de profundizar en las funciones, debes entender cómo la arquitectura de Codex determina todo lo que haces con él. El sistema opera en cinco superficies respaldadas por una capa de inteligencia compartida:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (on-request → never)       │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions             │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                             │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens         │
└─────────────────────────────────────────────────────────┘

Capa central: La familia de modelos GPT lo impulsa todo. A septiembre de 2026, gpt-6-astra es el modelo recomendado (su despliegue se anunció como completado el 4 de septiembre, aunque en la práctica el acceso sigue siendo desigual; es el modelo predeterminado incluido en CLI 0.153.4+ cuando no se configura uno explícitamente), con gpt-5.6-sol —la opción «Power», con razonamiento medio— como alternativa estable, junto con Terra (uso cotidiano) y Luna (rápido y asequible); gpt-5.5 es el modelo insignia de la generación anterior (contexto de 400K en Codex y de 1M en API), y gpt-5.4 dejará de estar disponible en Codex el 31 de agosto de 2026.^{83117146148149} Lee archivos, escribe parches, ejecuta comandos de shell y razona sobre tu base de código. Cuando el contexto se llena, Codex compacta la conversación para liberar espacio. Esta capa consume tokens.

Capa de seguridad: Cada comando que ejecuta Codex pasa por un entorno aislado a nivel del sistema operativo. En macOS, el framework Seatbelt de Apple aplica restricciones a nivel del kernel. En Linux, Landlock + seccomp filtran el acceso al sistema de archivos y a las llamadas al sistema. El entorno aislado opera a nivel del kernel, no dentro de contenedores. Después, la política de aprobación determina cuándo solicitar confirmación humana.

Capa de extensiones: MCP conecta servicios externos (GitHub, Figma, Sentry). Los skills agrupan flujos de trabajo reutilizables que Codex carga cuando los necesita. Las Apps se conectan con conectores de ChatGPT. La búsqueda web incorpora contexto de internet en tiempo real.

Capa de superficies: CLI para usuarios avanzados de terminal y automatización. La aplicación de escritorio para gestionar proyectos en varios hilos. La extensión del IDE para ciclos de edición, compilación y pruebas. Cloud para tareas asíncronas que se ejecutan de forma independiente.

La idea clave: La mayoría de los usuarios solo utiliza una superficie. Los usuarios avanzados usan las cinco: Cloud para tareas de larga duración, CLI para operaciones deterministas en repositorios, la extensión del IDE para ciclos de programación rápidos, la aplicación de escritorio para planificación y coordinación, y la extensión del navegador para flujos de trabajo en el navegador con sesión iniciada.

Tabla de contenido

1. ¿Cómo instalo Codex?
2. Inicio rápido: tu primera sesión
3. Superficies principales de interacción
4. Análisis detallado del sistema de configuración
5. ¿Qué modelo debería elegir?
6. ¿Cuánto cuesta Codex?
7. Marcos para tomar decisiones
8. ¿Cómo funciona el sistema de entorno aislado y aprobaciones?
9. ¿Cómo funciona AGENTS.md?
10. Hooks
11. ¿Qué es MCP (Model Context Protocol)?
12. Code Mode
13. Entorno de ejecución REPL de JavaScript
14. ¿Qué son los skills?
15. Plugins
16. Plan Mode y colaboración
17. Sistema de memoria
18. Gestión de sesiones
19. Modo no interactivo (codex exec)
20. Codex Cloud y tareas en segundo plano
21. La aplicación de escritorio de Codex
22. GitHub Action y CI/CD
23. Codex SDK
24. Optimización del rendimiento
25. ¿Cómo depuro problemas? — incluido codex doctor
26. Implementación empresarial
27. Prácticas recomendadas y antipatrones
28. Recetas de flujos de trabajo
29. Guía de migración
30. Tarjeta de referencia rápida
31. Registro de cambios
32. Referencias

¿Cómo instalo Codex?

Gestores de paquetes

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

¿Cómo actualizo, revierto a una versión anterior o desinstalo la CLI de Codex?

Codex incluye un comando de actualización automática desde la versión v0.128.0; todo lo demás se gestiona mediante el gestor de paquetes con el que se instaló.⁸⁶ Desde la versión v0.146.0, los artefactos de lanzamiento, los metadatos de los canales y los alias del instalador se distribuyen desde la infraestructura de lanzamientos alojada por OpenAI, con GitHub como alternativa.¹¹⁴ Si tu red incluye GitHub en la lista de permitidos para instalar y actualizar Codex, agrega también el host de lanzamientos de OpenAI; al existir esta alternativa, una omisión en la lista de permitidos degrada el proceso silenciosamente en lugar de provocar un error evidente.

# Check what you are running
codex --version                          # -> codex-cli 0.153.4
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

Fijar una versión es lo correcto cuando un lanzamiento te causa problemas. Codex mantiene una línea estable que avanza rápidamente, por lo que instalar una versión exacta es la forma más rápida de revertir el cambio: informa el problema, fija la versión y continúa. Confirma la reversión con codex --version, ya que una segunda instalación oculta en tu PATH podría seguir ejecutando silenciosamente el binario anterior (codex doctor señala precisamente este problema en Environment).

Desinstalar el paquete no elimina tu estado. La autenticación, la configuración y el historial de sesiones se almacenan en ~/.codex/. Déjalo en su lugar para conservar los inicios de sesión y el historial al reinstalar; elimínalo solo si realmente quieres empezar desde cero: rm -rf ~/.codex también borra config.toml, auth.json y todas las sesiones almacenadas.

Script de instalación directa (v0.106.0+)

Para macOS y Linux, hay un script de instalación de una sola línea disponible como recurso de lanzamiento de GitHub:⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

El script detecta automáticamente tu plataforma y arquitectura, descarga el binario correcto y lo agrega a tu PATH.

Descargas de binarios

Para entornos sin npm ni Homebrew, descarga los binarios específicos de cada plataforma desde Lanzamientos de GitHub¹:

Requisitos del sistema

• macOS: Apple Silicon o Intel (compatibilidad total con el entorno aislado mediante Seatbelt)
• Linux: x86_64 o arm64 (entorno aislado mediante Landlock + seccomp)
• Windows: Entorno aislado nativo con tokens restringidos (dejó de ser experimental en la versión v0.100.0). WSL también es compatible²

Autenticación

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Hay dos métodos de autenticación:

1. Cuenta de ChatGPT (recomendado): Inicia sesión con tu suscripción existente Plus, Pro, Team, Business, Edu o Enterprise. Tendrás acceso a todas las funciones, incluidas las tareas en la nube.
2. Clave de API: Configúrala mediante la variable de entorno CODEX_API_KEY o con codex login --with-api-key. Es posible que algunas funciones, como los hilos en la nube, no estén disponibles.

Consejo para expertos: Puedes configurar el almacenamiento de credenciales mediante cli_auth_credentials_store en config.toml. Las opciones son file (predeterminada), keyring (llavero del sistema operativo) o auto (usa el llavero si está disponible y, de lo contrario, un archivo).

Inicio de sesión con Amazon Bedrock (v0.145.0, experimental): Los equipos cuyo acceso a modelos se realiza mediante Amazon Bedrock disponen de un método experimental de inicio de sesión compatible con endpoints personalizados y autenticación, además de la autenticación administrada existente mediante claves de API (v0.140.0+) y la cadena de credenciales de AWS (consulta Proveedores de modelos personalizados). GPT-5.6 Sol es el modelo predeterminado de Bedrock.¹¹² La versión v0.150.0 corrige la compactación de conversaciones y la compatibilidad multiagente de los modelos de Amazon Bedrock.¹³² La versión v0.151.0 agrega una opción de Amazon Bedrock, controlada mediante una función experimental, a los flujos de inicio de sesión de la TUI que cumplen los requisitos: durante la configuración inicial, detecta los perfiles de AWS y las credenciales de entorno existentes; ofrece configuración manual mediante perfiles, claves de acceso, variables de entorno y claves de API de Bedrock; solicita la región de AWS; oculta los secretos mientras se introducen; y reinicia el servidor integrado cuando cambia el proveedor.¹³⁵ La versión v0.152.0 muestra el progreso de la renovación de credenciales: la TUI y codex exec muestran el avance mientras un proveedor de modelos renueva credenciales vencidas, incluida la reautenticación de sesiones de Amazon Bedrock. Esto se sustenta en las notificaciones estables modelProvider/authRecoveryStarted y modelProvider/authRecoveryCompleted del servidor de la aplicación, que incluyen el hilo, el turno, el proveedor y un mensaje dirigido al usuario.¹³⁸

Autocompletado del shell

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Verifica la instalación

codex --version
# codex-cli 0.153.4

Inicio rápido: tu primera sesión

Pasa de cero a trabajar productivamente en 5 minutos.

1. Instala y autentícate:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Ve a un proyecto:

cd ~/my-project                  # Any git repo works

3. Inicia Codex:

codex

Verás la TUI interactiva. Codex lee automáticamente la estructura de tu proyecto.

4. Haz una pregunta:

> What does this project do? Summarize the architecture.

Codex lee los archivos clave y explica la base de código. Una pregunta como esta no realiza ningún cambio: Codex solo modifica archivos cuando se lo pides, y el entorno aislado y la política de aprobación determinan cuándo debe solicitar permiso primero.

5. Haz un cambio:

> Add input validation to the login endpoint

Codex propone las modificaciones en forma de diff. Revísalas y apruébalas con y, o recházalas con n.

6. Usa un slash command:

> /plan Refactor the database layer to use connection pooling

Codex crea un plan sin ejecutarlo. Revisa el plan y luego apruébalo para iniciar la ejecución.

7. Revisa tu trabajo:

> /diff

Consulta todos los cambios que Codex realizó durante la sesión actual.

Próximos pasos: - Configura AGENTS.md con las instrucciones del proyecto (consulta ¿Cómo funciona AGENTS.md?) - Configura un perfil para tu flujo de trabajo (consulta Perfiles) - Prueba codex exec para la automatización no interactiva (consulta Modo no interactivo)

Superficies principales de interacción

Codex ofrece cinco interfaces distintas respaldadas por la misma inteligencia. Cada superficie está optimizada para un patrón de trabajo diferente.

1. CLI interactiva (interfaz de usuario de terminal)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

La interfaz de usuario de terminal es una aplicación de pantalla completa con:

• Editor de mensajes: Escribe instrucciones, adjunta archivos con @ y ejecuta comandos de shell con el prefijo !
• Panel de salida: Muestra en tiempo real las respuestas del modelo, las llamadas a herramientas y la salida de los comandos
• Barra de estado: Modelo, uso de tokens, rama de git y modo de sandbox

Atajos principales de la TUI:

Cambio en la línea de estado (v0.121.0): El antiguo medidor de la ventana de contexto de la línea de estado se reemplazó por un indicador porcentual de contexto que muestra qué tan llena está la ventana de contexto. Si tienes scripts o hooks que analizan la línea de estado, ten en cuenta este cambio de formato.⁸² Codex también mostrará un anuncio de actualización de CLI cuando haya una nueva versión disponible.

Slash commands disponibles en la TUI:

Rediseño del selector de flujos de trabajo (v0.129.0): Ahora es más fácil acceder a las opciones de reanudar y bifurcar desde un selector rediseñado. Además, el nuevo modo de historial de desplazamiento sin procesar te permite recorrer la transcripción sin renderizar cuando necesitas copiar literalmente comandos o la salida del modelo. Resulta útil al clasificar una sesión larga de depuración o canalizar la salida hacia otra herramienta.⁸⁹

Menú unificado de menciones con @ (v0.140.0): Al escribir @ en el editor de mensajes, ahora se abre de forma predeterminada un único menú de menciones que abarca archivos, plugins y skills, en reemplazo del flujo que solo permitía adjuntar archivos: basta una tecla para hacer referencia a cualquier recurso del proyecto.¹⁰²

2. Codex Desktop App (macOS + Windows)

codex app                    # Launch desktop app (auto-installs if missing)

La aplicación de escritorio añade capacidades que CLI no tiene:

• Trabajo simultáneo: Ejecuta varios agentes en paralelo en distintos proyectos al mismo tiempo
• Aislamiento mediante git worktrees: Cada hilo trabaja en una copia aislada de tu repositorio
• Revisión de diffs integrada: Prepara, revierte y confirma cambios sin salir de la aplicación
• Terminal integrada: Terminal por hilo para ejecutar comandos
• Bifurcación de conversaciones: Bifurca conversaciones para explorar alternativas
• Ventanas flotantes independientes: Separa las conversaciones en ventanas portátiles
• Automatizaciones: Programa tareas recurrentes (clasificación de incidencias, supervisión de CI y respuesta a alertas)
• Appshots: Adjunta a un hilo la ventana de la aplicación de Mac que está en primer plano, con una captura de pantalla y el texto disponible
• Comentarios en el navegador de la aplicación: Previsualiza páginas locales o públicas, deja comentarios sobre elementos o áreas y permite que Codex responda a observaciones visuales precisas
• Computer Use: Permite que Codex opere aplicaciones de Mac autorizadas para trabajos específicos de GUI; el uso bloqueado es opcional en los turnos remotos de Mac Computer Use que sean aptos

ChatGPT Voice, impulsado por GPT-Live (versión 26.715 de escritorio, 23 de julio de 2026): Ahora puedes controlar la aplicación de escritorio con la voz: conversa sobre el trabajo y coordina tareas en Chat, Work y Codex sin escribir. En macOS, al activar Screen context, se comparte con la conversación un appshot de la ventana que está en primer plano, por lo que puedes preguntar sobre lo que estás viendo en vez de describirlo. Está disponible en Plus, Pro, Business, Edu y Enterprise, tanto en la aplicación de escritorio como mediante Remote en iOS. Esta función de voz pertenece a la superficie de escritorio; la transcripción de voz de la propia CLI mediante la barra espaciadora es una función experimental independiente.¹¹³

Instantáneas compartidas de hilos (20 de agosto de 2026): En todos los planes de Codex, la aplicación de escritorio para macOS puede compartir una instantánea de solo lectura de un hilo local de Codex. La instantánea no se actualiza cuando cambia el hilo original; los enlaces de cuentas personales se abren para cualquier persona que los tenga, mientras que los enlaces de cuentas de espacios de trabajo solo funcionan para miembros del espacio de trabajo de origen. Codex oculta los patrones de secretos conocidos antes de compartir, pero OpenAI recomienda que revises el contenido compartido porque aún podría incluir información confidencial. Consulta o revoca los enlaces en los controles de datos de ChatGPT, dentro de Shared links.¹²⁸

Cuándo usar la aplicación y cuándo CLI: Usa la aplicación de escritorio cuando coordines varios flujos de trabajo o necesites revisar diffs visualmente. Usa CLI cuando necesites que la terminal pueda integrarse con otras herramientas, ejecutar scripts o conectarse con procesos de CI/CD.

3. Extensión para IDE (VS Code, Cursor, Windsurf)

La extensión de Codex para IDE se integra directamente en tu editor:

• Modo de agente predeterminado: Lee archivos, realiza cambios y ejecuta comandos
• Ediciones integradas: Sugerencias basadas en el contexto de tus archivos activos
• Sesiones compartidas: Las sesiones se sincronizan entre CLI y la extensión para IDE
• Misma autenticación: Inicia sesión con tu cuenta de ChatGPT o una clave API

Instálala desde VS Code Marketplace o desde las tiendas de extensiones de Cursor y Windsurf.³

4. Codex Cloud [EXPERIMENTAL]

Las tareas en la nube se ejecutan de forma asíncrona en entornos gestionados por OpenAI:

• Inicia y despreocúpate: Pon en cola tareas que se ejecutan con independencia de tu computadora local
• Ejecución paralela: Ejecuta varias tareas en la nube al mismo tiempo
• Creación de PR: Codex crea pull requests a partir del trabajo completado
• Aplicación local: Incorpora los resultados de la nube en tu repositorio local con codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

También puedes acceder a las tareas en la nube desde chatgpt.com/codex.⁴

5. Extensión de navegador (Chrome, Edge, Brave, Opera, Vivaldi)

Codex se distribuye como una extensión de navegador para Google Chrome, Microsoft Edge, Brave, Opera y Vivaldi, lo que añade una quinta superficie junto con CLI, la aplicación de escritorio, la extensión para IDE y la nube. La extensión se lanzó para Chrome en mayo de 2026; el registro de cambios del 25 de agosto de 2026 añadió los otros cuatro navegadores, cuya configuración se realiza desde Settings > Computer Use en la aplicación de escritorio de ChatGPT. Los cinco admiten menciones de pestañas y control del navegador; Opera no admite el chat lateral, por lo que sus tareas deben iniciarse desde la aplicación de escritorio. La extensión está diseñada para acompañar tu navegación habitual, no para apoderarse de ella: Codex trabaja en paralelo entre pestañas en segundo plano y tú mantienes el control sobre los sitios con los que interactúa.⁹⁰¹²⁷

• Ejecución paralela en pestañas: Codex opera en varias pestañas a la vez sin bloquear la pestaña en primer plano.
• Control por sitio: Tú decides mediante una lista de permitidos con qué sitios web puede interactuar Codex; de forma predeterminada, no tiene acceso a ninguno.
• El navegador como espacio de trabajo: La extensión es ideal para trabajar con aplicaciones y sitios web donde la página es la fuente de verdad —consolas administrativas, paneles internos, interfaces de gestión de contenido y sistemas de tickets—, no para sustituir a CLI en repositorios locales.
• La misma inteligencia: la extensión de navegador utiliza la misma inteligencia GPT-5.x-Codex que las demás superficies, por lo que las convenciones de una configuración de AGENTS.md o skills que funcione en CLI también se aplican al trabajo realizado mediante el navegador.

Instálala desde la documentación de la extensión de navegador, la página que antes se titulaba Codex for Chrome.¹²⁷

Análisis detallado del sistema de configuración

Codex usa TOML para la configuración. Comprender la jerarquía de precedencia es fundamental porque determina qué ajustes prevalecen cuando entran en conflicto.

Precedencia (de mayor a menor)

1. Anulaciones de sesión (mayor prioridad): flags de CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) y anulaciones -c key=value
2. Configuración del proyecto (.codex/config.toml, detectada desde el CWD hacia arriba hasta la raíz del proyecto; prevalece el directorio más cercano)
3. Configuración del usuario ($CODEX_HOME/config.toml, de manera predeterminada, ~/.codex/config.toml)
4. Configuración del sistema (/etc/codex/config.toml en Unix)
5. Valores predeterminados integrados (menor prioridad)

requirements.toml funciona como una capa de restricciones de políticas que limita los valores que los usuarios pueden seleccionar después de combinar la configuración habitual. Consulta Implementación empresarial.

Ubicaciones de los archivos de configuración

Consejo para expertos: La variable de entorno CODEX_HOME reemplaza el directorio predeterminado ~/.codex. Resulta útil para CI/CD o configuraciones con varias cuentas.

Proyectos de varias carpetas en la aplicación de escritorio (26.715, 23 de julio de 2026): Ahora, un proyecto local de la aplicación de escritorio de ChatGPT puede abarcar varias carpetas relacionadas, una de las cuales se designa como carpeta principal (menú del proyecto → Editar proyecto). La detección automática de config.toml solo se ejecuta en la carpeta principal; las carpetas secundarias siguen disponibles para buscar, leer y editar archivos, pero no aportan ninguna configuración. Un archivo .codex/config.toml ubicado en una carpeta secundaria es un archivo que Codex puede leer, no una configuración que carga. Esto corresponde al ámbito de los proyectos en la aplicación de escritorio, no a un cambio en las reglas de precedencia anteriores: CLI sigue resolviendo la configuración del proyecto recorriendo los directorios hacia arriba desde el directorio de trabajo actual.¹¹³

Referencia completa de configuración

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.6-sol"                  # Recommended default (the "Power" setting)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # on-request|never (untrusted retired in v0.149.0)

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output (global; per-tool MCP overrides in v0.152.0)
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Browser-extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

features.network_proxy es boolean | table. La forma booleana solo inicia o detiene el proxy; la forma de tabla contiene la política. El proxy es el encargado de aplicar las reglas de dominio del perfil de permisos a los comandos ejecutados en sandbox: cuando está desactivado, las reglas de dominio de [permissions.<name>.network] no se aplican y el acceso de los comandos a la red es directo. No filtra las búsquedas web, las aplicaciones, los servidores MCP ni otras herramientas alojadas.¹³⁰

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

Los requisitos experimental_network administrados por el administrador en requirements.toml pueden iniciar el proxy sin features.network_proxy.¹³⁰

Perfiles

Son ajustes predefinidos de configuración con nombre para distintos modos de trabajo. Desde Codex 0.134.0, cada perfil tiene su propio archivo —~/.codex/<name>.config.toml, que contiene únicamente claves de nivel superior— y --profile <name> superpone ese archivo a ~/.codex/config.toml. Las antiguas tablas [profiles.<name>] dentro de config.toml y el selector de nivel superior profile = "<name>" ya no se leen; si queda una tabla [profiles.<name>], --profile <name> se negará a iniciarse hasta que traslades sus claves al archivo del perfil.¹²²

# ~/.codex/fast.config.toml
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Un archivo de perfil constituye una capa por encima de tu configuración base de usuario y por debajo de la configuración del proyecto y de CLI, por lo que solo necesita contener los valores que difieren de la configuración base.¹²²

Activa un perfil:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Consejo para expertos: Define un perfil predeterminado con profile = "fast" en el nivel superior de tu configuración. Anúlalo para cada sesión con --profile.

Proveedores de modelos personalizados

Conéctate a Azure, AWS Bedrock, modelos locales o servicios de proxy:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Advertencia: El API de conexión chat/completions (wire_api = "chat") quedó obsoleto para los modelos alojados por OpenAI, y OpenAI anunció su eliminación en febrero de 2026.³⁴ Es posible que los proveedores locales (Ollama, LM Studio) todavía acepten este formato. Para los endpoints de OpenAI, usa wire_api = "responses" en su lugar.

Usa modelos locales con el flag --oss:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

O defínelo en la configuración:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Anulaciones de configuración en línea

Anula cualquier valor de configuración desde la línea de comandos:

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

¿Qué modelo debería elegir?

Modelos disponibles (septiembre de 2026)

GPT-5.5 (23 de abril de 2026) era la opción que OpenAI recomendaba en su lanzamiento para la mayoría de las tareas de Codex: programación compleja, uso de computadoras, trabajo intelectual y flujos de investigación. Estuvo disponible el 23 de abril en Codex CLI / web / escritorio para ChatGPT Plus / Pro / Business / Enterprise / Edu / Go, y el 24 de abril en API de OpenAI. Ventana de contexto: 400K en Codex y 1M en API — Codex limita la ventana a 400K para equilibrar el rendimiento y el costo entre los niveles de suscripción; API ofrece el millón completo. Precio (API): $5 por entrada / $30 por salida por MTok (el doble de la tarifa de GPT-5.4; OpenAI afirma que el aumento efectivo es de aproximadamente un 20 % tras las mejoras en la eficiencia de tokens). Pruebas de rendimiento: 82,7 % en Terminal-Bench 2.0 (el mejor resultado actual entre los modelos disponibles públicamente), 84,9 % en GDPval (44 profesiones), 78,7 % en OSWorld-Verified y 98,0 % en Tau2-bench Telecom (sin ajustes del prompt). OpenAI utilizó GPT-5.5 + Codex internamente para reescribir su infraestructura de servicio antes del lanzamiento, lo que produjo un aumento del 20 % en la velocidad de generación de tokens.⁸³

GPT-5.4 y GPT-5.4 mini se retiran de Codex el 31 de agosto de 2026.¹¹⁷ Hasta entonces, GPT-5.4 seguirá disponible para su selección en todas las interfaces de Codex.⁶⁴ La lista exacta de modelos varía según la cuenta y la fase del lanzamiento. Revisa la caché local: ~/.codex/models_cache.json.

Nota sobre la obsolescencia (11 de marzo de 2026): los modelos GPT-5.1 ya no están disponibles en ChatGPT. Las conversaciones existentes continúan automáticamente en GPT-5.3 Instant, GPT-5.4 Thinking o GPT-5.4 Pro. GPT-5.1-Codex-Mini siguió disponible mediante API y CLI hasta su desactivación el 23 de julio de 2026.⁷¹⁸⁸

Nota sobre el nivel gratuito (5 de mayo de 2026): GPT-5.5 Instant llegó al nivel gratuito de ChatGPT el 5 de mayo de 2026. Esto amplía el público de la familia GPT-5.5 más allá de los planes de pago, aunque el acceso a Codex CLI sigue requiriendo una suscripción válida a Plus / Pro / Business / Enterprise / Edu / Go o una clave de API.⁹²

GPT-5.4 mini (17 de marzo de 2026): una variante más pequeña y rápida de GPT-5.4, con 400K de contexto y un precio de $0,75/$4,50 por MTok, que utiliza solo el 30 % de la cuota de GPT-5.4. Es ideal para delegar en subagentes: deja que GPT-5.4 se encargue de la planificación y la coordinación, mientras los subagentes GPT-5.4 mini resuelven en paralelo subtareas más acotadas (búsqueda en el código base, revisión de archivos y procesamiento de documentos).⁷⁶

Bedrock GPT-5.6 (Sol, Terra, Luna) (v0.143.0, 8 de julio de 2026): Codex incorporó compatibilidad nativa con 3 variantes del modelo GPT-5.6 alojadas en Amazon Bedrock, incluido el nivel de esfuerzo de razonamiento max. Los equipos cuyo acceso a modelos se realiza mediante un proveedor de Bedrock pueden seleccionarlas de la misma forma que otros modelos de proveedores personalizados (consulta Proveedores de modelos personalizados); el nivel de esfuerzo max está pensado para las cargas de razonamiento y de agentes más difíciles.¹⁰⁶ La versión v0.144.6 (18 de julio de 2026) actualizó las instrucciones incluidas para Sol, Terra y Luna, y corrigió sus ventanas de contexto a 272.000 tokens.¹¹¹ La versión v0.145.0 (21 de julio de 2026) incorpora el inicio de sesión experimental en Bedrock con un endpoint personalizado y compatibilidad con autenticación, convierte a GPT-5.6 Sol en el modelo predeterminado de Bedrock y migra las selecciones incluidas de modelos GPT-5.4 a las variantes correspondientes de Terra y Luna.¹¹²

GPT-6-Astra (lanzado el 3 de septiembre de 2026; disponible en Codex mediante las versiones v0.153.1-v0.153.4): esta es la cronología, con fechas explícitas: la versión v0.153.1 incorporó de forma preliminar una entrada de catálogo exclusiva de API el 3 de septiembre de 2026; OpenAI anunció GPT-6-Astra ese mismo día; y la versión v0.153.4 agregó la entrada al selector y lo convirtió en la opción predeterminada de CLI incluido el 4 de septiembre. El anuncio describe un lanzamiento gradual que comienza con un conjunto limitado de organizaciones (primero, socios del programa de ciberseguridad) y se extiende a ChatGPT Plus, Pro, Business y Enterprise «durante los próximos días», además de API de OpenAI y AWS; los datos del lanzamiento provienen de la prensa (CNBC, Axios, Forbes, Al Jazeera y 9to5Mac).¹⁴⁵ Actualización del 4 de septiembre: OpenAI anunció en X que GPT-6 Astra «ya está disponible para todos los usuarios Pro, Enterprise y Business Premium en ChatGPT Work y Codex» y «activo en API», mientras que se esperaba que llegara a Plus y Business en cuestión de días. Esa misma noche, Tibo Sottiaux, responsable de Codex, añadió: «Astra ya se lanzó también para todos los usuarios Plus y Business». En la práctica, los permisos siguen siendo desiguales: reportes de la comunidad del 5 de septiembre indican que algunas cuentas Plus aún solo ven modelos GPT-5.6 en Codex; además, la línea sobre disponibilidad de la documentación de modelos citada a continuación no ha cambiado, por lo que sigue siendo la declaración oficial aplicable.¹⁴⁹ La documentación oficial ya está disponible: la página del modelo de API presenta gpt-6-astra como el modelo insignia, «Nuestro modelo más capaz, creado para los trabajos integrales más difíciles» – $10/MTok de entrada, $50/MTok de salida con las tarifas estándar de contexto corto, una ventana de contexto de 1,05M tokens con un máximo de 922.000 tokens de entrada, 128K de salida máxima y fecha límite de conocimiento del 30 de abril de 2026 – e incluye un nivel documentado para contextos largos: los prompts que superan los 272K tokens de entrada se cobran al doble por la entrada y a 1,5 veces por la salida en toda la solicitud, es decir, $20/MTok de entrada y $75/MTok de salida según la página de precios. Se sitúa por encima de GPT-5.6 Terra (equilibrado) y Luna (económico), y la documentación de Codex designa a Astra como el modelo recomendado para Codex, con una disponibilidad que «depende del lanzamiento, tu método de inicio de sesión y tu cliente», y especifica que pueden acceder las cuentas Pro, Business ($100) y Enterprise. La escala de razonamiento documentada de Astra en Codex es: Low, Medium, High, Extra High, Max, Ultra – la página de documentación de modelos indica Medium como valor predeterminado, mientras que el catálogo incluido en la versión v0.153.4 establece default_reasoning_level en low; por lo tanto, considera que el valor predeterminado efectivo depende de la interfaz y compruébalo con /status durante una sesión.¹⁴⁶¹⁴⁸ En CLI, Astra se puede configurar mediante API desde la versión v0.153.1 (-m gpt-6-astra), se incorpora a los catálogos de Amazon Bedrock en la versión v0.153.3 (GPT-5.6 Sol sigue siendo el modelo predeterminado de Bedrock) y, desde la versión v0.153.4, aparece en el selector de modelos y es la opción predeterminada incluida cuando no se configura explícitamente ningún modelo. No se documenta una versión mínima de CLI, así que considera esas versiones como los mínimos efectivos. Este cambio del modelo predeterminado corresponde al catálogo incluido de CLI, no a todas las interfaces: la matriz de disponibilidad de la documentación de modelos indica que Astra no está disponible en Codex cloud (GPT-5.6 Sol sigue disponible allí), y la página señala: «Actualmente, no puedes cambiar el modelo predeterminado de los chats de Codex cloud». Advertencia sobre el lanzamiento: los permisos varían según la cuenta y, en CLI 0.153.4 o posterior, una cuenta que aún no forme parte del lanzamiento tendrá un modelo predeterminado incluido al que todavía no puede acceder. Fija model = "gpt-5.6-sol" en config.toml (o pasa -m) para obtener una selección determinista. La facturación del modo Fast de Astra está documentada, aunque la página de modelos no enumera ningún nivel Fast: la documentación de velocidad de Codex establece un costo de 2,5 veces los créditos Standard al iniciar sesión con ChatGPT («donde esté disponible»), mientras que la página de precios de API muestra tarifas del modo Fast equivalentes a exactamente 2 veces las tarifas Standard aplicables ($20/$100 por MTok en contexto corto y $40/$150 en contexto largo). La parte de «velocidad 2x» de la cadena del catálogo de la versión v0.153.2 sigue siendo solo texto mostrado en el catálogo; la página de velocidad no especifica ningún multiplicador de velocidad para Astra.^145146147148

Opciones preestablecidas de Power con Astra (adición a la documentación, publicada a más tardar el 6 de septiembre de 2026): el fragmento sobre el selector de modelos en la documentación de modelos de Codex ahora asigna las opciones Power del selector a los niveles de razonamiento de GPT-6-Astra; es la primera correspondencia documentada entre las opciones preestablecidas de Power y Astra. Este párrafo no aparecía cuando se volvió a consultar ¹⁴⁶ el 5 de septiembre y se confirmó que estaba publicado el 7 de septiembre. Textualmente: «Para las cuentas Pro, Business ($100) y Enterprise que cumplan los requisitos, el lanzamiento de Astra actualiza las opciones Power a Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium y Astra Extra High. Las opciones pueden variar según el plan y la fase del lanzamiento». La oración anterior de la documentación señala que las ilustraciones del selector todavía muestran los controles de GPT-5.6. Debe interpretarse junto con la tabla de modelos anterior: «Power» ha correspondido a GPT-5.6 Sol con razonamiento medium; en una cuenta con los permisos necesarios, esa misma escala de opciones preestablecidas ahora abarca Terra, Sol y Astra con niveles de razonamiento fijos, y las opciones siguen dependiendo del plan y de la fase del lanzamiento.¹⁴⁶

Notas experimentales entre contextos (Astra, publicadas en la documentación, participación voluntaria): la página de documentación de modelos de Codex incluye una sección titulada «Administración experimental del contexto» que dice textualmente: «En los clientes de Codex compatibles, los usuarios que hayan iniciado sesión con ChatGPT Plus o Pro pueden activar voluntariamente la administración experimental del contexto. Astra conserva notas entre ventanas de contexto y puede buscar mensajes anteriores y resultados de herramientas de la misma tarea. Este experimento está desactivado de forma predeterminada y, en el lanzamiento, no está disponible con Business, Enterprise ni al iniciar sesión con una clave de API». El mecanismo de activación indica textualmente: «Para activarlo, establece features.context_management.experimental_mode = true en tu config.toml y, luego, inicia una tarea nueva». Es la misma opción features.context_management.experimental_mode que se incorporó en la versión v0.153.0 (consulta Administración del contexto); la página de documentación ahora la vincula por nombre con Astra y con el inicio de sesión de Plus y Pro, mientras que las notas de la versión v0.153.0 mencionaban sesiones válidas de Plus, Pro y Pro Lite. Es experimental y está desactivada de forma predeterminada; es probable que el comportamiento y los requisitos cambien.¹⁴⁰¹⁴⁶

Diagrama de flujo para seleccionar un modelo

Is this a quick fix or simple question?
├─ Yes → gpt-5.6-luna (fastest, most affordable)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.6-luna (the bundled subagent pick since v0.145.0)
   │     │  └─ No
   │     │     ├─ Everyday coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.6-terra (everyday model, 272K context)
   │     │     │  └─ No
   │     │     │     ├─ In the GPT-6-Astra rollout (entitled account)?
   │     │     │     │  ├─ Yes → gpt-6-astra (new flagship; bundled default at 0.153.4+)
   │     │     │     │  └─ No → gpt-5.6-sol ("Power" setting; stable fallback)
   └─ Still unsure? → gpt-5.6-sol

Esfuerzo de razonamiento

Controla cuánto «piensa» el modelo antes de responder:

Los niveles disponibles dependen del modelo. minimal solo está disponible para los modelos GPT-5. No todos los modelos admiten todos los niveles.

Detalles de persistent (v0.151.0): los turnos que se ejecutan con el esfuerzo persistent activan de forma predeterminada el recordatorio de la hora actual y la herramienta interrumpible clock.sleep (se conservan la configuración explícita de features.current_time_reminder y los requisitos administrados), e incluyen instrucciones de proactividad y seguimiento que los metadatos del modelo pueden reemplazar o desactivar mediante persistent_instructions.¹³⁵

codex -c model_reasoning_effort="xhigh" "find the race condition"

Consejo experto: el razonamiento xhigh puede consumir entre 3 y 5 veces más tokens que medium para el mismo prompt. Resérvalo para problemas realmente difíciles en los que valga la pena el razonamiento adicional.

Controles rápidos de razonamiento en la TUI (v0.124.0+).⁸⁵ En una sesión interactiva de la TUI, Alt+, reduce el razonamiento un nivel y Alt+. lo aumenta un nivel. Esto resulta útil cuando un problema difícil durante una sesión justifica un aumento temporal medium → high → xhigh sin usar /effort ni -c. Cuando aceptas una actualización de modelo durante una sesión, el razonamiento vuelve al valor predeterminado del modelo nuevo en lugar de conservar el nivel anterior.

Cambio de modelo

Cambia de modelo durante una sesión con el slash command /model, o configúralo para cada ejecución mediante --model / -m:

codex -m gpt-5.3-codex-spark "pair with me on this component"

¿Cuánto cuesta Codex?

Consulta también Selección de modelos para conocer sus capacidades y Marcos de decisión para elegir el modelo adecuado para cada tarea.

Acceso mediante planes de ChatGPT

La disponibilidad de Codex depende de tu plan de ChatGPT y de la configuración de la organización:⁵¹

Actualización de precios de abril de 2026: el precio anual de Business bajó de $25 a $20 por licencia al mes. Ahora hay licencias exclusivas para Codex con pago por uso disponibles para los espacios de trabajo Business y Enterprise: no tienen una tarifa fija por licencia y se facturan según el consumo de tokens.⁷⁹ La página de precios ahora publica los límites como rangos por modelo (consulta la tabla anterior), en lugar de los multiplicadores promocionales de 2x del lanzamiento de Codex Desktop App en febrero de 2026.¹⁶¹⁵²

Aumento del límite de uso en mayo de 2026 (venció el 31 de mayo de 2026): Codex con el plan Plus funcionó con un límite de 5 horas multiplicado por 25 (frente al aumento estándar de 20x), y el nivel de $100 al mes se duplicó durante el mismo periodo.⁸⁹

Experiencia de los límites de uso en la TUI (v0.152.0-v0.153.0): alcanzar un límite ya no supone un callejón sin salida. La v0.152.0 muestra avisos de límite de uso con acciones disponibles encima del cuadro de redacción —consultar el uso, administrar créditos, restablecer límites, notificar al propietario del espacio de trabajo y administrar planes—, filtrados según la cuenta autenticada y el usuario; el uso se actualiza después de los errores por límites y, cuando el aviso así lo indica, Codex cambia al primer modelo alternativo disponible sin modificar ninguna configuración no relacionada del hilo.¹³⁸ La v0.153.0 añade advertencias más tempranas para los planes Plus y Team: se muestra una advertencia cuando queda menos de la mitad de la asignación en una ventana de uso de aproximadamente 5 horas, mientras que los demás planes y las ventanas de otras duraciones conservan los umbrales existentes del 75 %, 90 % y 95 %.¹⁴⁰

Costos en créditos

Las operaciones de Codex consumen créditos de la asignación de tu plan:

En la práctica, «el uso de GPT-5.6 promedia entre 5 y 40 créditos por mensaje»; el modo rápido consume créditos a una tasa mayor en los modelos compatibles, y la generación de imágenes agota los límites incluidos entre 3 y 5 veces más rápido que las interacciones comparables que solo contienen texto.¹⁵²

Los créditos de los planes Enterprise y Edu se ajustan según la asignación del contrato. Consulta /status en la TUI para conocer el uso actual.

Facturación de API

Cuando usas Codex mediante la API, OpenAI factura el uso por token de acuerdo con el precio estándar de la API de OpenAI para el modelo seleccionado, además de cualquier descuento aplicable por almacenamiento en caché de prompts. Consulta la página oficial de precios de la API para conocer las tarifas actuales.²⁰

Estrategias para optimizar costos

1. Usa perfiles: crea un perfil fast con gpt-5.6-luna y model_reasoning_effort = "low" para tareas rutinarias
2. Reserva el razonamiento intensivo: usa xhigh solo para problemas realmente difíciles, ya que consume entre 3 y 5 veces más tokens
3. Usa --ephemeral: omite la persistencia de sesiones en CI/CD para reducir la sobrecarga
4. Minimiza los resúmenes de razonamiento: establece model_reasoning_summary = "none" cuando no necesites explicaciones
5. Procesa por lotes con el modo exec: codex exec evita la sobrecarga de la TUI en los flujos de automatización
6. Supervisa el uso: consulta /status en la TUI y los paneles de facturación de tu organización; desde la v0.148.0, /status, las líneas de estado y los títulos de la terminal muestran una estimación de los créditos o del costo del hilo para los espacios de trabajo que cumplen los requisitos¹¹⁸

Ejemplos de costos reales

Costos representativos de la API para tareas comunes (una instantánea de precios de gpt-5.3-codex de mediados de 2026, con razonamiento medio; las proporciones relativas se mantienen entre modelos):

Los costos varían según el esfuerzo de razonamiento, el almacenamiento en caché y la longitud de la conversación. Usa gpt-5.6-luna para reducir considerablemente el gasto de las tareas rutinarias. Los tokens de entrada almacenados en caché se facturan con descuento.

Sobrecarga oculta de tokens

Cada llamada a una herramienta añade tokens además de los que contiene tu prompt visible:

Consejo para expertos: supervisa tu uso real mediante /status en la TUI. El recuento de tokens incluye toda la sobrecarga, no solo tus mensajes visibles. Si los costos te sorprenden, comprueba cuántos servidores de MCP están conectados: cada uno añade definiciones de herramientas a todas las llamadas de API.

Gestión de costos del equipo

Estrategias para controlar los costos del equipo: - Configura requirements.toml para aplicar límites de modelo y esfuerzo de razonamiento en toda la organización - Usa gpt-5.6-luna para CI/CD: los procesos automatizados rara vez necesitan el nivel máximo de razonamiento - Presupuestos basados en perfiles: define perfiles ci, review y dev con límites de costo adecuados - Supervisa mediante OpenTelemetry: las implementaciones empresariales pueden exportar la telemetría de uso a las plataformas de observabilidad existentes

Marcos de decisión

Cuándo usar cada interfaz

Cuándo usar cada modo de sandbox

Cuándo usar cada nivel de razonamiento

Modo Plan frente a ejecución directa

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Modo Steer: Enter frente a Tab

Regla general: Enter = «detente y presta atención a esto ahora». Tab = «cuando termines, haz también esto».

Desktop App frente a CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

¿Qué perfil elegir?

Elige un perfil preconfigurado según tu tarea:

Archivos de perfil (uno por cada ajuste predefinido, en ~/.codex/; el formato anterior de archivo único profile = "default" + [profiles.*] no se reconoce desde la versión 0.134.0¹²²):

# ~/.codex/fast.config.toml
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Cambia de perfil para cada sesión: codex --profile careful

¿Cómo funciona el sistema de sandbox y aprobación?

Codex utiliza un modelo de seguridad de dos capas que separa lo que es técnicamente posible de cuándo Codex solicita aprobación humana. El enfoque difiere radicalmente del sistema de permisos de Claude Code: Codex aplica las restricciones en el nivel del kernel del sistema operativo.⁵ Consulta también Implementación empresarial para conocer las restricciones de requirements.toml que los administradores aplican en toda la organización.

Refuerzo de seguridad en v0.148.0: ahora las restricciones del sandbox se cierran ante fallos: tanto en Linux como en Windows, una ruta denegada o ilegible se considera bloqueada en lugar de permitirse silenciosamente.¹¹⁸

Capa 1: sandbox (qué es posible)

El sandbox controla el acceso al sistema de archivos y a la red mediante mecanismos nativos del sistema operativo:

Aplicación específica de cada plataforma:

• macOS: framework Seatbelt de Apple mediante sandbox-exec, con perfiles específicos para cada modo que se compilan durante la ejecución y que aplica el kernel⁶. Desde v0.121.0, los perfiles del sandbox de macOS pueden incluir sockets Unix específicos en una lista de permitidos (por ejemplo, docker.sock y sockets IPC del editor), y la resolución DNS privada ya no se bloquea de forma predeterminada.⁸²
• Linux: Landlock para restringir el sistema de archivos y seccomp para filtrar llamadas al sistema. Un proceso auxiliar independiente (codex-linux-sandbox) proporciona aislamiento de defensa en profundidad.⁵ Bubblewrap (bwrap) se incluye y compila como parte de la compilación para Linux (dejó de ser opcional en v0.100.0)⁷. v0.117.0 mejoró la fiabilidad del sandbox en distribuciones antiguas con configuraciones de kernel heredadas.⁷⁵ v0.129.0 reforzó el inicio del sandbox en Linux y actualizó la versión incluida de Bubblewrap a 0.11.2, con parches de seguridad del proyecto original; v0.130.0 añadió más medidas de refuerzo durante el inicio.⁸⁹⁹¹
• Windows: sandbox nativo con tokens restringidos (dejó de ser experimental en v0.100.0). También se admite WSL, que hereda Landlock y seccomp de Linux. v0.117.0 incluye mejoras en el sandbox de tokens restringidos para aislar mejor los procesos.⁷⁵ v0.130.0 permite que los usuarios del sandbox accedan a la caché de archivos binarios del entorno de ejecución de escritorio, de modo que el sandbox de Windows pueda resolverlos de manera fiable para quienes utilizan el sandbox del espacio de trabajo.⁹¹

Por qué es importante: A diferencia del aislamiento basado en contenedores (Docker), el sandbox en el nivel del sistema operativo es más rápido, ligero y difícil de vulnerar. El kernel aplica las restricciones antes de que Codex llegue siquiera a ver la llamada al sistema.

Correcciones de seguridad: - Evasión del sandbox mediante una bifurcación de zsh (v0.106.0): se corrigió una vulnerabilidad que permitía que la ejecución del shell mediante una bifurcación de zsh eludiera las restricciones del sandbox.⁶⁰ Si utilizas una versión anterior, actualízala de inmediato. - Límite del tamaño de entrada (v0.106.0): Codex ahora aplica un límite aproximado de 1 millón de caracteres para evitar bloqueos provocados por cargas útiles excesivamente grandes.⁶⁰ - Perfil seguro para devcontainers (v0.121.0): un nuevo perfil reforzado para devcontainers de Docker utiliza Bubblewrap para aplicar el sandbox dentro del contenedor. Se admite WSL2; WSL1 se rechaza explícitamente porque Bubblewrap es incompatible con la capa de compatibilidad del kernel de WSL1.⁸² - Revisión de Guardian y hooks (v0.121.0): los hooks están deshabilitados durante las sesiones de revisión de Guardian, de modo que los hooks anteriores o posteriores al uso de herramientas no interfieran en las decisiones del subagente Guardian.⁸² Si dependes de los hooks para registrar o validar operaciones, ten presente que las revisiones de Guardian los omiten; recurre a la observabilidad del servidor de la aplicación si necesitas un registro de auditoría completo. - Sistema de archivos /dev en Linux (v0.105.0): los comandos ejecutados en el sandbox de Linux ahora reciben un sistema de archivos /dev mínimo, lo que mejora la compatibilidad con herramientas que esperan encontrar nodos de dispositivo.⁶¹

Política ReadOnlyAccess (v0.100.0+): una estructura de políticas configurable para controlar con precisión el acceso de lectura. Úsala para restringir los directorios que Codex puede leer, incluso en el modo workspace-write:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Capa 2: política de aprobación (cuándo preguntar)

La política de aprobación determina cuándo Codex se detiene para solicitar confirmación humana:

on-failure todavía aparece en algunos ejemplos antiguos y rutas de compatibilidad, pero la documentación actual de configuración de OpenAI lo marca como obsoleto. Prefiere on-request para las ejecuciones interactivas y never para las no interactivas que ya cuenten con un límite de seguridad externo.⁸⁷

Desde v0.150.0, puedes asignar un atajo de teclado para alternar entre los modos de permisos desde el editor; configúralo mediante /keymap.¹³²

IDs de aprobación distintos (v0.104.0+)

Codex ahora asigna un ID de aprobación distinto a cada comando de una ejecución de shell con varios pasos. Esto permite aprobaciones específicas: aprobar un comando de una secuencia no aprueba automáticamente los posteriores dentro de la misma invocación del shell.⁴⁹

Controles de aprobación flexibles (v0.105.0+)

El flujo de aprobación ahora admite permisos adicionales para el sandbox y rechazos específicos:⁶¹

• Permisos adicionales para el sandbox: cuando un comando necesita acceso más allá del modo actual del sandbox, Codex puede solicitar permisos adicionales específicos en lugar de requerir un cambio completo de modo
• Rechazo específico: rechaza llamadas individuales a herramientas y proporciona comentarios para que Codex pueda adaptar su enfoque en lugar de limitarse a intentar de nuevo el mismo comando

Solicitudes de permisos durante la ejecución (v0.113.0+)

Codex ahora incluye una herramienta integrada request_permissions que permite al modelo solicitar permisos adicionales durante la ejecución.⁶⁹ Cuando el modelo encuentra una tarea que requiere acceso elevado, puede solicitar formalmente permisos específicos —rutas del sistema de archivos, acceso a la red, etc.— mediante el flujo de aprobación de la TUI, en vez de fallar silenciosamente o exigir que el usuario reinicie con otras flags.

Modo de aprobación de aplicaciones writes (v0.144.0+)

Las aplicaciones y los conectores incorporan un nivel de aprobación intermedio: el modo de aprobación de aplicaciones writes permite ejecutar sin confirmación las acciones que una aplicación haya declarado como de solo lectura, pero sigue deteniéndose ante cualquier operación de escritura.¹⁰⁷ Antes, las aprobaciones de aplicaciones se parecían más a una elección de todo o nada; writes se ajusta al nivel de confianza que la mayoría de los operadores realmente desea para las integraciones: libertad para consultar, permiso para modificar.

Aprobaciones revisadas automáticamente: --approve-for-me (v0.147.0+)

La nueva flag --approve-for-me de CLI convierte las solicitudes de aprobación en aprobaciones revisadas automáticamente: en lugar de interrumpirte, cada solicitud pasa por una revisión que la aprueba o rechaza en tu nombre.¹¹⁶ Esto ocupa un punto intermedio entre «aprobarlo todo» —la postura que antes fomentaba --full-auto, ahora eliminado— e «interrumpir por todo»: las solicitudes siguen existiendo como puntos de decisión, pero un revisor las responde. Combínala con los valores predeterminados más seguros de revisión automática para modelos con capacidades de ciberseguridad incorporados en v0.146.1, que esta flag hereda. Trátala como cualquier delegación de autoridad: es adecuada para ejecuciones largas sin supervisión en las que una interrupción provocaría un bloqueo, pero no para sesiones que afecten credenciales o el estado de producción, donde conviene que tú seas quien revise.

Aprobación de entradas elevadas de terminal (v0.151.0)

La flag de función write_stdin_approval —deshabilitada de forma predeterminada— exige una nueva aprobación antes de enviar una entrada no vacía a una terminal unified-exec elevada. Estas revisiones se canalizan mediante hooks, Guardian, el servidor de la aplicación y la TUI como aprobaciones writeStdin; el entorno de la terminal, el directorio de inicio y el estado de elevación persisten entre turnos, y la identidad del proceso se vuelve a validar después de la aprobación y antes de escribir cualquier byte. La acción con todo su formato y el motivo de la aprobación deben caber en 8.000 bytes; las acciones demasiado grandes o truncadas se rechazan antes de solicitar aprobación o de que algún contenido llegue a la terminal.¹³⁵

Perfiles de permisos (v0.113.0+, ampliados en v0.128.0 y v0.133.0)

Los perfiles de permisos separan las políticas del sandbox para el sistema de archivos y la red en secciones reutilizables con nombre. Configura default_permissions con un perfil integrado como :read-only o :workspace, o haz que apunte a una tabla [permissions.<name>] personalizada.⁸⁷ v0.133.0 consolida los perfiles como una superficie administrada: los listados de APIs exponen los metadatos de los perfiles disponibles, los perfiles pueden heredarse entre sí, el archivo requirements.toml administrado puede declarar requisitos de permisos, los perfiles activos se actualizan durante la ejecución y la configuración del sandbox de Windows ahora utiliza el perfil resuelto en vez de una política específica independiente.⁹⁸

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

Usa none para archivos confidenciales y patrones glob que deban ser ilegibles incluso cuando se pueda escribir en la raíz del proyecto. Para excepciones puntuales de comandos, prefiere las reglas en lugar de ampliar demasiado un perfil.⁸⁷

v0.151.0: los hilos restaurados del servidor de la aplicación conservan sus perfiles de permisos en vez de reducirse a anulaciones heredadas del sandbox para cada turno; los perfiles sobreviven al enrutamiento de turnos y a los cambios de directorio compatibles mediante /cd, mientras que cualquier /cd que no pueda representar de forma segura el perfil restaurado como un modo de sandbox heredado se rechaza en lugar de debilitar silenciosamente las restricciones.¹³⁴

Orientación heredada sobre --full-auto

Las guías anteriores describían --full-auto como un alias práctico de:

codex --sandbox workspace-write --ask-for-approval on-request

En v0.128.0, las notas de la versión marcan --full-auto como obsoleto, y la ayuda actual de CLI ya no lo incluye para ejecuciones interactivas. Usa las flags explícitas anteriores o un perfil de permisos con nombre.⁸⁶

v0.147.0 completa la eliminación: codex exec --full-auto ya no existe. Un script que todavía pase la flag ahora produce un error en lugar de ejecutarse. La migración es mecánica: sustitúyela por --sandbox workspace-write y añade una flag de aprobación o un perfil si la invocación anterior dependía del comportamiento de aprobación de --full-auto. Audita cualquier automatización que invoque codex exec mediante el shell antes de actualizar: el fallo se manifiesta como una canalización interrumpida, no como una advertencia de obsolescencia.¹¹⁶

Fiabilidad del sandbox (v0.129.0): el refuerzo del inicio del sandbox de Linux reduce las condiciones de carrera en sistemas de archivos lentos o repositorios extraídos mediante enlaces simbólicos; las mejoras de fiabilidad del sandbox de Windows corrigen varios cierres inesperados en casos límite durante ejecuciones prolongadas; y la versión incluida de Bubblewrap se actualiza a 0.11.2, con parches de seguridad del proyecto original. No se requieren cambios de configuración. Ejecuta codex update para obtener estas mejoras.⁸⁹

Configuraciones recomendadas

Desarrollo diario (opción predeterminada segura):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Usuario avanzado (acceso completo con supervisión humana):

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

Algunos artículos de la comunidad recomiendan esta combinación como un «punto ideal»⁸; entiende qué hace realmente antes de repetir el consejo: las solicitudes de aprobación aparecen cuando un comando necesita salir del sandbox o acceder a la red, y danger-full-access elimina ambos límites, por lo que a on-request casi no le queda nada que elevar. Ofrece capacidad máxima con un mínimo de preguntas, no capacidad máxima con verificación humana para cada comando; si quieres esto último, conserva workspace-write y deja que el límite del sandbox genere las solicitudes.¹²³

Automatización de CI/CD:

sandbox_mode = "workspace-write"
approval_policy = "never"

Aprobaciones inteligentes con el subagente Guardian (v0.115.0+)

Las aprobaciones inteligentes pueden canalizar las solicitudes de revisión mediante un subagente Guardian, en lugar de requerir aprobación humana para cada acción. La sesión de Guardian persiste entre aprobaciones para reutilizar la caché del prompt y evitar la sobrecarga del inicio. Cada revisión recibe un historial limpio, por lo que las decisiones anteriores no se filtran en las posteriores.⁷³

Configura el revisor en config.toml:

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

Esto resulta especialmente útil en flujos de trabajo de CI/CD donde quieres una revisión automatizada con razonamiento, en vez de aplicar indiscriminadamente approval_policy = "never".

Cambio de los valores predeterminados de Guardian v2 (v0.151.0): Guardian v2 ahora utiliza de forma predeterminada revisiones de uso de computadora con imágenes. features.guardianv2.review_scope.computer_use_only tiene como valor predeterminado true; configúralo como false para conservar el alcance más amplio de revisión de herramientas. Asimismo, features.guardianv2.transcript.include_images tiene como valor predeterminado true; configúralo como false para excluir las imágenes de las transcripciones de Guardian. Ambas funciones se incorporaron en v0.150.0 como opciones configurables desactivadas de forma predeterminada; en v0.151.0 pasaron a estar activadas.¹³⁵

El alcance de Guardian sigue el modo de aprobación (v0.153.0): ahora dos modos omiten el trabajo de Guardian que no puede cambiar el resultado. En Acceso completo —que ya combina approvalPolicy: "never" con permisos sin restricciones—, las solicitudes de confirmación de Guardian y MCP se aprueban sin revisión síncrona, precalentamiento del muestreador ni puntuación en segundo plano; los entornos pendientes, fallidos o restringidos no se consideran de Acceso completo, y el estado activo de los permisos se vuelve a evaluar en cada turno para que un hilo existente pueda entrar o salir de este modo de forma segura. En el modo de aprobación del usuario (approvals_reviewer = "user"), se omiten el precalentamiento de Guardian y la puntuación asíncrona, y las confirmaciones ordinarias de ejecución de node_repl.js se aceptan automáticamente, mientras que las comprobaciones de acciones confidenciales y las solicitudes de intervención del usuario conservan su comportamiento actual.¹⁴⁰ Esto limita cuándo se ejecuta Guardian, no la capa de aprobación humana: el comportamiento de las solicitudes que esta guía describe para danger-full-access con on-request corresponde a la política de aprobación, que es un mecanismo independiente. v0.152.1 también permite que la revisión de aprobaciones de Guardian obtenga su política de Node REPL de los metadatos del modelo (auto_review.node_repl_policy) y recurra a la política incluida cuando el campo no esté presente.¹³⁹

La puntuación de uso de computadora de Guardian respeta los requisitos del modelo (v0.153.1): la puntuación de Guardian limitada al uso de computadora y las decisiones rápidas de aprobación ahora solo se ejecutan cuando el modelo activo establece node_repl_auto_review_required en sus metadatos; además, las puntuaciones anteriores o en curso se invalidan cuando un cambio de modelo omite la puntuación, por lo que volver a un modelo sujeto a revisión no puede reactivar una decisión de aprobación obsoleta. Esta es la novedad principal del parche v0.153.1, aunque no aparece en el cuerpo de las notas de la versión: #42422 —una selección del commit 38ba8cdc— solo puede comprobarse mediante la comparación rust-v0.153.0…rust-v0.153.1.¹⁴²

Clasificador de PowerShell más estricto (v0.142.2): los comandos de PowerShell que contienen regiones ejecutables del AST que el clasificador de seguridad no puede inspeccionar ahora requieren aprobación, en lugar de pasar inadvertidos por la aprobación automática. Esto cierra una brecha que permitía que PowerShell ofuscado o construido dinámicamente eludiera la clasificación en Windows.¹⁰⁵

Detección ampliada de comandos peligrosos (v0.144.5): la detección ahora reconoce más variantes forzadas de rm, y los comandos rechazados muestran motivos de rechazo más claros en vez de una denegación opaca, lo cual resulta útil al ajustar políticas de aprobación y necesitar saber por qué se bloqueó un comando.¹¹⁰

Habilitar el acceso a la red

Codex bloquea de forma predeterminada el acceso a la red en el modo workspace-write. Habilítalo cuando sea necesario:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

Compatibilidad con proxies de WebSocket (v0.104.0+)

Para entornos empresariales que dirigen el tráfico de WebSocket mediante un proxy, Codex ahora admite las variables de entorno WS_PROXY y WSS_PROXY:⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

Estas complementan la compatibilidad existente con HTTPS_PROXY y proxies SOCKS5 (v0.93.0+).

v0.146.0 es la versión que hizo que «todas las capas de transporte» fuera realmente cierto. Ahora los proxies configurados se respetan en la autenticación, las descargas de plugins, la autorización de MCP, la ejecución remota, las conexiones de WebSocket, las redirecciones HTTP y las conexiones con LM Studio: siete rutas que, según el registro de cambios, antes ignoraban el proxy.¹¹⁴ Si ejecutabas Codex detrás de un proxy empresarial antes de v0.146.0 y los inicios de sesión o las instalaciones de plugins fallaban mientras las llamadas normales al modelo funcionaban, esta brecha probablemente lo explique.

Proxy del sistema en macOS (v0.142.2+): con respect_system_proxy habilitado, los clientes de autenticación de macOS respetan la configuración del proxy del sistema, PAC y WPAD. Así, las Mac empresariales que reciben la configuración del proxy mediante perfiles ya no necesitan variables de entorno del proxy en cada shell para el tráfico de autenticación.¹⁰⁵ Desde v0.143.0, esto se extiende a Windows y al tráfico de Responses API: Codex dirige tanto la autenticación como las llamadas de Responses API mediante el proxy del sistema de macOS o Windows, incluida la configuración automática con PAC y WPAD, lo que cierra la última brecha en redes empresariales restringidas de ambos sistemas operativos.¹⁰⁶

Probar el sandbox

Verifica el comportamiento del sandbox antes de confiar en él:

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

Si el sandbox funciona correctamente, ambos comandos deberían fallar con un error de permiso denegado al usar un perfil limitado al espacio de trabajo. Si alguno se ejecuta correctamente, debes investigar la configuración del sandbox.

¿Cómo funciona AGENTS.md?

AGENTS.md es el sistema de instrucciones de proyecto de Codex: un estándar abierto⁹ que ahora está bajo la dirección de la Agentic AI Foundation de la Linux Foundation. Es compatible con Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode y más de 60.000 proyectos de código abierto. Define cómo se comporta Codex dentro de un repositorio o directorio específico. Consulta Skills para conocer los paquetes de conocimientos reutilizables que complementan AGENTS.md.

Jerarquía de descubrimiento

Codex crea una cadena de instrucciones al iniciar la sesión recorriendo el árbol de directorios:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Proyecto (desde la raíz de git hasta el directorio actual): En cada nivel se busca AGENTS.override.md > AGENTS.md > nombres de archivo alternativos
3. Combinación: Los archivos se concatenan desde la raíz hacia abajo; los archivos más cercanos aparecen después en el prompt y prevalecen sobre las instrucciones anteriores

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Los proyectos no confiables omiten el AGENTS.md del proyecto (v0.150.0): el recorrido anterior presupone que el proyecto es confiable. Desde la versión v0.150.0, «Los proyectos no confiables ya no proporcionan instrucciones de AGENTS.md en el ámbito del proyecto, y las reglas administradas de denegación de lectura siguen aplicándose después de los cambios de permisos»; el descubrimiento dentro del proyecto se omite, mientras que se conservan las instrucciones de usuario de ~/.codex/AGENTS.md, de modo que un repositorio no confiable no pueda inyectar un contrato operativo antes de que confíes en él.¹³²

Proyectos de escritorio con varias carpetas (26.715, 23 de julio de 2026): el recorrido anterior describe CLI, que resuelve todo en relación con el directorio de trabajo actual. La aplicación de escritorio de ChatGPT ahora permite que un proyecto local abarque varias carpetas relacionadas y realiza el descubrimiento usando exactamente una de ellas: «Los chats nuevos, las operaciones de Git y el descubrimiento automático de AGENTS.md, skills y config.toml utilizan la carpeta principal. Las carpetas secundarias siguen disponibles para buscar, leer y editar archivos». Puedes elegir qué carpeta será la principal desde el menú del proyecto mediante Editar proyecto.¹¹³

Esa única configuración controla al mismo tiempo 3 de los 5 sistemas principales de Codex: las instrucciones, las skills y la configuración siguen la carpeta principal. En la práctica, un AGENTS.md ubicado en una carpeta secundaria es un archivo que Codex puede abrir, no un contrato operativo que carga. Si el repositorio que contiene tus reglas es el que adjuntaste en segundo lugar, conviértelo en la carpeta principal o vuelve a incluir esas reglas en el AGENTS.md de la carpeta principal; lo mismo se aplica a las carpetas de skills del repositorio que esperabas que se detectaran. Nada cambió en el recorrido de directorios de CLI; esto corresponde al ámbito de los proyectos de la aplicación de escritorio.

Qué caracteriza a un excelente AGENTS.md

Según las recomendaciones directas del propio Codex y los patrones de la comunidad¹⁰:

QUÉ HACER: - Sé específico: "Use rg --files for discovery" es mejor que "search efficiently" - Define el criterio de finalización: ¿Qué significa que algo esté «terminado»? (las pruebas pasan, el lint no arroja errores, etc.) - Incluye comandos: compilación, pruebas, lint y formato (con las invocaciones exactas) - Organiza por tarea: secciones de programación, revisión, lanzamiento e incidentes/depuración - Define cómo escalar: qué hacer cuando algo te impide avanzar o encuentras un estado inesperado

QUÉ NO HACER: - Incluir guías de estilo completas sin reglas de ejecución - Usar instrucciones ambiguas («ten cuidado», «optimiza») - Mezclar prioridades contradictorias (rapidez + verificación exhaustiva + ningún presupuesto de ejecución) - Escribir documentación explicativa (AGENTS.md es una política operativa, no un README)

Ejemplo: AGENTS.md para producción

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Gestión de secretos en las sesiones del agente

Trata el historial visible para Codex como una superficie de seguridad, no solo el código fuente. Las notas de las versiones de Codex documentan el trabajo realizado en las instantáneas del shell y la ocultación de variables de entorno, mientras que el sistema de memoria analiza la presencia de secretos en las escrituras de memoria. Sin embargo, estas protecciones no convierten la salida de los comandos, las transcripciones de sesiones, las instantáneas del shell, los registros locales ni los scripts auxiliares en lugares seguros para mostrar credenciales.³⁷⁵⁵⁹⁵

La regla operativa es sencilla: no muestres secretos para que el modelo los inspeccione; conserva las credenciales auxiliares en la configuración requerida por el entorno; durante las auditorías, separa el código fuente ejecutable, la documentación, las cachés generadas, las transcripciones de sesiones, las instantáneas del shell, los registros y los almacenes de secretos intencionales; oculta el historial local cuando aparezca un patrón que, con un alto grado de certeza, corresponda a un secreto; e incorpora hooks de prevención solo después de comprobar el proceso manual de higiene. La enseñanza pública es el mapa de superficies y los criterios de aceptación, no los valores privados de los tokens, las rutas exactas ni el funcionamiento interno de los detectores.⁹⁵

El mecanismo de sustitución

AGENTS.override.md en cualquier nivel del directorio sustituye al AGENTS.md normal en ese ámbito. Úsalo para:

• Congelamientos de versiones: «No se permiten funciones nuevas, solo correcciones»
• Modo de incidentes: «Todos los cambios deben ser revisados por la persona de guardia»
• Refuerzo temporal: «No se actualizarán dependencias durante este sprint»

Configuración

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Generación de la estructura inicial

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

O verifica tu cadena de instrucciones:

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex introdujo los hooks en v0.99.0 y v0.100.0 con los nombres heredados AfterAgent y AfterToolUse, añadió un motor experimental de hooks en v0.114.0 con SessionStart y Stop,⁷⁰ y estabilizó los hooks en v0.124.0 (23 de abril de 2026).⁸⁵ El motor incluido en rust-v0.150.0 registra doce eventos (HOOK_EVENT_NAMES en codex-rs/hooks/src/lib.rs): once en v0.149.1, con Interrupt añadido como el duodécimo en v0.150.0¹³²; además, los nombres heredados desaparecieron de la superficie configurable: AfterToolUse ya no aparece en ninguna parte del árbol de código fuente y AfterAgent solo permanece como nombre interno de la carga útil del puente heredado notify.¹²⁴ Los hooks ejecutan scripts o herramientas MCP durante el bucle agéntico. Se ejecutan todos los hooks coincidentes de varios archivos, los distintos hooks de comando que coinciden con un mismo evento se inician simultáneamente y cada hook no administrado debe revisarse y considerarse de confianza antes de ejecutarse.¹²⁴ v0.148.0 amplía el motor: los hooks pueden ejecutar comandos de forma asíncrona e invocar herramientas MCP: configura async = true en un controlador de comandos para que se ejecute en segundo plano mientras Codex continúa, o utiliza un controlador mcp_tool para acceder a los mismos servidores MCP que usa el agente.¹¹⁸¹²⁴

Eventos de hooks disponibles

Las herramientas alojadas, como WebSearch, no pasan por la ruta de hooks, y algunas rutas de herramientas especializadas pueden excluirse; según la propia descripción de OpenAI, son «una medida de protección útil, no un límite de aplicación completo».¹²⁴

Configuración de hooks

Los hooks se organizan en tres niveles —un evento, un grupo de patrones de coincidencia y uno o más controladores— y se encuentran en hooks.json (~/.codex/hooks.json, <repo>/.codex/hooks.json o el archivo hooks/hooks.json de un plugin) o se definen en línea en config.toml y requirements.toml. Los hooks locales del proyecto solo se cargan cuando la capa .codex/ del proyecto es de confianza.¹²⁴ La forma TOML en línea:

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

Campos del controlador: type (command o mcp_tool; los controladores prompt y agent se analizan, pero se omiten), command, timeout en segundos (600 de forma predeterminada; 1 segundo para SessionEnd, hasta un máximo de 3), statusMessage, additionalContextLimit (cuánto contenido de additionalContext llega al modelo antes de que Codex guarde el texto completo en el disco y envíe una vista previa), commandWindows (reemplazo exclusivo para Windows) y async. Los comandos se ejecutan con el cwd de la sesión como directorio de trabajo, por lo que los hooks locales del repositorio deben resolver las rutas a partir de git rev-parse --show-toplevel, en lugar de usar una ruta relativa como .codex/hooks/....¹²⁴

Revisión y confianza. Codex registra la confianza según el hash actual de cada hook no administrado; los hooks nuevos o modificados se marcan para revisión y se omiten hasta que se consideren de confianza. Ejecuta /hooks para inspeccionar las fuentes de los hooks, revisarlos, marcarlos como confiables o deshabilitar hooks individuales; cuando hay hooks pendientes de revisión al iniciar, Codex muestra una advertencia que remite a /hooks. Los hooks administrados provenientes del sistema, MDM, la nube o fuentes requirements.toml son de confianza por política y no pueden deshabilitarse desde el explorador de hooks del usuario. --dangerously-bypass-hook-trust ejecuta los hooks habilitados sin registrar la confianza de forma persistente durante una invocación, para procesos automatizados que validan las fuentes de los hooks por otros medios.¹²⁴

La salida stdout del hook SessionStart se incorpora al contexto del modelo, por lo que resulta ideal para inyectar información dinámica (fechas, nombres de ramas y variables de entorno) al inicio de la sesión.

Reproducción de patrones de hooks de Claude Code

Codex utiliza los mismos nombres de eventos que Claude Code para los eventos que implementa, por lo que la mayoría de las configuraciones de hooks pueden migrarse trasladando el JSON a hooks.json y marcándolo como confiable mediante /hooks:

Consejo para expertos: siguen incorporándose nuevos eventos de hooks en las versiones —v0.150.0 añadió el evento Interrupt (¹³²)—, así que consulta HOOK_EVENT_NAMES en codex-rs/hooks/src/lib.rs y el registro de cambios de Codex para ver la lista actual.

Explorador de hooks integrado en la TUI (v0.129.0): ejecuta /hooks en la TUI para descubrir los hooks disponibles, ver cuáles están activos y alternar hooks individuales sin editar config.toml. Resulta útil para diagnosticar un hook incluido en un plugin que no funciona correctamente o para deshabilitar temporalmente un linter PostToolUse durante una sesión de edición que requiera máxima concentración.⁸⁹

¿Qué es MCP (Model Context Protocol)? [EXPERIMENTAL]

MCP amplía las capacidades de Codex al conectarlo con herramientas y servicios externos. El grupo de comandos codex mcp está marcado actualmente como experimental, y los comandos y el formato de configuración pueden cambiar entre versiones. Codex admite dos tipos de transporte: STDIO (procesos locales) y Streamable HTTP (servidores remotos).¹¹

Cambios de MCP en v0.121.0: Ahora las herramientas se registran con un espacio de nombres, por lo que sus nombres aparecen en los listados como <server>:<tool> en lugar de nombres simples; actualiza cualquier script o prompt que use grep con nombres de herramientas sin calificar. Se incorporó un nuevo indicador supports_parallel_tool_calls en los MCP incluidos, lo que permite la ejecución paralela en los servidores que declaren admitirla. Los metadatos del estado del sandbox ahora se transmiten mediante los metadatos de las herramientas de MCP, de modo que los servidores puedan adaptar su comportamiento (por ejemplo, advertir si se ejecutan en un sandbox read-only). La solicitud personalizada codex/sandbox-state se eliminó; usa la ruta de metadatos en su lugar. La fase 3 del lanzamiento de Apps para MCP llega con compatibilidad para llamadas a herramientas; ahora también se admiten llamadas diferidas a herramientas aplanadas en los servidores que utilizan el patrón de llamadas diferidas.⁸²

Cambios de MCP en v0.142.2 (25 de junio de 2026): Las herramientas de MCP ahora usan la búsqueda de herramientas de forma predeterminada cuando es compatible; en lugar de cargar por adelantado la definición de cada herramienta, Codex las descubre según sea necesario, lo que mejora el descubrimiento en configuraciones con muchas herramientas sin perder compatibilidad con modelos y proveedores anteriores. Los servidores remotos de MCP mediante stdio también aceptan directorios de trabajo absolutos escritos con el formato de ruta de la plataforma remota (una ruta con formato de Windows desde un cliente macOS o viceversa).¹⁰⁵

Cambios de MCP en v0.147.0 (7 de agosto de 2026): Codex incorpora compatibilidad opcional con la revisión del protocolo MCP del 28 de julio de 2026: descubrimiento paginado (los catálogos grandes de herramientas se transmiten por páginas en lugar de usar un listado único de gran tamaño), solicitudes de varias rondas (un servidor puede mantener un intercambio de varios pasos dentro de una única solicitud lógica) e inicio no bloqueante del servidor, que permite exponer las herramientas de MCP almacenadas en caché antes de que el servidor termine de iniciarse, por lo que un servidor lento ya no retrasa el inicio de la sesión. Como es opcional, los servidores que usan la revisión anterior siguen funcionando sin cambios.¹¹⁶

Cambios de MCP en v0.151.0 (29 de agosto de 2026): Los servidores opcionales de MCP obtienen un período de gracia de inicio configurable: mcp_optional_startup_grace_ms (1.000 ms de forma predeterminada) controla cuánto espera la captura del catálogo de herramientas a los servidores opcionales; 0 desactiva el período de gracia compartido para que estos servidores recurran al valor configurado en startup_timeout_sec; y los valores actualizados se aplican durante la ejecución y al actualizar la configuración de MCP. Las extensiones también pueden inspeccionar o reemplazar los resultados de las herramientas de MCP antes de que lleguen al modelo: ToolLifecycleContributor::on_mcp_tool_result se ejecuta antes de publicar la finalización de MCP y de preparar el resultado para el modelo, tanto con resultados correctos como con errores, incluso mediante Code Mode.¹³⁴

Cambios de MCP en v0.152.0 (1 de septiembre de 2026): Se incorporan tres cambios aditivos. Llegan las solicitudes de formularios de openai/elicitation: Codex anuncia compatibilidad con formularios cuando el cliente declara una capacidad form cuyo valor es un objeto, gestiona las solicitudes openai/elicitation/create y reenvía sus metadatos y su esquema opaco mediante el servidor de la aplicación como openaiForm (conservando las anotaciones x-openai-*); la gestión anterior de openai/form permanece independiente y la TUI rechaza automáticamente las solicitudes de formularios que no puede mostrar. Límites de salida por herramienta: cada entrada de la configuración tools de un servidor de MCP acepta un valor positivo para output_token_limit (por ejemplo, [mcp_servers.context7.tools.search] con output_token_limit = 2000); cuando las políticas del plugin y del usuario se superponen, prevalece el límite más restrictivo, y el presupuesto efectivo se conserva en el historial de la conversación para que la salida de las herramientas, las respuestas de hooks posteriores a su ejecución y las sesiones reanudadas se trunquen con el mismo límite, de forma adicional al valor global tool_output_token_limit. Nombres de servidor con formato de paquete: los nombres de servidores de MCP ahora pueden contener :, @, / y . (por lo que npm:@modelcontextprotocol/server-sequential.thinking es un nombre válido), y se conservan en mcp add/get/list/remove, en los espacios de nombres de las herramientas durante la ejecución y en la búsqueda de credenciales de OAuth; además, los nombres que no son simples aparecen entre comillas en las sugerencias de recuperación generadas para config.toml.¹³⁸

Configuración de servidores de MCP

Servidores STDIO (procesos locales):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

Servidores HTTP (remotos):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

Administración mediante CLI

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

Durante una sesión, /mcp muestra los servidores activos y las herramientas disponibles. /mcp verbose (v0.123.0+)⁸⁴ devuelve diagnósticos completos de los servidores, recursos y plantillas de recursos, lo que resulta útil cuando un servidor no se carga o las herramientas no aparecen donde deberían. El comando /mcp sin opciones sigue siendo rápido. Desde la v0.144.0, las herramientas de MCP pueden solicitar autenticación de forma interactiva sin habilitar ninguna opción experimental: si un servidor requiere autenticación a mitad de una sesión, la solicita mediante el flujo habitual en lugar de generar un error hasta que te autentiques previamente con codex mcp login.¹⁰⁷

La carga de MCP desde plugins (v0.123.0+) acepta tanto el esquema estándar mcpServers como mapas de servidores de nivel superior en .mcp.json, por lo que los plugins creados con cualquiera de las dos convenciones se cargan correctamente.⁸⁴

Ejecución de Codex COMO servidor de MCP

Obsoleto (24 de agosto de 2026). Según el registro oficial de cambios: «El comando codex mcp-server ahora está obsoleto. Usa el servidor de aplicaciones de Codex en su lugar. Para usar Codex desde Claude Code, utiliza el plugin de Codex para Claude Code». Desde la v0.149.0, el binario imprime warning: `codex mcp-server` is deprecated and will be removed in a future release. en stderr y luego se inicia de todos modos (PR #39657). Las integraciones nuevas deben usar el protocolo app-server, la interfaz subyacente de la extensión de VS Code y la aplicación de escritorio (autenticación, historial de conversaciones, aprobaciones y eventos transmitidos del agente) o, desde Claude Code, el plugin de Codex para Claude Code: «Usa Codex desde Claude Code para revisar código o delegar tareas».¹²⁵

Mientras el comando siga existiendo, Codex todavía puede exponerse como servidor de MCP para la orquestación de múltiples agentes (está obsoleto, pero aún funciona en la versión 0.150.0, que muestra una advertencia explícita sobre su obsolescencia):^12125132

codex mcp-server                        # Start as MCP server (stdio transport); deprecated, prints a warning

El servidor expone dos herramientas: 1. codex(): Inicia una sesión nueva con parámetros de prompt, sandbox, modelo y aprobación 2. codex-reply(): Continúa una sesión existente con threadId y un prompt

Uso con SDK de Agents (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Servidores de MCP destacados

Patrones prácticos

Patrón 1: Desarrollo consciente del contexto — Combina Context7 con la documentación de tu framework para que Codex siempre tenga referencias actuales de API:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Patrón 2: Límites de salida — Las respuestas de las herramientas de MCP se truncan de forma predeterminada a unos 25.000 caracteres. Para las herramientas que devuelven grandes volúmenes de datos (consultas de bases de datos o capturas de registros), usa enabled_tools para restringir la respuesta a herramientas específicas y mantenerla enfocada.

Patrón 2a: Salida multimodal de herramientas (v0.107.0) — Las herramientas personalizadas ahora pueden devolver contenido multimodal (imágenes y contenido enriquecido) junto con texto. Esto permite que las herramientas que producen artefactos visuales —capturas de pantalla, diagramas o gráficos renderizados— los transmitan directamente al modelo para su análisis.⁶²

Patrón 3: Gobernanza empresarial de MCP — Restringe los servidores de MCP que pueden usar los desarrolladores mediante requirements.toml:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Todo servidor que no coincida con una identidad incluida en requirements.toml se bloqueará al iniciarse. Consulta Implementación empresarial para ver la configuración completa de políticas.

Code Mode [EXPERIMENTAL]

Code Mode (v0.114.0) ofrece flujos de trabajo de programación más aislados al restringir el alcance del agente a operaciones centradas en el código.⁷⁰ Cuando está habilitado, el agente se concentra en leer, escribir y probar código sin interactuar de forma más amplia con el sistema.

Desde v0.139.0, Code Mode puede realizar búsquedas web independientes directamente —incluso desde llamadas anidadas a herramientas de JavaScript— y recibe resultados en texto sin formato, por lo que un flujo de Code Mode puede obtener información actualizada sin salir del contexto de programación aislado.¹⁵⁵ v0.146.0 amplía la búsqueda web independiente a proveedores de modelos personalizados compatibles, de modo que esta capacidad ya no se limita a los modelos alojados por OpenAI.¹¹⁴

v0.146.0 permitió que app-server se conectara a hosts remotos de Code Mode, por lo que el entorno de ejecución de Code Mode ya no tenía que estar en la misma computadora que el cliente; originalmente, la conexión se realizaba mediante WebSocket.¹¹⁴ v0.151.0 elimina el transporte WebSocket (#40692): las conexiones --code-mode-host de app server solo aceptan endpoints gRPC http:// y https://, y el host independiente de Code Mode está limitado a listeners de stdio y gRPC; en la etiqueta rust-v0.151.0, la documentación de su listener dice textualmente “Transport endpoint: stdio, stdio://, or grpc://IP:PORT.” WebSocket se conserva únicamente como un endpoint opcional que transmite lotes sin procesar de trazas OTLP para rastreo, no como transporte de sesiones.¹³⁵

Esta función es experimental. Consulta las notas de la versión para conocer las novedades.

Entorno de ejecución REPL de JavaScript [REMOVED]

Codex v0.100.0 añadió un entorno de ejecución REPL experimental de JavaScript (js_repl), y v0.106.0 lo incorporó a la interfaz /experimental.⁶⁰ Esa orientación ahora es histórica. En v0.128.0, el registro de cambios de la versión incluye “Remove js_repl feature”, y la lista actual de funciones marca tanto js_repl como js_repl_tools_only como eliminados.⁸⁶

No añadas features.js_repl = true a configuraciones nuevas. Usa comandos de shell, scripts incluidos en el repositorio, herramientas de MCP o una skill de Codex con un directorio scripts/ cuando necesites lógica ejecutable y repetible.

¿Qué son las skills?

Las skills son paquetes reutilizables de capacidades específicas para tareas que Codex carga bajo demanda. Siguen el estándar abierto de agent skills.¹³

Estructura de una skill

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

Ubicaciones de detección

Codex almacena las skills instaladas por el usuario en $CODEX_HOME/skills (valor predeterminado: ~/.codex/skills), incluidas las skills integradas del sistema en .system/. Codex admite carpetas de skills enlazadas simbólicamente.

Crear una skill

Formato de SKILL.md:

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

Metadatos (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Invocar skills

• Explícita: menú /skills o mención de $skill-name en el prompt
• Implícita: Codex detecta automáticamente las skills que coinciden con la descripción de la tarea (si allow_implicit_invocation: true)
• Creador: usa $skill-creator para crear una skill nueva de forma interactiva
• Instalador: usa $skill-installer install <name> para instalar skills de la comunidad
• Proporcionada por el ejecutor (v0.146.0): Codex detecta las skills que ofrece el ejecutor y lee sus recursos asociados, incluidas las que selecciones explícitamente¹¹⁴

Los presupuestos de contexto truncan los catálogos de skills. v0.146.0 conserva más skills disponibles cuando el contexto es limitado y advierte cuando es necesario truncar un catálogo.¹¹⁴ Antes, una biblioteca grande de skills podía recortarse silenciosamente, por lo que una skill que esperabas tener disponible simplemente no se ofrecía. Si dependes de la invocación implícita entre muchas skills, presta atención a esa advertencia.

Habilitar/deshabilitar

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills frente a slash commands

Depurar skills

Si una skill no se activa:

1. Comprueba la detección: /skills debería mostrarla en la TUI
2. Verifica la ruta: asegúrate de que la carpeta de la skill esté en una ubicación reconocida (~/.codex/skills/, la raíz del proyecto o /etc/codex/skills/)
3. Comprueba enabled: las skills con enabled = false en config.toml no se cargarán
4. Comprueba la activación implícita: si dependes de la detección automática, asegúrate de que allow_implicit_invocation: true esté en agents/openai.yaml
5. Usa palabras clave: incluye en el prompt términos de la description de la skill para mejorar la coincidencia implícita

Ejemplo para producción: skill de despliegue

Una skill completa con varios archivos que muestra cómo funcionan en conjunto las referencias y los scripts:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Invócala con: $deploy to staging o $deploy production with canary rollout

Plugins

Los plugins unifican skills, entradas de MCP, hooks y conectores de aplicaciones en un único paquete instalable (v0.110.0+).⁶⁵ Desde la v0.117.0, los plugins son componentes de primera clase: los plugins asociados a productos se sincronizan automáticamente al iniciar y /plugins ofrece un navegador integrado en la TUI para descubrirlos y administrarlos.⁷⁵ La v0.128.0 amplió los flujos de trabajo de plugins con la instalación desde marketplaces, el almacenamiento en caché de paquetes remotos, APIs de desinstalación remota, hooks incluidos en plugins, el estado de activación de hooks y la importación de configuraciones de agentes externos.⁸⁶ La v0.129.0 (7 de mayo de 2026) incorpora la posibilidad de compartir plugins en el espacio de trabajo (enviar un conjunto de plugins a tus compañeros de equipo sin volver a publicarlo), controles de acceso al contenido compartido (activar o desactivar por destinatario y revocar el acceso), filtrado por origen (limitar los marketplaces de los que obtiene contenido un espacio de trabajo) y operaciones del marketplace que pueden ejecutarse directamente desde el navegador /plugins en lugar de hacerlo mediante la CLI.⁸⁹ La v0.133.0 (21 de mayo de 2026) facilita la auditoría del descubrimiento de plugins: el resultado del listado identifica cada marketplace, muestra las versiones instaladas y las raíces de los marketplaces, y permite presentar colecciones remotas de plugins sin tener que adivinar de qué registro proviene cada resultado.⁹⁸ La v0.130.0 (8 de mayo de 2026) aporta mayor transparencia al empaquetado de plugins y más control al flujo para compartirlos:⁹¹

• Hooks incluidos visibles en los detalles del plugin. La vista de detalles de /plugins ahora enumera todos los hooks del ciclo de vida incluidos en un plugin (SessionStart, UserPromptSubmit, Stop, etc.). Antes de instalarlo, puedes ver exactamente qué hooks registrará en tu sesión, lo que evita efectos secundarios inesperados de hooks en un plugin en el que solo confías por sus herramientas.
• Metadatos de plugins compartidos en shareContext. Cuando se comparte un plugin desde un espacio de trabajo, la carga útil del enlace compartido ahora expone sus metadatos (creador, alcance y vigencia), de modo que las sesiones receptoras puedan mostrar su procedencia y decidir si lo aceptan.
• Controles de visibilidad en la configuración para compartir. La configuración para compartir incluye una opción de visibilidad que permite a los equipos publicar plugins en espacios de trabajo o listas de destinatarios específicos sin hacer que aparezcan de forma general en toda la organización.

La v0.143.0 (8 de julio de 2026) activa los plugins remotos de forma predeterminada. Ahora están habilitados sin una opción de activación explícita, el catálogo de /plugins incorpora filas con más información (incluidos marketplaces npm, además de fuentes git y locales) y cada entrada muestra tanto la versión remota como la instalada localmente, para que cualquier divergencia sea visible de inmediato.¹⁰⁶ Para un equipo que busca estandarizar un conjunto compartido de plugins, su activación remota predeterminada elimina el paso de habilitación en cada máquina que antes retrasaba la implementación.

Fuentes de plugins

Desde la v0.147.0, la búsqueda de plugins abarca los catálogos locales, personales, del espacio de trabajo y remotos con una sola consulta: buscas una capacidad, no el catálogo específico que la contiene. En combinación con los paquetes portátiles de Agent Plugins, un plugin creado en un entorno puede instalarse sin problemas en otro, en lugar de quedar vinculado a la máquina o al espacio de trabajo donde se creó.¹¹⁶

Descubrimiento de plugins

Codex indica al modelo qué plugins están habilitados al comienzo de la sesión (v0.111.0), lo que facilita el descubrimiento de MCPs, aplicaciones y skills instalados.⁶⁵ El modelo puede sugerir plugins relevantes durante una sesión según el contexto de la tarea. En la v0.117.0, los plugins asociados a productos se sincronizan al iniciar, lo que garantiza que el catálogo más reciente esté disponible sin intervención manual.⁷⁵ Desde la v0.142.0, el menú /plugins organiza los plugins remotos en las secciones Selección de OpenAI, Espacio de trabajo y Compartidos conmigo, y los turnos que cumplen los requisitos pueden recomendar e instalar directamente plugins pertinentes.¹⁰⁴ Desde la v0.151.0, plugin/list y plugin/installed cargan la configuración efectiva de plugins para cada cwd solicitado: los marketplaces locales se combinan en el orden de la solicitud, los estados de instalación y activación se integran entre repositorios, y las configuraciones de proyecto no válidas se informan mediante marketplaceLoadErrors sin descartar los catálogos locales válidos ni los catálogos remotos habilitados globalmente.¹³⁴

Menciones @plugin (v0.112.0+)

Haz referencia a cualquier plugin instalado directamente en el chat mediante @plugin-name.⁶⁸ Cuando mencionas un plugin, su contexto (capacidades, herramientas y configuración) se incluye automáticamente en la ventana de contexto del modelo, sin que tengas que describir qué hace.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

Esto funciona con cualquier plugin instalado, incluidos skills personalizados, servidores de MCP y conectores de aplicaciones.

Marketplace de plugins (v0.113.0+)

El marketplace de plugins ahora permite un descubrimiento más completo mediante metadatos, categorías y calificaciones.⁶⁹ Las comprobaciones de autenticación durante la instalación verifican que los plugins que requieren claves de API o OAuth tengan credenciales válidas antes de instalarlos. Un endpoint de desinstalación elimina correctamente los plugins y su configuración asociada.

Incorporación de marketplaces de terceros (v0.121.0+)

La documentación actual de OpenAI Codex mantiene la administración de fuentes de marketplaces bajo codex plugin marketplace. Esto formaliza la distribución de plugins de terceros más allá del marketplace propio de OpenAI y admite la notación abreviada de repositorios de GitHub, URL de Git mediante HTTP(S), URL de SSH y directorios raíz de marketplaces locales; usa --ref para fijar una referencia de Git y repite --sparse PATH únicamente para repositorios de marketplaces basados en Git.⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

Una vez agregados, los plugins de un marketplace aparecen en el navegador /plugins junto con los predeterminados. Los clientes del servidor de aplicaciones (integraciones con IDE o aplicaciones de escritorio) disponen de un endpoint equivalente para registrar marketplaces mediante programación.⁸²

Consideración de seguridad: Los marketplaces de terceros ejecutan código arbitrario de plugins con tus permisos de Codex. Verifica las fuentes antes de agregarlas y, durante las primeras ejecuciones, prefiere un entorno aislado.

Agent Plugins: el estándar compatible con múltiples proveedores (v0.146.0–v0.147.0)

“Agent Plugins” no es solo el nombre de una función de Codex: es un estándar de empaquetado abierto y neutral respecto al proveedor, publicado como Agent Plugins 1.0.0 el 6 de agosto de 2026, cuyo sitio oficial lo resume como «un formato de paquete portátil para componentes reutilizables que amplían agentes de IA».¹⁵¹ Un plugin es un directorio con un manifiesto plugin.json obligatorio (un esquema cerrado con exactamente diez campos de nivel superior permitidos: $schema, name, version, description, author, homepage, repository, license, keywords, extensions; los clientes «DEBEN informar e ignorar cada campo desconocido»), una carpeta skills/ opcional (cada directorio secundario inmediato que contenga un SKILL.md constituye un skill), un archivo mcp.json opcional que declare servidores stdio, Streamable HTTP o HTTP+SSE heredados, y directorios opcionales con espacios de nombres de cliente en formato de dominio inverso que otros clientes «DEBEN ignorar». Su alcance normativo es el empaquetado: la especificación «define la especificación canónica Agent Plugins v1.0.0 para empaquetar componentes reutilizables que amplían agentes de IA como plugins distribuibles»; Agent Skills y MCP conservan sus propias especificaciones subyacentes.¹⁵¹

La gobernanza es el aspecto central. Vercel inició la propuesta y desarrolló la especificación 1.0 con Amazon, Anysphere (Cursor), GitHub, Microsoft y OpenAI; la lista de responsables del repositorio de la especificación incluye representantes de Amazon, Cursor, Microsoft, OpenAI y Vercel, y Google anunció el día del lanzamiento que se incorporaría al grupo principal de responsables.¹⁵¹ Entre los clientes mencionados en el lanzamiento se encuentran ChatGPT, Codex, Cursor, GitHub Copilot, Kiro y VS Code. Hay una ausencia notable: Anthropic, creador del formato Agent Skills subyacente y del propio MCP, no figura entre los responsables; Claude Code mantiene su propio formato de plugins, y Codex cubre esa brecha desde su lado mediante la fuente de marketplace de Claude Code (v0.146.0) y /import.¹⁵¹

En términos de Codex: la v0.146.0 incorpora manifiestos de Agent Plugins, la publicación de plugins en espacios de trabajo y dos marketplaces de plugins adicionales: Amazon Bedrock y Claude Code¹¹⁴; la v0.147.0 completa el circuito con la instalación de Agent Plugins portátiles y la búsqueda en catálogos locales, personales, del espacio de trabajo y remotos.¹¹⁶ Para los equipos, la publicación en el espacio de trabajo es la parte más útil en términos operativos: permite publicar plugins en su propio espacio de trabajo sin tener que crear un marketplace público ni pedir a cada desarrollador que agregue manualmente una fuente de Git.

Las notas de la versión anuncian las interfaces de Codex sin publicar sus claves de configuración ni la sintaxis de la CLI. Esta entrada registra la incorporación de la capacidad y lo que especifica el estándar, no cómo utilizarla desde Codex; considera que tanto el flujo para crear manifiestos como cualquier invocación de codex plugin publish permanecen sin verificar hasta que la documentación de OpenAI los describa.

Administración de plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

La v0.153.0 amplía la CLI de plugins, que pasa de administrar marketplaces a permitir operaciones sobre plugins individuales en marketplaces remotos: codex plugin list incluye entradas del catálogo remoto (con su fuente, versión, política de instalación y política de autenticación en la salida de JSON), y los plugins remotos pueden agregarse y eliminarse mediante la CLI existente para plugins. Los catálogos remotos se almacenan en caché según su alcance y colección: se prefieren los resultados recientes almacenados en caché; si una solicitud para agregar un plugin no lo encuentra allí, se vuelve a obtener el catálogo una vez; y el catálogo seleccionado local se conserva cuando falla un listado remoto sin filtrar, aunque los errores siguen mostrándose para los marketplaces remotos seleccionados explícitamente.¹⁴⁰

En la TUI, usa /plugins (v0.117.0+) para explorar, instalar y eliminar plugins individuales de forma interactiva sin salir de la sesión.⁷⁵

Consejo para expertos: Los plugins consolidan lo que antes requería configurar MCP, instalar skills y preparar conectores de aplicaciones por separado. Un solo plugin puede incluir los tres, lo que agiliza la incorporación de equipos y facilita trasladar la configuración.

Modo de planificación y colaboración

El modo de planificación permite que Codex diseñe un enfoque antes de ejecutar cambios. Está habilitado de forma predeterminada (desde la versión v0.94.0).¹⁴ Consulta Marcos de decisión para ver el árbol de decisión «Modo de planificación frente a ejecución directa».

Modo de planificación frente a la herramienta update_plan (v0.152.0): son dos cosas distintas y solo una está activada de forma predeterminada. El modo de planificación —el modo de colaboración descrito en esta sección, en el que Codex hace una propuesta antes de ejecutarla— está habilitado de forma predeterminada desde la versión v0.94.0 y no ha cambiado. update_plan es una herramienta de planificación que el modelo puede invocar para mantener un plan estructurado durante un turno, y se lanzó como opción voluntaria en la versión v0.152.0: tools.update_plan.enabled tiene el valor predeterminado false y, mientras está deshabilitada, Codex también elimina las indicaciones incluidas sobre update_plan de sus prompts del modelo, el modo de colaboración, el sistema multiagente, la compactación, el precalentamiento y la continuación de objetivos (las instrucciones base personalizadas, las instrucciones del catálogo de modelos, las políticas de colaboración y el texto de los objetivos del usuario se conservan aunque mencionen la planificación). Habilítala explícitamente con tools.update_plan.enabled = true en config.toml.¹³⁸

Cómo entrar al modo de planificación

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

En el modo de planificación, Codex: - Lee archivos y analiza el código base - Propone un plan de implementación - No realiza cambios hasta que los apruebes - Transmite el plan en una vista exclusiva de la TUI

Modo Steer

El modo Steer (habilitado de forma predeterminada desde la versión v0.98.0) te permite introducir instrucciones nuevas mientras Codex trabaja activamente, sin interrumpir su tarea actual.¹⁴

Hay dos métodos para introducir instrucciones:

Ejemplos prácticos:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

El modo Steer siempre está activo en la TUI. Si prefieres esperar a que Codex termine antes de darle instrucciones, simplemente escribe con normalidad cuando finalice el turno; no necesitas ningún modo especial.

Mejoras de la TUI (v0.105.0–v0.106.0)

Resaltado de sintaxis (v0.105.0): La TUI ahora resalta la sintaxis de los bloques de código delimitados y las diferencias integradas en el texto. Usa /theme para elegir un esquema de colores.⁶¹

Nuevos comandos de la TUI (v0.105.0+):⁶¹

Transcripción de voz (v0.105.0, experimental): Presiona la barra espaciadora para dictar prompts mediante la transcripción de voz. Esta función es experimental y puede requerir permisos para usar el micrófono.⁶¹ A partir de la versión v0.107.0, las sesiones de voz en tiempo real permiten seleccionar los dispositivos de micrófono y altavoz, por lo que puedes elegir un hardware específico de entrada y salida de audio.⁶² Se eliminó en la versión v0.140.0 y regresó en la v0.145.0: los controles de voz experimentales de /realtime y sus dependencias de audio se eliminaron de la TUI en la versión v0.140.0 (la transcripción de voz mediante la barra espaciadora no se vio afectada).¹⁰² La versión v0.145.0 recupera la voz de una forma nueva: entradas de audio y salidas de herramientas de audio en formatos de audio locales comunes, además de conversaciones V3 en tiempo real mediante streaming.¹¹²

Otras mejoras: - Los enlaces largos ahora permanecen activos aunque se dividan entre varias líneas de la TUI (v0.105.0)⁶¹ - Los enlaces a archivos locales se muestran con un formato mejorado (v0.106.0)⁶⁰ - Los enlaces web del Markdown de la TUI permanecen activos mediante metadatos OSC 8, y las tablas con poco espacio adoptan un formato alternativo de registros legibles de clave/valor sin perder los destinos de los enlaces (v0.136.0)¹⁵⁸ - Los enlaces de Markdown aparecen como etiquetas en las que se puede hacer clic en las terminales compatibles, mientras que las URL permanecen visibles en las demás (v0.150.0)¹³² - Se corrigió el manejo de Ctrl+C para que los subagentes terminen correctamente los procesos secundarios (v0.106.0)⁶⁰

Sistema de memoria

Codex cuenta con un sistema de memoria persistente (v0.100.0+) que almacena datos, preferencias y contexto del proyecto entre sesiones.²⁴

Comandos de memoria

Las memorias se almacenan en archivos Markdown dentro de ~/.codex/memory/. Codex las carga al inicio de la sesión y las utiliza para orientar su comportamiento en todas las sesiones futuras.

Qué almacenar

Las memorias funcionan mejor para preferencias persistentes y datos del proyecto:

• Convenciones del proyecto: «Este proyecto usa tabulaciones, no espacios» o «Las respuestas de API siempre incluyen un campo meta»
• Preferencias de herramientas: «Usa pnpm en lugar de npm» o «Ejecuta las pruebas con pytest -x --tb=short»
• Decisiones de arquitectura: «El módulo de autenticación está en src/core/auth/, no en src/middleware/»
• Preferencias del flujo de trabajo: «Ejecuta siempre el linter antes de mostrarme las diferencias»

Memoria en pipelines

Cuando ejecutas codex exec, las memorias se cargan automáticamente. Esto significa que los pipelines de CI/CD y los scripts se benefician del mismo contexto que las sesiones interactivas, sin necesidad de repetir las instrucciones en cada ejecución.

Mejoras de la memoria (v0.101.0–v0.107.0)

• Depuración de secretos: Las memorias se analizan automáticamente para detectar secretos antes de escribirlas en el disco
• Conocimiento del CWD: Los archivos de memoria ahora incluyen el contexto del directorio de trabajo para recordar información específica del proyecto
• Exclusión de mensajes del desarrollador: Los mensajes del desarrollador y del sistema se excluyen de la entrada de memoria de la fase 1, lo que mejora la calidad de la memoria al centrarse en las interacciones del usuario
• Olvido basado en diferencias (v0.106.0): La memoria ahora utiliza un sistema de olvido basado en diferencias para eliminar datos obsoletos, lo que mantiene el almacén de memoria compacto y pertinente con el paso del tiempo⁶⁰
• Selección basada en el uso (v0.106.0): La recuperación de memorias ahora tiene en cuenta el uso y prioriza las memorias consultadas con frecuencia y las que han sido pertinentes recientemente⁶⁰
• Memorias configurables (v0.107.0): Ahora las memorias son totalmente configurables. Usa codex debug clear-memories para restablecer todas las memorias almacenadas y comenzar desde cero; resulta útil al cambiar de contexto entre proyectos no relacionados o cuando el estado de la memoria se ha desviado⁶²
• Actualización del modelo de la fase 2 (v0.121.0): El modelo de consolidación de memoria de la fase 2 ahora es gpt-5.4 (en lugar del modelo predeterminado anterior). El pipeline de la fase 2 se ejecuta entre sesiones para condensar las transcripciones de la fase 1 en datos duraderos; el cambio de modelo mejora la calidad de la recuperación con el mismo costo de tokens.⁸²
• Menú de memorias de la TUI (v0.121.0): Una nueva interfaz dentro de la sesión permite acceder al modo de memoria, eliminar memorias específicas y usar un botón de restablecimiento. Ahora, al restablecer la memoria, se conservan las ejecuciones anteriores en lugar de invalidarlas, por lo que el restablecimiento borra la información que podría recuperarse en el futuro sin afectar la reproducción de las sesiones.⁸²

Memoria frente a AGENTS.md

Consejo: Usa /m_update para los datos que deban conservarse indefinidamente. Para el contexto específico de una sesión, simplemente indícaselo a Codex directamente en la conversación. Para el contexto compartido con el equipo, usa AGENTS.md.

Gestión de sesiones

Codex conserva las sesiones en ~/.codex/sessions/, lo que permite reanudarlas, bifurcarlas y trabajar con varios hilos tanto en CLI como en las interfaces de escritorio.

v0.146.0 permite identificar los hilos por nombre. /new y /clear ahora aceptan un nombre de sesión, los hilos importantes pueden fijarse y las conversaciones secundarias permanecen abiertas, por lo que ya no tienes que cerrar una para acceder a otra.¹¹⁴ En la práctica, un proyecto de larga duración deja de ser una lista de marcas de tiempo que debes reconocer por la fecha. v0.147.0 incorpora secciones de conversaciones: las conversaciones se organizan en secciones persistentes que pueden ordenarse manualmente, y las transcripciones extensas se recorren de forma incremental en lugar de cargarse por completo.¹¹⁶ v0.148.0 incorpora /export y la bifurcación desde la línea de comandos: /export guarda la conversación completa en Markdown (en el portapapeles o en un archivo nuevo), codex exec fork bifurca una sesión de forma no interactiva y el selector de reanudación permite archivar y restaurar sesiones.¹¹⁸ v0.149.0 incorpora codex queue —envía mensajes a sesiones locales o remotas existentes desde la línea de comandos— y corrige los hilos reanudados o bifurcados para que restauren su perfil de permisos activo.¹²⁰ v0.150.0 incorpora títulos automáticos: las tareas de terminal sin nombre reciben automáticamente títulos descriptivos, y /rename sugiere un título editable basado en la conversación.¹³² v0.151.0 incorpora /recap: solicita cuando quieras un breve resumen del progreso reciente de la conversación y de los próximos pasos; Codex también genera automáticamente el mismo resumen para las conversaciones elegibles que estén inactivas y sin enfocar, y lo agrega a la transcripción mediante solicitudes acotadas y aisladas, con reintentos únicamente cuando falla la generación automática.¹³⁵ v0.153.0 hace opcional la parte automática: tui.auto_recap = false cancela las comprobaciones automáticas programadas de recapitulación y descarta los resultados automáticos pendientes, mientras que /recap manual sigue funcionando.¹⁴⁰

codex agents (v0.149.0) es el panel interactivo para todas las sesiones de agentes activas en la computadora: desde una sola pantalla puedes buscar, iniciar, abrir, renombrar y detener tareas, con atajos configurables. Dentro de una sesión, /agents permite cambiar entre todas las sesiones de agentes activas y /subagents entre los subagentes de la sesión actual.¹²⁰¹²⁹ v0.150.0 permite identificar las tareas desde la conversación: haz referencia a otras tareas de Codex mediante menciones con @ y pide a los agentes que lean, creen o envíen mensajes a tareas desde la terminal.¹³²

Reanudar

Retoma el trabajo donde lo dejaste:

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

El slash command /resume dentro de la TUI abre el mismo selector interactivo con búsqueda.

Historial paginado de hilos (v0.145.0, promovido en v0.151.0): El historial paginado de hilos mejora la eficiencia al reanudar sesiones, buscar en el historial, conservar los nombres de los hilos, admitir subagentes y gestionar recuerdos: el historial se carga página por página en lugar de hacerlo todo de una vez, algo importante para directorios de trabajo de larga duración con cientos de sesiones. Se introdujo como función experimental en v0.145.0; v0.151.0 retira los APIs de la fase experimental (thread/turns/list, thread/items/list y thread/revert ya no necesitan la capacidad experimental de API) y establece el modo paginado como valor predeterminado resuelto SOLO para hilos duraderos cuyo almacenamiento admita thread/turns/list y thread/items/list, y únicamente cuando thread/start omita historyMode. Los hilos efímeros y los respaldados por sistemas de almacenamiento que no admiten esos APIs siguen usando el modo heredado de manera predeterminada, las selecciones explícitas mantienen su comportamiento y la enumeración ThreadHistoryMode a nivel de protocolo todavía usa Legacy como valor predeterminado en la etiqueta rust-v0.151.0 (protocol.rs:755-758): se trata de un valor predeterminado resuelto para los hilos duraderos compatibles, no de un cambio generalizado.¹¹²¹³⁵

Bifurcar

Bifurca una conversación para explorar alternativas sin perder tu progreso actual:

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Las bifurcaciones crean hilos independientes que comparten el mismo historial hasta el punto de bifurcación. Desde v0.146.0, el historial de las bifurcaciones está paginado y estas pueden crearse como temporales: una bifurcación temporal no aparece en las listas de hilos, lo que evita que los experimentos desechables saturen la lista que realmente utilizas para navegar.¹¹⁴ Los cambios realizados en una bifurcación no afectan a la otra. Esto resulta útil para comparar enfoques (por ejemplo, «bifurca y prueba Redis en lugar de Memcached») o explorar cambios riesgosos de forma segura.

Bifurcación de hilos en subagentes (v0.107.0): Ahora los hilos pueden bifurcarse en subagentes independientes, lo que permite que una conversación genere flujos de trabajo paralelos que se ejecutan de manera autónoma. Esto amplía el modelo de bifurcación existente: en vez de limitarse a ramificar la conversación, el hilo bifurcado se convierte en un subagente con su propio contexto de ejecución.⁶² Desde v0.117.0, los subagentes usan direcciones basadas en rutas (por ejemplo, /root/agent_a) y mensajería estructurada entre agentes, lo que hace que la coordinación multiagente sea más explícita y fácil de depurar.⁷⁵

Mensajes cifrados entre agentes (v0.138.0+): Multi-agent v2 ahora cifra el texto de la tarea que un agente principal envía al generar o enviar mensajes a un subagente. Los parámetros de mensaje de spawn_agent, send_message y followup_task se marcan como cifrados: la API cifra la carga útil cuando el modelo principal emite la llamada a la herramienta, la instancia local de Codex solo transporta el texto cifrado (InterAgentCommunication.encrypted_content, con el contenido de texto sin cifrar vacío) y la API lo descifra del lado del servidor al entregárselo al modelo receptor.¹⁰⁸ Esto tiene tres consecuencias prácticas:

• Los registros de tu sesión local ya no contienen el texto sin cifrar de las delegaciones. Puedes ver que un agente principal generó un subagente y qué respuesta recibió, pero no la instrucción exacta que envió. Si auditas o depuras ejecuciones multiagente a partir del historial de sesiones, ese registro ya no está disponible; el problema de regresión abierto que hace seguimiento de esto no tiene ninguna corrección vinculada a mediados de julio de 2026.¹⁰⁹ Los eventos del ciclo de vida de las extensiones (inicio y detención de subagentes, ejecución de herramientas y metadatos de los turnos, desde v0.133.0) y la observabilidad del servidor de aplicaciones siguen siendo los mecanismos disponibles para reconstruir lo ocurrido.⁹⁸
• Los modelos de proveedores personalizados pueden dejar de funcionar. Un endpoint de modelo que no esté configurado para usar herramientas cifradas rechaza el esquema cifrado de spawn_agent con un error 400 ("declares encrypted parameters but is not configured for encrypted tool use"). Si la delegación multiagente falla con ese error al usar un proveedor personalizado, la causa es el cambio de cifrado, no tu configuración.¹⁰⁹
• Las notificaciones generadas por Codex siguen siendo legibles. Codex genera las notificaciones de finalización de los agentes secundarios, por lo que permanecen como texto sin cifrar y ahora se muestran como elementos agent_message tipados en lugar de sobres JSON serializados.¹⁰⁸

OpenAI no ha publicado el modelo de amenazas que motivó el cambio; el PR describe el flujo del texto cifrado, pero no indica contra qué protege.

Multi-agent v2 estabilizado (v0.145.0, opcional): La experiencia Multi-agent v2, que debutó en v0.137.0 e incorporó la delegación cifrada en v0.138.0, ahora está estabilizada como función opcional. v0.145.0 incorpora modelos configurables para los subagentes, niveles de razonamiento por subagente, concurrencia configurable, roles multiagente restaurados y mejoras en la navegación entre agentes. Si decidiste no adoptar v2 durante el período de ajustes de v0.137/v0.138, esta es la versión en la que se consolida la configuración: ahora el modelo y el nivel de razonamiento de los subagentes se definen en la configuración en lugar de estar fijados por el entorno de ejecución.¹¹²

Lista de hilos

Consulta y administra las sesiones activas:

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

En la aplicación de escritorio, los hilos aparecen en la barra lateral con el historial completo y vistas previas de las diferencias.

Ciclo de vida de las sesiones

Las sesiones se sincronizan entre CLI y la aplicación de escritorio: comienza en una y continúa en la otra.

Modo no interactivo (codex exec)

codex exec ejecuta Codex de forma no interactiva para scripts, CI/CD y automatización.¹⁵

Uso básico

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
codex exec --json "triage open bugs" -o result.txt

De forma predeterminada, codex exec escribe el progreso y los eventos en stderr, y el mensaje final del agente en stdout. Este diseño permite integrarlo con las canalizaciones estándar de Unix.

Archivado de sesiones (v0.136.0)

Las sesiones pueden archivarse para mantener enfocada la lista de reanudaciones y bifurcaciones sin eliminar el historial. Archiva una sesión desde la TUI con /archive o desde el shell:¹⁵⁸

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

Una sesión archivada queda protegida contra operaciones de reanudación o bifurcación hasta que la desarchives, lo que evita que continúes por accidente una sesión que querías retirar. En la misma versión, codex app-server --stdio inicia app-server en modo stdio para integraciones con editores o hosts, y ahora se impide que /diff ejecute asistentes de Git proporcionados por el repositorio (una corrección de seguridad para comandos). En Windows, una ruta de aprovisionamiento alfa incorpora codex sandbox setup --elevated para administradores.¹⁵⁸

Salida en líneas JSON

Con --json, stdout se convierte en un flujo de eventos JSONL:

codex exec --json "fix the tests" | jq

Tipos de eventos: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Salida estructurada

Impón la estructura de la respuesta mediante un esquema JSON:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message escribe el mensaje final en un archivo.

Reanudación y revisión de sesiones

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Opciones principales

Autenticación en CI

codex exec admite CODEX_API_KEY para la autenticación no interactiva en entornos de automatización.

Mensaje de inicio de codex exec (v0.130.0). El mensaje de inicio de codex exec ya no muestra la antigua frase “research preview”. Si tu CI analiza la salida de inicio, el texto del mensaje ahora es más breve; los eventos estructurados de --json no cambiaron.⁹¹

codex remote-control (v0.130.0+)

codex remote-control es un comando de nivel superior que inicia un app-server sin interfaz gráfica, diseñado para ser controlado por otro proceso, como extensiones de IDE, orquestadores personalizados o planos de control remoto. Sustituye la invocación de codex app-server con múltiples opciones que muchos integradores componían manualmente y ofrece a las herramientas de terceros un único punto de entrada estable al mismo entorno de ejecución de app-server incluido en las interfaces de escritorio e IDE.⁹¹ La versión v0.133.0 mejora la forma de ejecución del comando: puede funcionar como un comando en primer plano, esperar hasta estar listo, informar el estado de la máquina y, aun así, ofrecer los comandos explícitos de tipo daemon start / stop para configuraciones de controladores de larga duración.⁹⁸ La versión v0.143.0 incorpora codex remote-control pair, que genera un código de vinculación manual desde un daemon en ejecución para que un controlador pueda conectarse sin el protocolo de detección automática; resulta útil cuando el proceso controlador se encuentra en un host o segmento de red distinto al del daemon.¹⁰⁶

# Start a headless, remotely controllable app-server
codex remote-control

# Generate a manual pairing code for an out-of-band controller (v0.143.0+)
codex remote-control pair

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

Combina codex remote-control con las APIs de paginación de app-server que aparecen a continuación cuando desarrolles interfaces de usuario que necesiten enumerar historiales extensos de hilos sin cargar todos los turnos en la memoria de una sola vez.

Paginación de hilos de app-server (v0.130.0+)

Los clientes de app-server ahora pueden paginar hilos extensos mediante 3 vistas distintas de los elementos de los turnos:⁹¹

Combina la paginación con la interfaz ThreadStore, introducida en la versión v0.121.0, para recorrer de manera eficiente los hilos de larga duración, en especial en implementaciones de control remoto donde el orquestador puede encontrarse en una máquina distinta a la de los archivos de ejecución.⁸² La versión v0.143.0 amplía lo que un controlador puede inspeccionar: los clientes de app-server ahora pueden enumerar los entornos disponibles, listar los hilos descendientes de un hilo y bifurcar el historial a partir de un turno específico; son las operaciones fundamentales que necesita una interfaz de usuario para ramificar una ejecución desde un punto anterior sin reproducirla hasta allí.¹⁰⁶ La versión v0.151.0 saca del estado experimental las APIs del historial paginado de hilos y, cuando thread/start omite historyMode, utiliza de forma predeterminada el historial paginado para los hilos persistentes cuyos almacenes lo admiten (los hilos efímeros y los almacenes incompatibles conservan el comportamiento anterior); la carga del historial completo está obsoleta para los hilos paginados (#40676).¹³⁵

Actualización en vivo de la configuración de app-server (v0.130.0+)

Los hilos activos de app-server ahora incorporan los cambios de config.toml sin necesidad de reiniciarse: edita la configuración, guárdala y el hilo en ejecución reflejará los nuevos valores en su siguiente turno. Esta corrección complementa a codex remote-control: un servidor sin interfaz gráfica y de larga duración puede reconfigurarse en funcionamiento, sin tener que detenerlo.⁹¹

Configuración activa limitada al turno (v0.151.0): ahora es posible cambiar la configuración de un turno en ejecución mientras está en curso. El método experimental turn/settings/update de app-server actualiza model, effort, summary y serviceTier para los pasos posteriores de un turno activo específico sin modificar los turnos futuros, e informa si la actualización se aplicó, se rechazó o dejó de encontrar su destino; las restricciones administradas se vuelven a validar y se preservan las propiedades de aprobación admitidas y de seguridad de Guardian del turno antes de publicar una instantánea actualizada de la configuración. turn/start también acepta serviceTierForTurn, lo que permite que un turno nuevo anule el nivel de servicio sin modificar el nivel guardado del hilo (“default” indica velocidad estándar; si se omite o se usa null, se hereda el nivel del hilo).¹³⁵

Ejecutores remotos cifrados (v0.141.0)

Desde la versión v0.141.0 (estable, 18 de junio de 2026), los ejecutores remotos se conectan mediante canales Noise-relay autenticados y cifrados de extremo a extremo. El plano de control y el ejecutor ya no necesitan confiar en el relay situado entre ambos, algo importante cuando tu orquestador controla un app-server a través de un límite de red. La misma versión hizo que la ejecución remota multiplataforma preserve el directorio de trabajo y el shell nativos del ejecutor, por lo que un controlador de un sistema operativo que gestiona un ejecutor de otro ya no modifica implícitamente las rutas ni la semántica del shell. TLS ahora también acepta firmas de certificados P-521 para ofrecer compatibilidad con proxies empresariales.¹⁰³

Codex Cloud y tareas en segundo plano [EXPERIMENTAL]

Compatibilidad con GitLab (beta, 19 de agosto de 2026): Codex cloud ahora permite conectar proyectos de GitLab en todos los planes de ChatGPT: vincula un proyecto, crea entornos, inicia tareas desde incidencias y solicitudes de fusión, y solicita revisiones; Self-Managed GitLab requiere la versión 19.0 o posterior.¹¹⁹

Estado: Codex Cloud es una función experimental. Las interfaces, los precios y la disponibilidad pueden cambiar. OpenAI administra los entornos en la nube y tú no controlas la infraestructura.

Codex Cloud ejecuta tareas de forma asíncrona en entornos administrados por OpenAI.⁴ A partir de CLI v0.150.0, también es posible interactuar con las tareas desde una conversación en la terminal: haz referencia a otras tareas de Codex mediante menciones con @ y pide a los agentes que lean, creen tareas o les envíen mensajes.¹³² Consulta también Acción de GitHub y CI/CD para integrar Codex en tu pipeline de CI.

Refuerzo de las credenciales de las tareas en la nube (v0.152.0): las solicitudes de tareas en la nube pueden incluir credenciales guardadas de ChatGPT, por lo que ahora su destino se restringe incluso antes de cargar la autenticación: CODEX_CLOUD_TASKS_BASE_URL se valida con respecto a los orígenes de HTTPS de confianza de ChatGPT en el puerto 443 (se rechazan las URLs que contienen información de usuario, consultas o fragmentos), y se deshabilitan las redirecciones tanto para el backend de tareas en la nube como para los clientes de detección de entornos, de modo que las credenciales nunca se reenvíen al destino de una redirección.¹³⁸

Cómo funciona

1. Envía una tarea (mediante chatgpt.com/codex, la integración con Slack o CLI)
2. Codex clona tu repositorio en un sandbox aislado en la nube
3. El agente trabaja de forma independiente: lee el código, ejecuta pruebas y realiza cambios
4. Al terminar, Codex crea una PR o proporciona un diff para su revisión
5. Aplica los resultados localmente con codex apply <TASK_ID>

Acceso a Internet en la nube

El acceso del agente a Internet está desactivado de forma predeterminada y se configura en cada entorno:

• Desactivado: el agente no tiene acceso a Internet (opción predeterminada)
• Activado: lista opcional de dominios permitidos + restricciones de métodos HTTP

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Los scripts de configuración pueden seguir usando Internet para instalar dependencias, incluso cuando el acceso del agente a Internet está desactivado.

Integración con Slack

Menciona a @Codex en un canal o hilo de Slack para iniciar una tarea en la nube.

Requisitos previos: 1. Un plan de ChatGPT compatible (Plus, Pro, Business, Enterprise o Edu) 2. Una cuenta de GitHub conectada 3. Al menos un entorno en la nube configurado 4. La aplicación de Slack instalada en tu espacio de trabajo

Codex responde con un enlace a la tarea y publica los resultados cuando termina.

CLI en la nube

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

La aplicación de escritorio de Codex

La aplicación de escritorio de Codex (macOS y Windows) ofrece una interfaz gráfica optimizada para administrar varios proyectos.¹⁶ La versión para Windows se lanzó el 4 de marzo de 2026 con compatibilidad nativa con PowerShell y un sandbox nativo de Windows.⁶⁶

Instalación

codex app                      # Auto-downloads and installs on first run

O descárgala directamente: Codex.dmg (macOS) | Disponible en Microsoft Store (Windows)

Funciones principales

Appshots, comentarios en el navegador y Computer Use

Las actualizaciones de la aplicación del 21 de mayo convierten la aplicación de escritorio en una superficie contextual más completa, en lugar de limitarla a administrar hilos. Usa Appshots cuando Codex necesite conocer el estado de otra aplicación de Mac antes de poder actuar: Codex captura la ventana que está en primer plano, el texto visible y fuera de pantalla que la aplicación pone a disposición, y almacena el archivo adjunto localmente en el historial de la sesión.⁹⁹

Para trabajos web y de frontend, usa primero el navegador integrado cuando la página no requiera autenticación: les proporciona a Codex y a ti una vista previa renderizada compartida, admite acciones de uso del navegador como hacer clic, tomar capturas de pantalla, descargar recursos y realizar inspecciones de solo lectura mediante JavaScript, y te permite marcar regiones de la página con comentarios que Codex puede atender en el siguiente turno.⁹⁹ Para sitios que requieren iniciar sesión, continúa usando la extensión del navegador (Chrome, Edge, Brave, Opera o Vivaldi; Opera no cuenta con chat lateral). Herramientas de sitios (WebMCP, 25 de agosto de 2026): en el navegador integrado de la aplicación de escritorio, ChatGPT Work y Codex pueden usar herramientas proporcionadas por un sitio web para trabajar con la página; usa GPT-5.6 Sol o GPT-5.6 Terra en la versión más reciente de la aplicación de escritorio, ya que las herramientas de sitios no están disponibles con GPT-5.6 Luna ni en espacios de trabajo Enterprise o Edu.¹²⁷

Usa Computer Use únicamente cuando una integración estructurada o la vista previa del navegador no puedan verificar la tarea. Puede inspeccionar y operar aplicaciones autorizadas de Mac, pero conserva las aprobaciones y reglas de sandbox de Codex para editar archivos y ejecutar comandos de shell. Además, el uso con la computadora bloqueada sigue siendo limitado: Codex puede acceder temporalmente a las aplicaciones autorizadas durante turnos activos y de confianza de Computer Use después de bloquear la Mac, con medidas de protección para volver a bloquearla y detección de entradas locales.⁹⁹

Modos de hilo

Cada hilo se ejecuta en uno de tres modos, que seleccionas al crearlo:

Mecanismos de aislamiento de Worktree:

Cuando inicias un hilo de Worktree, la aplicación de escritorio: 1. Crea un nuevo worktree de Git (git worktree add) en un directorio temporal 2. Extrae una rama nueva a partir de tu HEAD actual 3. Ejecuta el agente dentro del worktree; todos los cambios en los archivos quedan aislados 4. Presenta un diff para que lo revises al terminar; tú eliges qué cambios integrar

Esto significa que puedes ejecutar simultáneamente varios hilos de Worktree en el mismo repositorio sin conflictos. Cada uno obtiene su propia rama y directorio de trabajo.

Configuración de Worktree y propiedad de los hilos (v0.151.0): el comportamiento de los worktrees administrados se determina a partir de la configuración [desktop] existente mediante un analizador específico de configuración: la raíz de los worktrees se establece de forma predeterminada en $CODEX_HOME/worktrees, la limpieza automática está habilitada por defecto y se conservan 15 worktrees; además, las raíces configuradas, las opciones de limpieza y las cantidades de retención se validan antes de usarse. Cada worktree vinculado y administrado también puede incluir un registro de propiedad codex-thread.json con control de versiones en sus metadatos de Git, que lo vincula a un hilo: las escrituras son atómicas y no sobrescriben datos existentes (las vinculaciones repetidas son idempotentes y se rechazan los propietarios en conflicto), mientras que los checkouts principales, anidados y no administrados se rechazan antes de modificar los metadatos de propiedad.¹³⁵

Automatizaciones

Las automatizaciones se ejecutan localmente en la aplicación, por lo que esta debe estar abierta y el proyecto debe estar disponible en el disco:

• En repositorios de Git, las automatizaciones usan worktrees específicos en segundo plano (aislados de tu directorio de trabajo)
• En proyectos que no usan Git, las ejecuciones se realizan directamente en el directorio del proyecto
• Las automatizaciones usan tu configuración predeterminada de sandbox

Cómo configurar una automatización: 1. Abre un proyecto en la aplicación de escritorio 2. Haz clic en la pestaña Automatizaciones de la barra lateral 3. Define un desencadenador (programación, webhook o manual) 4. Escribe el prompt y selecciona el modo de ejecución (local o worktree) 5. Establece el nivel de razonamiento de la ejecución automatizada (App v26.312)⁷² 6. Las automatizaciones se ejecutan según la programación y ponen los resultados en una cola para su revisión

Ejemplos de uso: - Clasificación de incidencias: categoriza y prioriza automáticamente las incidencias nuevas - Supervisión de CI: detecta errores de compilación y sugiere soluciones - Respuesta a alertas: reacciona a las alertas de supervisión con un análisis de diagnóstico - Actualizaciones de dependencias: comprueba y aplica parches de seguridad

Los resultados aparecen en una cola de revisión para que una persona los apruebe.

Compatibilidad con Windows

La aplicación de escritorio de Codex se lanzó para Windows el 4 de marzo de 2026 (App v26.304) con compatibilidad nativa con PowerShell, un sandbox nativo de Windows y paridad completa de funciones, incluidos skills, automatizaciones y worktrees, sin necesidad de WSL.⁶⁶

Action de GitHub y CI/CD

La Action oficial de GitHub integra Codex en tu pipeline de CI/CD.¹⁸

Uso básico

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Opciones de configuración

Salida: final-message, el texto de la respuesta final de Codex para los pasos o trabajos posteriores.

Estrategias de seguridad

Controles de acceso

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Valor predeterminado: solo los colaboradores con acceso de escritura pueden activar flujos de trabajo de Codex.

SDK de Codex

El SDK de TypeScript integra las capacidades de agente de Codex en aplicaciones personalizadas.¹⁹

Instalación

npm install @openai/codex-sdk

Uso básico

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Funciones avanzadas de SDK

• runStreamed(...): Flujo asíncrono de eventos para recibir actualizaciones intermedias
• Autenticación de SDK de Python (v0.132.0+): El inicio de sesión con clave de API, los flujos de navegador o código de dispositivo de ChatGPT, la inspección de cuentas y el cierre de sesión son opciones nativas de SDK.⁹⁷
• Comodidad para turnos de solo texto (v0.132.0+): Las APIs de turno de Python aceptan cadenas de texto sin formato y devuelven metadatos de TurnResult más completos, con los elementos recopilados, los tiempos y el uso.⁹⁷
• outputSchema: Impone una salida final con la estructura de JSON
• Entrada multimodal: Pasa texto e imágenes locales ({ type: "local_image", path: "..." })
• Flujos de trabajo con imágenes (v0.117.0): view_image devuelve URLs, las imágenes generadas pueden volver a abrirse y el historial de imágenes se conserva al reanudar una sesión⁷⁵
• view_image en varios entornos (v0.130.0): En las sesiones que abarcan varios entornos (función incorporada en la versión v0.124.0 con selección del entorno y el directorio de trabajo en cada turno, y perfeccionada en la versión v0.125.0 con entornos persistentes), view_image ahora resuelve las rutas de archivo mediante el entorno seleccionado, en lugar de hacerlo a través del sistema de archivos local del orquestador. Una imagen adjunta desde un entorno remoto se obtiene en relación con el directorio de trabajo de ese entorno, no con el host donde se ejecuta el SDK.⁹¹

Configuración de hilos y clientes

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

Las sesiones se conservan en ~/.codex/sessions.

Entorno de ejecución: Node.js 18+.

Optimización del rendimiento

Gestión del contexto

Las ventanas de contexto varían según el modelo. La familia GPT-5.6 actual (Sol, Terra y Luna) tiene una ventana de 272K; GPT-5.5, el modelo insignia de la generación anterior, ofrece 400K en Codex (1M en la API); GPT-5.4 y GPT-5.4-mini (que se retirarán de Codex el 31 de agosto de 2026) ofrecen 1M y 400K, respectivamente; la familia GPT-5.3-Codex heredada admitía 272K de entrada + 128K de salida (un presupuesto total de 400K). Todas se llenan más rápido de lo que podrías esperar, así que gestiónalas de forma proactiva:

1. Usa /compact con regularidad: Resume el historial de la conversación para liberar tokens
2. Proporciona documentación local: Un AGENTS.md de calidad y una buena documentación local reducen el trabajo de exploración (que consume contexto)
3. Usa @ para adjuntar archivos específicos: Haz referencia directa a los archivos en lugar de pedirle a Codex que los encuentre
4. Mantén los prompts enfocados: Los prompts delimitados que indican los archivos exactos consumen menos contexto que una exploración abierta

Gestión experimental del contexto (v0.153.0, desactivada de forma predeterminada): features.context_management.experimental_mode activa una pila de contexto coordinada —contexto con presupuesto de tokens, notas del historial y una herramienta new_context— para las sesiones elegibles de ChatGPT Plus, Pro y Pro Lite que utilizan el backend de Codex. Se excluyen las sesiones con clave de API, los proveedores personalizados, los endpoints que no son de Codex y los hilos estructurados temporales. Además, la función se encuentra explícitamente en desarrollo: considérala un adelanto del rumbo que está tomando la gestión del contexto, no algo sobre lo cual debas construir flujos de trabajo.¹⁴⁰

Eficiencia de tokens

Optimización de la velocidad

1. gpt-5.3-codex-spark: Variante de menor latencia para el trabajo interactivo en pareja
2. --profile fast: gpt-5.6-luna preconfigurado con un nivel bajo de razonamiento
3. Ejecución de herramientas en paralelo: Codex ejecuta simultáneamente las lecturas y comprobaciones independientes, así que estructura los prompts para permitirlo
4. Ciclos orientados a resultados: Pide «implementa, prueba, corrige y detente cuando todo pase» en lugar de dar instrucciones paso a paso

¿Cómo depuro problemas?

Problemas comunes y soluciones

Referencia de mensajes de error

¿Qué hace codex doctor?

codex doctor es el único comando que debes ejecutar antes de informar de un error o depurar una instalación que no funciona. Reúne en un solo informe los datos del entorno de ejecución local, la configuración, la autenticación, la terminal, la red y el estado, y la propia plantilla de incidencias del proyecto te pide que pegues su salida.¹⁵³

codex doctor                           # Full human-readable report (the default)
codex doctor --summary                 # Compact view
codex doctor --json                    # Redacted structured JSON, for bug reports
codex doctor --all                     # Expand truncated lists
codex doctor --no-color                # Strip ANSI color

El informe está organizado en secciones estables para que puedas ir rápidamente a la que necesitas:¹⁵³

Cada comprobación incluye un marcador de estado —✓ correcto, ✗ error, ⚠ advertencia, ○ inactivo— y una línea de resumen. --json identifica cada comprobación con un identificador estable, lo que permite usarla en CI o en un script de soporte, en lugar de limitarla a la inspección visual.¹⁵³

El comando se ha ampliado con cada versión: apareció en v0.131.0; en v0.135.0 incorporó informes sobre el entorno, Git, la terminal, el servidor de la aplicación y el inventario de hilos; y en v0.139.0 añadió detalles sobre el editor y el paginador (con los valores confidenciales ocultos en JSON).^96159155

Úsalo primero, no al final. La mayoría de los informes que afirman que «Codex no funciona» se deben a algo que doctor ya identifica: un modo de autenticación obsoleto, un archivo config.toml que no se pudo analizar o una segunda instalación que oculta la que se encuentra en tu PATH.

Herramientas de diagnóstico

codex doctor                           # Full local diagnostic (start here)
codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

Diagnósticos de la TUI durante la sesión:

/status                                # Token/session overview
/debug-config                          # Show config layers and requirement sources
/compact                               # Summarize history to reclaim context

Nota: codex --verbose no es una opción válida de nivel superior. Usa los subcomandos de depuración y los diagnósticos de la TUI anteriores.

Reinstalación limpia

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Conserva ~/.codex/ (autenticación, configuración y sesiones). Para fijar una versión exacta, volver a una versión anterior después de una versión defectuosa o borrar por completo el estado, consulta Actualizar, volver a una versión anterior o desinstalar.

Modo de depuración

codex debug app-server send-message-v2  # Test app-server client

Informar de problemas

/feedback                              # Send logs to Codex maintainers (in TUI)

También puedes informar de problemas en github.com/openai/codex/issues.¹

Codex Security [VISTA PREVIA]

Codex Security entró en vista previa de investigación el 6 de marzo de 2026 e incorporó al conjunto de Codex la revisión de seguridad de aplicaciones con reconocimiento del contexto.⁷⁷ Está disponible mediante Codex web para clientes de ChatGPT Pro, Enterprise, Business y Edu.

Cómo funciona: Codex Security analiza repositorios para crear un modelo de amenazas específico de cada proyecto, identifica vulnerabilidades clasificadas según su impacto en situaciones reales y somete los hallazgos a pruebas rigurosas en un entorno aislado para validarlos. El agente presenta hallazgos de mayor confianza junto con sus correcciones, lo que reduce el ruido causado por errores insignificantes.

Rendimiento: Durante la vista previa de investigación, Codex Security analizó 1,2 millones de commits e identificó 10.561 vulnerabilidades de gravedad alta. La precisión mejoró con el tiempo: redujo el ruido en un 84 %, disminuyó en más de un 90 % la cantidad de casos cuya gravedad se había sobrestimado y redujo a la mitad la tasa de falsos positivos. El sistema ha encontrado vulnerabilidades reales en OpenSSH, GnuTLS y Chromium, y se han asignado 14 CVE.⁷⁷

Nota: Codex Security es independiente del modelo de seguridad integrado en el sandbox de CLI. El sandbox protege tu computadora de Codex; Codex Security protege tu código frente a vulnerabilidades.

Implementación empresarial

Controles de administración (requirements.toml)

Los administradores aplican las políticas empresariales mediante requirements.toml, un archivo de configuración impuesto por el administrador que restringe los ajustes sensibles de seguridad que los usuarios no pueden anular:²¹

La versión v0.146.0 incorpora el reconocimiento de planes empresariales y controles de administración para las actualizaciones dentro de la aplicación.¹¹⁴ En una flota administrada, esto marca la diferencia entre permitir que los desarrolladores actualicen CLI por su cuenta cada vez que detecten una nueva versión y dejar que el administrador decida cuándo desplegarla. Las notas de la versión anuncian el control, pero no publican su clave de requirements.toml; considera que el nombre exacto del ajuste no está verificado hasta que OpenAI lo documente.

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["on-request", "never"]   # `untrusted` retired in v0.149.0

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

A diferencia del archivo config.toml de cada usuario, que establece preferencias, requirements.toml constituye una capa de restricciones obligatorias que limita los valores que los usuarios pueden seleccionar, sin que estos puedan anularla. Las reglas de requisitos del administrador solo pueden solicitar confirmación o prohibir (nunca permitir de forma silenciosa).

Configuración de MDM en macOS

Distribuye la configuración mediante MDM con el dominio de preferencias com.openai.codex.²¹ Codex admite las cargas útiles estándar de MDM para macOS (Jamf Pro, Fleet, Kandji, etc.). Codifica TOML en base64 sin saltos de línea:

Precedencia (de mayor a menor):

1. Preferencias administradas de macOS (MDM)
2. Requisitos obtenidos de la nube (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (sistema de archivos local)

Los requisitos de la nube solo completan los campos de requisitos que no se hayan establecido, por lo que las capas administradas con mayor precedencia siempre prevalecen. Los requisitos de la nube se aplican según la disponibilidad; si la consulta falla o se agota el tiempo de espera, Codex continúa sin la capa de la nube.

Integración con OpenTelemetry

Codex permite propagar el contexto de seguimiento de OpenTelemetry desde las variables de entorno estándar de OTel hasta las llamadas de API de OpenAI. Configura las variables de entorno estándar antes de iniciar Codex:

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• Se respetan las variables de entorno estándar OTEL_* (punto de conexión, nombre del servicio y atributos de recursos)
• El contexto de seguimiento se propaga a través de Codex hasta las llamadas de API, lo que permite una observabilidad integral
• Usa atributos de recursos para etiquetar los seguimientos por equipo, entorno o proyecto
• Ten presentes los requisitos de privacidad al habilitar el registro de instrucciones y herramientas, ya que los seguimientos pueden contener fragmentos de código
• Metadatos configurables de seguimiento de OpenTelemetry (v0.130.0+). Además del contenedor estándar OTEL_RESOURCE_ATTRIBUTES, el crate codex-otel ahora ofrece metadatos de seguimiento configurables para que los administradores puedan etiquetar los seguimientos con dimensiones específicas de la organización (centro de costos, ID del proyecto o referencia del ticket) sin tener que reconstruir OTEL_RESOURCE_ATTRIBUTES desde cero en cada ejecución. Combina esta función con los análisis más detallados de revisiones y comentarios incluidos en la misma versión para unificar la depuración y la clasificación de incidencias en las sesiones de CLI, app-server y remote-control.⁹¹

Acceso empresarial

• ChatGPT Business / Enterprise / Edu: Acceso controlado por el administrador de la organización, con aplicación automática de los requisitos obtenidos de la nube. Admite SSO mediante SAML/OIDC a través de tu proveedor de identidad (Okta, Entra ID, etc.)
• API: Autenticación, facturación y controles de organización y proyecto estándar de API. OpenAI publica informes SOC 2 Type II y SOC 3; hay un BAA de HIPAA disponible para el nivel Enterprise
• Codex SDK: Incorpóralo en herramientas y flujos de trabajo internos
• Aplicación de políticas a escala: Usa requirements_toml_base64 distribuido mediante MDM o /etc/codex/requirements.toml en el sistema de archivos

Tratamiento de datos y cumplimiento normativo: - Las entradas y salidas de API no se utilizan para entrenamiento según los términos de Business/Enterprise/API de OpenAI - Para la residencia de datos, el tráfico de API de OpenAI se enruta de forma predeterminada mediante infraestructura ubicada en Estados Unidos; si necesitas residencia de datos en la UE, consulta al equipo de ventas empresariales de OpenAI - Las transcripciones de las sesiones se almacenan localmente; solo las llamadas de API salen de la computadora - ChatGPT Enterprise admite marcos de cumplimiento normativo como SOC 2, GDPR y CCPA

Estrategia de implementación

Implementación gradual recomendada para organizaciones:

1. Piloto (semanas 1 y 2): Despliega la herramienta para entre 3 y 5 ingenieros sénior con requirements.toml, aplicando el entorno aislado read-only, las aprobaciones on-request y la búsqueda web cached. Recopila comentarios sobre los patrones de AGENTS.md y las necesidades de servidores MCP.
2. Ampliación al equipo (semanas 3 y 4): Despliega la herramienta para todo el equipo. Distribuye el archivo config.toml estándar del equipo mediante MDM o el repositorio. Habilita el entorno aislado workspace-write para los repositorios de confianza.
3. Integración con CI (semanas 5 y 6): Añade codex-action a los procesos de CI/CD para automatizar la revisión de PR y la generación de pruebas. Usa --ephemeral para mantener los costos predecibles.
4. Toda la organización (a partir del segundo mes): Realiza el despliegue mediante MDM con requirements.toml para imponer los servidores MCP aprobados, las políticas del entorno aislado y las listas de modelos permitidos.

Patrones de auditoría

Supervisa el uso de Codex y garantiza el cumplimiento normativo:

• Seguimientos de OpenTelemetry: Supervisa el volumen de llamadas de API, el uso de tokens y la latencia de cada equipo
• Persistencia de sesiones: Audita ~/.codex/sessions/ para revisar el cumplimiento normativo (desactívala con --ephemeral en contextos sensibles)
• Aplicación de identidad de MCP: requirements.toml registra los intentos bloqueados de acceso a servidores; revísalos para detectar el uso no autorizado de herramientas
• Registro de auditoría de Git: Todos los cambios de archivos que realiza Codex pasan por el flujo estándar de Git; revísalos mediante el historial de ramas y las diferencias de los PR

Mejores prácticas y antipatrones

Patrones para redactar prompts

1. Prompts basados en restricciones: Comienza por los límites. «NO cambies los contratos de API. Solo refactoriza la implementación interna».
2. Pasos de reproducción estructurados: Los pasos numerados permiten corregir errores mejor que las descripciones imprecisas
3. Solicitudes de verificación: Termina con «Ejecuta el linter y el conjunto de pruebas pertinente más pequeño. Informa los comandos y resultados».
4. Referencias a archivos: Usa @filename para adjuntar archivos específicos al contexto
5. Ciclos orientados a resultados: «Implementa, ejecuta las pruebas, corrige los fallos y detente solo cuando todas las pruebas pasen». Codex itera hasta terminar

Filosofía de pruebas

La comunidad coincide en un enfoque de colaboración con IA basado en pruebas:²²

• Define las pruebas de antemano como señales de finalización
• Deja que Codex itere hasta que las pruebas pasen (rojo → verde → refactorización)
• Adopta los patrones de programación de Tiger Style
• Proporciona el texto exacto del archivo cuando solicites parches. Codex usa coincidencias estrictas, no parches aproximados basados en AST

Mejores prácticas para gestionar el contexto

• Proporciona documentación local de alta calidad en lugar de depender de búsquedas web
• Mantén documentos Markdown estructurados con tablas de contenido y archivos de progreso («divulgación progresiva»)
• Normaliza los finales de línea (LF frente a CRLF) en todos los archivos con seguimiento para evitar fallos al aplicar parches
• Mantén AGENTS.md conciso, ya que las instrucciones largas terminan desplazadas fuera del contexto

Flujo de trabajo con Git

• Crea siempre una rama nueva antes de ejecutar Codex en repositorios que no conozcas
• Usa flujos de trabajo basados en parches (git diff / git apply) en lugar de ediciones directas
• Revisa las sugerencias de Codex como si fueran PR de revisión de código
• Usa /diff para verificar los cambios antes de confirmar un commit

Skills y prompts de la comunidad

El repositorio feiskyer/codex-settings ofrece configuraciones mantenidas por la comunidad:²³

Prompts reutilizables (en ~/.codex/prompts/): - deep-reflector: Extrae aprendizajes de las sesiones de desarrollo - github-issue-fixer [issue-number]: Análisis sistemático de errores y creación de PR - github-pr-reviewer [pr-number]: Flujos de trabajo para revisar código - ui-engineer [requirements]: Desarrollo frontend listo para producción

Skills de la comunidad: - claude-skill: Transfiere tareas a Claude Code con modos de permisos - autonomous-skill: Automatización de tareas durante varias sesiones con seguimiento del progreso - deep-research: Coordinación paralela de subtareas - kiro-skill: Flujo de requisitos → diseño → tareas → ejecución

Antipatrones

Errores comunes que desperdician tokens, generan resultados deficientes o crean flujos de trabajo frustrantes.

Antipatrones de costos

Antipatrones de contexto

Antipatrones de flujo de trabajo

Antipatrones de prompts

Recetas de flujo de trabajo

Patrones integrales para situaciones habituales de desarrollo.

Receta 1: Configuración de un proyecto nuevo

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Revisa el AGENTS.md generado, edítalo para que coincida con tus convenciones y luego:

> Run the health endpoint test and confirm it passes

Receta 2: Flujo de desarrollo diario

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Revisa con /diff y luego confirma el commit.

Receta 3: Refactorización compleja con el modo Plan

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Revisa el plan. Apruébalo o reoriéntalo:

[Tab] Also add a migration script using Alembic

Después de que Codex lo ejecute, verifica:

> Run the full test suite and report results
> /diff

Receta 4: Revisión de PR con codex exec

codex exec --model gpt-5.6-luna \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Receta 5: Depuración con Cloud Tasks [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."