Codex CLI: la referencia técnica definitiva

TL;DR: Codex es un agente de programación con múltiples superficies: lee tu base de código, ejecuta comandos en un sandbox a nivel de sistema operativo, aplica cambios en archivos y delega tareas a la nube. Domina cinco sistemas — config.toml, el modelo de sandbox/aprobaciones, AGENTS.md, MCP y skills—, y se convertirá en un multiplicador de fuerza. GPT-5.6 Sol es la opción predeterminada recomendada (la configuración “Power”, razonamiento medio); GPT-5.5, el modelo insignia de la generación anterior, ofrece 400K de contexto en Codex y 1M en API.⁸³¹¹⁷ ¿Eres nuevo aquí? Ve directamente a Instalación e Inicio rápido. ¿Sigues los lanzamientos? La versión estable más reciente es la v0.147.0 (7 de agosto de 2026); consulta Aspectos destacados de la versión para conocer los cambios recientes y el Registro de cambios para ver todas las actualizaciones.¹¹⁶

Codex funciona como un agente de programación con múltiples superficies, no como un chatbot que escribe código. CLI lee tu base de código, ejecuta comandos en un sandbox, aplica cambios en archivos, se conecta a servicios externos mediante MCP y delega tareas de larga duración a la nube. Se ejecuta localmente, pero piensa globalmente; la misma inteligencia impulsa cinco superficies distintas según cómo trabajes, incluida la nueva extensión de Chrome que ejecuta Codex en tu navegador sin adueñarse de él.⁹⁰

La diferencia entre un uso casual y uno eficaz de Codex se reduce a cinco sistemas fundamentales. Domínalos y Codex se convertirá en un multiplicador de fuerza:

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

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

Puntos clave

• Cinco superficies, un mismo cerebro: CLI, la app de escritorio, la extensión para IDE, las tareas en la nube y la nueva extensión de Chrome comparten la misma inteligencia GPT-5.x-Codex; elige la superficie que se adapte a tu flujo de trabajo.⁹⁰
• Sandboxing a nivel del sistema operativo: Codex aplica restricciones del sistema de archivos y de red a nivel del kernel (Seatbelt en macOS, Landlock + seccomp en Linux), no dentro de contenedores.
• AGENTS.md funciona entre 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 la sobrecarga de cambiar de contexto: Define preajustes de configuración con nombre (fast, careful, auto) y alterna entre ellos con --profile.
• La gestión del contexto importa: la familia GPT-5.6 (Sol, Terra, Luna) utiliza una ventana de contexto de 272K; GPT-5.5, el modelo insignia de la generación anterior, ofrece 400K en Codex y 1M en API. Usa /compact, prompts enfocados y referencias @file para gestionar los presupuestos de tokens de forma proactiva.⁸³¹¹²

Cómo usar esta guía

Esta es una referencia de más de 3.300 líneas; empieza donde encaje tu nivel de experiencia:

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

Aspectos destacados de las versiones: qué cambió recientemente

La narrativa versión por versión, para quienes siguen el ritmo de lanzamientos de Codex. ¿Eres nuevo aquí? Omite esta sección y vuelve después de Inicio rápido; no necesitas nada de aquí para empezar a ser productivo.

GPT-5.6 Sol es el valor predeterminado recomendado en Codex: la configuración predeterminada de “Power” con razonamiento medio, ajustable hacia Smarter o Faster; GPT-5.5 (23 de abril de 2026: contexto de 400K en Codex, 1M en API, $5/$30 por MTok, 82,7 % SOTA en Terminal-Bench 2.0) es el modelo insignia de la generación anterior.⁸³¹¹⁷ Desde CLI v0.147.0 (estable, 7 de agosto de 2026), codex exec --full-auto fue eliminado (obsoleto desde v0.128): los scripts que aún lo incluyen ahora generan un error; reemplázalo con --sandbox workspace-write junto con una opción de aprobación o un perfil. v0.147.0 también incorpora --approve-for-me (las solicitudes de aprobación se resuelven mediante una revisión automática), Agent Plugins portátiles con búsqueda en catálogos locales, personales, de espacio de trabajo y remotos, el protocolo opcional MCP 2026-07-28 (descubrimiento paginado, solicitudes de múltiples rondas, inicio de servidor no bloqueante) y secciones de conversación para organizar transcripciones largas.¹¹⁶ v0.146.0 (estable, 29 de julio) hizo que los proxies configurados cubrieran 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.¹¹⁴¹¹⁵ Desde CLI v0.145.0 (estable, 21 de julio de 2026), /import migra desde Cursor además de Claude Code —configuración, servidores MCP, plugins, sesiones, comandos y memorias con alcance de proyecto—; la voz regresa como conversaciones realtime V3 en streaming con entradas de audio y salidas de herramientas de audio en formatos locales comunes; la experiencia opcional multi-agent v2 se estabiliza con modelos de subagentes, niveles de razonamiento y concurrencia configurables; un historial de hilos paginado experimental ofrece reanudación eficiente, búsqueda, nombres persistentes, compatibilidad con subagentes y memorias; se incorpora el inicio de sesión experimental de Amazon Bedrock con compatibilidad para endpoint y autenticación personalizados (GPT-5.6 Sol como modelo predeterminado de Bedrock), y las selecciones de modelos GPT-5.4 incluidas 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.¹¹¹¹¹² Desde CLI v0.140.0 (estable, 15 de junio de 2026), /usage muestra la actividad diaria/semanal/acumulada de tokens de la cuenta, las sesiones se pueden eliminar 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 chats recientes desde Claude Code, escribir @ abre de forma predeterminada un menú unificado de menciones para archivos, plugins y skills, y la autenticación administrada con claves de API de Amazon Bedrock se incorpora junto con almacenamiento local cifrado para las credenciales de CLI y MCP OAuth; los controles de voz experimentales de /realtime se eliminaron de la TUI (la voz regresó después en v0.145.0 como realtime V3 en streaming).¹⁰²¹¹² Desde CLI v0.139.0 (estable, 9 de junio de 2026), el modo de código puede llamar directamente a la búsqueda web independiente (incluso desde llamadas anidadas de herramientas JavaScript) y recibir resultados en texto sin formato, los esquemas de entrada de herramientas/conectores ahora preservan las construcciones oneOf/allOf para mejorar la compatibilidad con esquemas grandes y MCP, codex doctor añade detalles del entorno del editor y del paginador (ocultando valores sensibles en JSON), y el marketplace de plugins expone fuentes en codex plugin marketplace list --json con listados más rápidos del catálogo en caché.¹²² v0.138.0 (8 de junio) añadió /app para transferir una sesión de CLI a la app de escritorio en macOS y Windows, expuso rutas de imágenes locales al modelo, hizo más flexible la selección del esfuerzo de razonamiento y proporcionó a la automatización de plugins una salida estructurada de JSON; también empezó a cifrar el texto de tareas de padre a subagente en multi-agent v2, por lo que las instrucciones de delegación ya no aparecen en texto sin formato en los registros de sesión locales (consulta Multi-Agent).¹²³¹⁰⁸ v0.137.0 (4 de junio) incorporó multi-agent v2 (tiempo de ejecución mantenido por hilo, mejores valores predeterminados de seguimiento y metadatos, hide_spawn_agent_metadata con valor predeterminado true), atajos de teclado F13–F24 en la TUI y una extensión de skills v1 con resolución de catálogo por turno.¹²⁴ Desde CLI v0.135.0 (28 de mayo de 2026), codex doctor informa un inventario más completo del entorno, Git, terminal, app-server e hilos; /status muestra detalles de conexión remota y la versión del servidor cuando la TUI está conectada mediante un remoto; el modo vim obtuvo edición con objetos de texto, mejor comportamiento al final de palabras/líneas y una interrupción de turno configurable; /permissions ahora reconoce perfiles de permisos con nombre y muestra los personalizados; las compilaciones empaquetadas de Codex descubren y usan el asistente zsh parcheado incluido en macOS compatibles; y Python SDK expone preajustes Sandbox fáciles de usar para APIs de hilo y turno.¹²⁶ v0.134.0 (26 de mayo de 2026) introdujo búsqueda en el historial local de conversaciones 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 en CLI, los permisos de la TUI y los flujos de sandbox (las configuraciones de perfiles heredadas se rechazan con orientación de migración), mejoró la configuración de MCP con selección de entorno por servidor y opciones de OAuth para servidores HTTP en streaming, hizo más fiables los esquemas de herramientas de conectores al preservar $ref/$defs locales y compactar esquemas demasiado grandes, permitió que las herramientas MCP de solo lectura se ejecutaran de forma concurrente cuando anuncian readOnlyHint, y añadió un contexto más completo de extensiones y hooks, incluido el historial de conversación para herramientas de extensión.¹⁰¹ v0.133.0 (21 de mayo de 2026) activó los objetivos de forma predeterminada con almacenamiento dedicado y seguimiento del progreso; codex remote-control incorporó preparación/estado en primer plano y arranque/detención estilo daemon; los perfiles de permisos obtuvieron APIs de lista, herencia, requirements.toml administrado, actualización en tiempo de ejecución y una integración de sandbox más sólida en Windows; el descubrimiento de plugins muestra las versiones instaladas, las raíces del marketplace y las colecciones remotas; y las extensiones pueden observar el inicio/detención de subagentes, la ejecución de herramientas, los metadatos de turnos y el procesamiento asíncrono de aprobaciones/turnos. La actualización de la app de Codex del 21 de mayo añadió Appshots para ventanas de Mac en primer plano, Goal mode GA en app/IDE/CLI, mejoras en las anotaciones del navegador dentro de la app y Computer Use bloqueado opcional para usuarios de Mac elegibles.⁹⁹¹⁰⁰ v0.132.0 (20 de mayo de 2026) añadió autenticación de primera clase para Python SDK, APIs de turnos solo de texto más simples, TurnResult más completo, codex exec resume --output-schema, inicio más rápido de la TUI, registro de ejecutores remotos respaldado por autenticación y preservación de fidelidad de imágenes en turnos de app-server. Usa opciones explícitas de sandbox/aprobación o perfiles de permisos: el heredado --full-auto fue eliminado desde v0.147.0; js_repl sigue eliminado.^{86878991969798116}

Nota de estabilidad: Las funciones marcadas como [EXPERIMENTAL] o under development están sujetas a cambios entre versiones. Desde v0.133.0 (21 de mayo de 2026), los objetivos están activados de forma predeterminada, los perfiles de permisos son una superficie administrada de primera clase, el descubrimiento de plugins es más inspeccionable y remote-control es más fácil de ejecutar como comando de app-server en primer plano o daemonizado. Codex Cloud y el modo de código siguen siendo experimentales o están en desarrollo, mientras que CLI, el sandboxing, AGENTS.md, config.toml, Skills, hooks, herramientas multi-agent, plugins, Browser, Computer Use y Appshots son superficies estables o documentadas orientadas al usuario según la plataforma y el plan. v0.132.0 completa la autenticación de Python SDK y la automatización estructurada de reanudación; v0.131.0 añadió codex doctor, búsqueda unificada de menciones con @, comandos de marketplace de CLI, uso compartido de plugins consciente de versiones, remote-control administrado por daemon con activación/desactivación en tiempo de ejecución, entornos respaldados por registro y endurecimiento adicional del sandbox de Windows.⁹⁶⁹⁷⁹⁸ El heredado --full-auto fue eliminado en v0.147.0 (obsoleto desde v0.128) y js_repl sigue eliminado.^8687116

Cómo funciona Codex: el modelo mental

Antes de profundizar en las funciones, entiende cómo la arquitectura de Codex da forma a 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   │
│  ┌──────────┐                                           │
│  │  Chrome  │  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 (untrusted → 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-5.x impulsa todo. Desde agosto de 2026, gpt-5.6-sol es el valor predeterminado recomendado — la configuración “Power”, con razonamiento medio — junto a 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 1M en API), y gpt-5.4 se retira de Codex el 31 de agosto de 2026.⁸³¹¹⁷ 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 sandbox 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 las llamadas al sistema. El sandbox opera a nivel del kernel, no dentro de contenedores. Luego, la política de aprobación decide cuándo solicitar confirmación humana.

Capa de extensiones: MCP conecta servicios externos (GitHub, Figma, Sentry). Las skills agrupan flujos de trabajo reutilizables que Codex carga según sea necesario. Las apps se conectan a los conectores de ChatGPT. La búsqueda web añade contexto en tiempo real desde internet.

Capa de superficies: CLI para usuarios avanzados de terminal y automatización. Aplicación de escritorio para la gestión de proyectos con múltiples hilos. Extensión de IDE para ciclos de editar-compilar-probar. 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 de IDE para ciclos de programación ajustados, la aplicación de escritorio para planificación y coordinación, y Chrome 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 de decisión
8. ¿Cómo funciona el sistema de sandbox y aprobación?
9. ¿Cómo funciona AGENTS.md?
10. Hooks
11. ¿Qué es MCP (Model Context Protocol)?
12. Modo Code
13. Entorno de ejecución REPL de JavaScript
14. ¿Qué son las skills?
15. Plugins
16. Modo Plan 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. Acción de GitHub y CI/CD
23. Codex SDK
24. Optimización del rendimiento
25. ¿Cómo depuro problemas? – incluido codex doctor
26. Implementación empresarial
27. Mejores prácticas 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 el CLI de Codex?

Codex incluye un comando de actualización automática desde la v0.128.0; todo lo demás se realiza mediante el gestor de paquetes con el que lo instalaste.⁸⁶ Desde la v0.146.0, los artefactos de lanzamiento, los metadatos de canales y los alias del instalador se sirven desde la infraestructura de lanzamientos alojada por OpenAI, con GitHub como respaldo.¹¹⁴ Si tu red incluye GitHub en una lista de permitidos para las instalaciones y actualizaciones de Codex, agrega también el host de lanzamientos de OpenAI; el respaldo hace que una omisión en la lista de permitidos se degrade silenciosamente en vez de fallar de forma evidente.

# Check what you are running
codex --version                          # -> codex-cli 0.147.0
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 afecta. Codex sigue una línea estable de evolución rápida, así que instalar una versión exacta es la forma más rápida de revertir: reporta el problema, fija la versión y sigue adelante. Verifica que la reversión se haya aplicado con codex --version, ya que una segunda instalación oculta en tu PATH seguirá sirviendo silenciosamente el binario anterior (codex doctor señala exactamente esto en Environment).

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

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

Para macOS y Linux, hay disponible un script de instalación de una línea 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 coloca en tu PATH.

Descargas de binarios

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

Requisitos del sistema

• macOS: Apple Silicon o Intel (compatibilidad completa con sandbox mediante Seatbelt)
• Linux: x86_64 o arm64 (sandbox mediante Landlock + seccomp)
• Windows: Sandbox nativo con tokens restringidos (pasó de experimental en la v0.100.0). También se admite WSL²

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

Dos rutas de autenticación:

1. Cuenta de ChatGPT (recomendada): Inicia sesión con tu suscripción existente de Plus, Pro, Team, Business, Edu o Enterprise. Acceso completo a las funciones, incluidas las tareas en la nube.
2. Clave de API: Configúrala mediante la variable de entorno CODEX_API_KEY o codex login --with-api-key. Algunas funciones (hilos en la nube) pueden no estar disponibles.

Consejo experto: El almacenamiento de credenciales se puede configurar mediante cli_auth_credentials_store en config.toml. Opciones: file (predeterminado), keyring (llavero del sistema operativo) o auto (keyring si está disponible; de lo contrario, file).

Inicio de sesión de Amazon Bedrock (v0.145.0, experimental): Los equipos cuyo acceso a modelos se realiza mediante Amazon Bedrock cuentan con una ruta experimental de inicio de sesión con compatibilidad para endpoint y autenticación personalizados, junto con la autenticación existente de clave de API administrada (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.¹¹²

Autocompletado de 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.147.0

Inicio rápido: tu primera sesión

Pasa de cero a ser productivo 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 archivos clave y explica la base de código. Una pregunta como esta no realiza cambios: Codex solo aplica parches a los archivos cuando solicitas un cambio, y la política de sandbox y aprobación determina cuándo debe pedirte confirmación primero.

5. Realiza un cambio:

> Add input validation to the login endpoint

Codex propone ediciones como un 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 aprueba para iniciar la ejecución.

7. Revisa tu trabajo:

> /diff

Ve todos los cambios que Codex realizó en la sesión actual.

¿Qué sigue?

• Configura AGENTS.md con instrucciones del proyecto (consulta ¿Cómo funciona AGENTS.md?)
• Configura un perfil para tu flujo de trabajo (consulta Perfiles)
• Prueba codex exec para 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 se optimiza para un patrón de flujo de trabajo diferente.

1. CLI interactiva (Terminal UI)

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 terminal es una aplicación de pantalla completa con:

• Compositor: Escribe prompts, adjunta archivos con @, ejecuta comandos de shell con el prefijo !
• Panel de salida: Respuestas del modelo en streaming, llamadas a herramientas y salida de comandos
• Barra de estado: Modelo, uso de tokens, rama de git, modo sandbox

Atajos principales de TUI:

Cambio en la línea de estado (v0.121.0): El antiguo medidor de ventana de contexto de la línea de estado fue reemplazado por un indicador de porcentaje de contexto que muestra qué tan llena está tu ventana de contexto. Si tienes scripts o hooks que analizan la línea de estado, revisa 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 reanudar y bifurcar desde un selector rediseñado, y un nuevo modo de desplazamiento sin procesar te permite recorrer la transcripción sin renderizar cuando necesitas copiar comandos o salida del modelo literalmente. Resulta útil al clasificar una sesión larga de depuración o canalizar la salida a otra herramienta.⁸⁹

Menú unificado de menciones @ (v0.140.0): Escribir @ en el compositor ahora abre por defecto un único menú de menciones que abarca archivos, plugins y skills, en reemplazo del flujo de adjuntar solo archivos; una sola pulsación para hacer referencia a cualquier recurso del proyecto.¹⁰²

2. Codex Desktop App (macOS + Windows)

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

La app de escritorio añade capacidades que CLI no tiene:

• Multitarea: Ejecuta varios agentes en paralelo en distintos proyectos al mismo tiempo
• Aislamiento mediante git worktree: Cada hilo trabaja en una copia aislada de tu repositorio
• Revisión de diff en línea: Prepara, revierte y confirma cambios sin salir de la app
• Terminal integrada: Terminal por hilo para ejecutar comandos
• Bifurcación de conversaciones: Ramifica conversaciones para explorar alternativas
• Ventanas flotantes emergentes: Desacopla conversaciones en ventanas portátiles
• Automatizaciones: Programa tareas recurrentes (clasificación de incidencias, monitoreo de CI, respuesta a alertas)
• Appshots: Adjunta la ventana de la app de Mac que está al frente a un hilo con una captura de pantalla y el texto disponible
• Comentarios en el navegador integrado: Obtén una vista previa de páginas locales o públicas, deja comentarios sobre elementos o áreas y permite que Codex aborde comentarios visuales precisos
• Computer Use: Permite que Codex opere apps de Mac autorizadas para trabajo GUI acotado; el uso bloqueado es opcional para turnos elegibles de Computer Use remoto en Mac

ChatGPT Voice, con tecnología de GPT-Live (desktop 26.715, 23 de julio de 2026): Ahora puedes controlar la app de escritorio mediante voz: habla sobre el trabajo y coordina tareas entre Chat, Work y Codex sin escribir. En macOS, activar Screen context comparte un appshot de la ventana que está al frente con la conversación, para que puedas preguntar sobre lo que estás viendo en lugar de describirlo. Está disponible en Plus, Pro, Business, Edu y Enterprise, en la app de escritorio y mediante Remote en iOS. Esta es voz de la superficie de escritorio; la propia transcripción de voz con la barra espaciadora de CLI es una función experimental independiente.¹¹³

Cuándo usar la app frente a CLI: Usa la app de escritorio cuando estés coordinando varios flujos de trabajo o necesites revisión visual de diff. Usa CLI cuando quieras componibilidad de terminal, scripts o integración con CI/CD.

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

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

• Modo agente de forma predeterminada: Lee archivos, realiza ediciones y ejecuta comandos
• Ediciones en línea: Sugerencias conscientes del contexto en tus archivos activos
• Sesiones compartidas: Las sesiones se sincronizan entre CLI y la extensión IDE
• La misma autenticación: Inicia sesión con una cuenta de ChatGPT o una clave de API

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

4. Codex Cloud [EXPERIMENTAL]

Las tareas de Cloud se ejecutan de forma asíncrona en entornos administrados por OpenAI:

• Ejecutar y olvidar: Pon en cola tareas que se ejecutan independientemente de tu máquina local
• Ejecución en paralelo: Ejecuta varias tareas de Cloud simultáneamente
• Creación de PR: Codex crea pull requests a partir del trabajo completado
• Aplicación local: Incorpora resultados de Cloud a 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 de Cloud desde chatgpt.com/codex.⁴

5. Codex para Chrome [NUEVO]

Codex se ofrece como extensión de navegador para Chrome, añadiendo una quinta superficie junto con CLI, la app de escritorio, la extensión IDE y Cloud. La extensión está diseñada para acompañar tu navegación habitual en lugar de adueñarse de ella: Codex trabaja en paralelo entre pestañas en segundo plano, y tú mantienes el control sobre los sitios que puede tocar.⁹⁰

• Ejecución en paralelo entre pestañas: Codex opera en varias pestañas a la vez sin bloquear la pestaña en primer plano.
• Control por sitio: Incluyes en una lista de permitidos los sitios web con los que Codex puede interactuar; de forma predeterminada, no tiene acceso.
• El navegador como espacio de trabajo: La extensión es ideal para trabajo con apps y sitios web donde la página es la fuente de verdad — consolas de administración, dashboards internos, interfaces de gestión de contenido, sistemas de tickets — y no reemplaza a CLI para repositorios locales.
• La misma inteligencia: Codex para Chrome ejecuta la misma inteligencia GPT-5.x-Codex que usan las demás superficies, así que una configuración de AGENTS.md o skills que funciona en CLI aplica las mismas convenciones al trabajo impulsado desde el navegador.

Instálala desde la documentación de la extensión Codex para Chrome.⁹⁰

Análisis detallado del sistema de configuración

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

Precedencia (de mayor a menor)

1. Anulaciones de sesión (máxima 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, el valor predeterminado es ~/.codex/config.toml)
4. Configuración del sistema (/etc/codex/config.toml en Unix)
5. Valores predeterminados integrados (mínima prioridad)

requirements.toml actúa como una capa de restricciones de políticas que limita qué valores pueden seleccionar los usuarios después de la combinación normal de configuraciones. Consulta Implementación empresarial.

Ubicaciones de los archivos de configuración

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

Proyectos de escritorio con varias carpetas (26.715, 23 de julio de 2026): Un proyecto local en la app de escritorio de ChatGPT ahora puede abarcar varias carpetas relacionadas, con una de ellas designada como carpeta principal (menú del proyecto → Edit project). La detección automática de config.toml se ejecuta únicamente en la carpeta principal; las carpetas secundarias siguen disponibles para buscar, leer y editar archivos, pero no aportan configuración. Un .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 de la app de escritorio, no a un cambio en las reglas de precedencia anteriores: el CLI sigue resolviendo la configuración del proyecto al recorrer 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"          # untrusted|on-request|never

[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)

# ─── 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
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             # Chrome 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 networking proxy (experimental)
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

Perfiles

Preajustes de configuración con nombre para distintos modos de trabajo:

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Activa un perfil:

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

Consejo experto: Establece un perfil predeterminado con profile = "fast" en el nivel superior de tu configuración. Anúlalo por sesión con --profile.

Proveedores de modelos personalizados

Conéctate a Azure, AWS Bedrock, modelos locales o servicios 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: La API de conexión chat/completions (wire_api = "chat") quedó obsoleta para los modelos alojados por OpenAI, y OpenAI anunció su eliminación en febrero de 2026.³⁴ Los proveedores locales (Ollama, LM Studio) pueden seguir aceptando este formato. Para 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 configúralo 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 (agosto de 2026)

GPT-5.5 (23 de abril de 2026) fue la opción recomendada por OpenAI para la mayoría de las tareas de Codex en su lanzamiento: programación compleja, uso de computadoras, trabajo de conocimiento y flujos de investigación. Disponible en Codex CLI / web / desktop el 23 de abril para ChatGPT Plus / Pro / Business / Enterprise / Edu / Go; en la API de OpenAI el 24 de abril. Ventana de contexto: 400K en Codex, 1M en la API — Codex limita la ventana a 400K para equilibrar el rendimiento y el costo entre los niveles de suscripción; la API ofrece el 1M completo. Precios (API): $5 de entrada / $30 de salida por MTok (2× la tarifa de GPT-5.4; OpenAI indica un aumento efectivo de ~20 % tras las mejoras en eficiencia de tokens). Benchmarks: 82,7 % en Terminal-Bench 2.0 (SOTA actual entre los modelos disponibles públicamente), 84,9 % en GDPval (44 ocupaciones), 78,7 % en OSWorld-Verified, 98,0 % en Tau2-bench Telecom (sin ajuste de prompts). OpenAI utilizó internamente GPT-5.5 + Codex para reescribir la 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 sigue siendo seleccionable en todas las superficies de Codex.⁶⁴ La lista exacta de modelos varía según la cuenta y el despliegue. Revisa tu caché local: ~/.codex/models_cache.json.

Nota sobre desuso (11 de marzo de 2026): los modelos GPT-5.1 ya no están disponibles en ChatGPT. Las conversaciones existentes continúan automáticamente con GPT-5.3 Instant, GPT-5.4 Thinking o GPT-5.4 Pro. GPT-5.1-Codex-Mini permaneció 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 se implementó en el nivel gratuito de ChatGPT el 5 de mayo de 2026. Esto amplía la audiencia 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 elegible 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 a $0,75/$4,50 por MTok — utiliza solo el 30 % de la cuota de GPT-5.4. 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 la base de código, revisión de archivos, procesamiento de documentos).⁷⁶

Bedrock GPT-5.6 (Sol, Terra, Luna) (v0.143.0, 8 de julio de 2026): Codex añadió compatibilidad de primera clase con tres variantes del modelo GPT-5.6 alojadas en Amazon Bedrock, incluida la compatibilidad con el nivel de esfuerzo de razonamiento max. Para los equipos cuyo acceso a modelos funciona mediante un proveedor Bedrock, se pueden seleccionar igual que otros modelos de proveedores personalizados (consulta Proveedores de modelos personalizados); el nivel de esfuerzo max está orientado a las cargas de trabajo de razonamiento y agentes más difíciles.¹⁰⁶ 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.¹¹¹ v0.145.0 (21 de julio de 2026) añade inicio de sesión experimental en Bedrock con compatibilidad para endpoint y autenticación personalizados, establece GPT-5.6 Sol como el modelo predeterminado de Bedrock y migra las selecciones incluidas de modelos GPT-5.4 a las variantes correspondientes de Terra y Luna.¹¹²

Diagrama de flujo para la selección de 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 → gpt-5.6-sol (flagship — the default "Power" setting)
   └─ Still unsure? → gpt-5.6-sol

Esfuerzo de razonamiento

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

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

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

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

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

Cambio de modelo

Cambia de modelo a mitad de 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 las capacidades y Marcos de decisión para elegir el modelo adecuado según la tarea.

Acceso mediante planes de ChatGPT

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

Actualización de precios de abril de 2026: El precio anual de Business bajó de $25 a $20/asiento/mes. Los asientos solo de Codex con precios de pago por uso ahora están disponibles para espacios de trabajo Business y Enterprise: sin tarifa fija por asiento, se facturan según el consumo de tokens.⁷⁹ La página de precios ahora publica los límites como bandas por modelo (consulta la tabla anterior), en lugar de los multiplicadores promocionales de 2x del lanzamiento de Desktop App de febrero de 2026.¹⁶¹¹⁹

Aumento del límite de uso de mayo de 2026 (vencido el 31 de mayo de 2026): Codex en el plan Plus tuvo un límite de 25× cada 5 horas (frente al aumento estándar de 20×), y el nivel de $100/mes se duplicó durante la misma ventana.⁸⁹

Costos de 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 los turnos comparables de solo texto.¹¹⁹

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

Facturación de API

Al usar Codex a través de API, OpenAI factura el uso por token según los precios estándar de OpenAI API para el modelo seleccionado (más los descuentos aplicables por caché de prompts). Consulta la página oficial de precios de API para conocer las tarifas actuales.²⁰

Estrategias de optimización de 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 alto: Usa xhigh solo para problemas realmente difíciles, ya que cuesta 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: Configura 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 flujos de trabajo de automatización
6. Supervisa el uso: Consulta /status en la TUI y los paneles de facturación de tu organización

Ejemplos de costos reales

Costos representativos de API para tareas comunes (una instantánea de precios de gpt-5.3-codex de mediados de 2026, razonamiento medio; los tamaños relativos se trasladan entre modelos):

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

Sobrecarga oculta de tokens

Cada llamada a herramientas añade tokens más allá de tu prompt visible:

Consejo de experto: 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, verifica cuántos servidores de MCP están conectados: cada uno añade definiciones de herramientas a cada llamada 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: las canalizaciones automatizadas rara vez necesitan el razonamiento máximo - Presupuestos basados en perfiles: define perfiles ci, review y dev con límites de costo adecuados - Supervisa mediante OpenTelemetry: las implementaciones Enterprise pueden exportar telemetría de uso a las pilas 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, escucha 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?

Relaciona tu tarea con un perfil preconfigurado:

Configuración de config.toml:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Cambia los perfiles por sesión: codex --profile careful

¿Cómo funcionan el sistema de sandbox y las aprobaciones?

Codex utiliza un modelo de seguridad de dos capas que separa lo que es técnicamente posible de cuándo Codex solicita la aprobación de una persona. Este enfoque difiere de manera fundamental 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.

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 por plataforma:

• macOS: framework Seatbelt de Apple mediante sandbox-exec, con perfiles específicos para cada modo que se compilan en tiempo de ejecución y que el kernel hace cumplir⁶. 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 (hereda Landlock y seccomp de Linux). v0.117.0 incluye mejoras en el sandbox con tokens restringidos para ofrecer un mejor aislamiento de procesos.⁷⁵ v0.130.0 permite que los usuarios del sandbox accedan a la caché de binarios del entorno de ejecución de escritorio, de modo que el sandbox de Windows pueda resolver esos binarios de forma fiable para los usuarios del 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, más ligero y más difícil de vulnerar. El kernel aplica las restricciones antes de que Codex siquiera vea la llamada al sistema.

Correcciones de seguridad: - Evasión del sandbox mediante bifurcación de zsh (v0.106.0): Se corrigió una vulnerabilidad por la que la ejecución del shell mediante la bifurcación de zsh podía eludir las restricciones del sandbox.⁶⁰ Si usas una versión anterior, actualízala de inmediato. - Límite del tamaño de entrada (v0.106.0): Codex ahora impone un límite de entrada de aproximadamente 1 millón de caracteres para evitar bloqueos causados por cargas excesivamente grandes.⁶⁰ - Perfil seguro para devcontainers (v0.121.0): Un nuevo perfil reforzado para clientes que utilizan devcontainers de Docker emplea Bubblewrap para aplicar el sandbox dentro del contenedor. Se admite WSL2; WSL1 se rechaza explícitamente (Bubblewrap es incompatible con la capa de compatibilidad del kernel de WSL1).⁸² - Revisión de Guardian y hooks (v0.121.0): Los hooks se deshabilitan durante las sesiones de revisión de Guardian para que los hooks anteriores y posteriores al uso de herramientas no interfieran con las decisiones del subagente Guardian.⁸² Si dependes de los hooks para registrar o validar acciones, ten en cuenta que las revisiones de Guardian los omiten; recurre a la observabilidad del servidor de aplicaciones si necesitas una pista de auditoría completa. - Sistema de archivos /dev de 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ítica configurable para controlar de forma granular 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 la confirmación de una persona:

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 cuentan con un límite de seguridad externo.⁸⁷

Identificadores de aprobación independientes (v0.104.0+)

Codex ahora asigna identificadores de aprobación independientes a cada comando de una ejecución del shell de varios pasos. Esto significa que las aprobaciones son granulares: aprobar un comando de una secuencia no aprueba automáticamente los siguientes 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 del sandbox y rechazos granulares:⁶¹

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

Solicitudes de permisos en tiempo de ejecución (v0.113.0+)

Codex ahora incluye una herramienta request_permissions integrada que permite al modelo solicitar permisos adicionales en tiempo de 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 lugar de fallar silenciosamente u obligar al usuario a reiniciar con flags diferentes.

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

Las aplicaciones y los conectores incorporan un nivel intermedio de aprobación: el modo de aprobación de aplicaciones writes permite ejecutar sin confirmación las acciones que una aplicación declara como de solo lectura, pero sigue deteniéndose ante cualquier acción de escritura.¹⁰⁷ Antes, las aprobaciones de aplicaciones funcionaban prácticamente como un «todo o nada»; writes coincide con el modelo de confianza que la mayoría de los operadores realmente quiere para las integraciones: libertad para consultar, aprobación para modificar.

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

El nuevo flag --approve-for-me de CLI convierte las solicitudes de aprobación en aprobaciones revisadas automáticamente: en lugar de interrumpirte, cada solicitud se somete a una revisión que la aprueba o rechaza en tu nombre.¹¹⁶ Esto se sitúa entre «aprobarlo todo» (la postura que --full-auto, ahora eliminado, solía fomentar) e «interrumpir para todo»: las solicitudes siguen existiendo como puntos de decisión, pero quien responde es un revisor. Combínalo con los valores predeterminados más seguros de revisión automática para modelos con capacidades cibernéticas introducidos en v0.146.1, que este flag hereda. Trátalo como cualquier delegación de autoridad: es adecuado para ejecuciones largas sin supervisión, donde una interrupción implica un bloqueo, pero no para sesiones que afectan credenciales o el estado de producción, donde querrás ser quien revise.

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

Los perfiles de permisos dividen 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 personalizada [permissions.<name>].⁸⁷ v0.133.0 convierte los perfiles en una superficie administrada: los listados de APIs exponen los metadatos disponibles de los perfiles, estos pueden heredar unos de otros, el archivo requirements.toml administrado puede declarar requisitos de permisos, los perfiles activos se actualizan en tiempo de ejecución y la configuración del sandbox de Windows ahora utiliza el perfil resuelto en lugar de una política ad hoc 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 no deben poder leerse aunque se pueda escribir en la raíz del proyecto. Para excepciones puntuales de comandos, prefiere las reglas antes que ampliar un perfil de manera general.⁸⁷

Orientación sobre el antiguo --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 muestra para las ejecuciones interactivas. Usa en su lugar los flags explícitos anteriores o un perfil de permisos con nombre.⁸⁶

v0.147.0 completa la eliminación: codex exec --full-auto ya no existe. Ahora, un script que siga pasando el flag produce un error en lugar de ejecutarse. La migración es mecánica: reemplázalo por --sandbox workspace-write (además de un flag o perfil de aprobación si tu 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 rota, 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 copias de trabajo con enlaces simbólicos; las mejoras de fiabilidad del sandbox de Windows solucionan varios fallos en casos extremos durante ejecuciones prolongadas; y la versión incluida de Bubblewrap se actualiza a 0.11.2 con parches de seguridad del proyecto original. No es necesario cambiar la 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 = "untrusted"

La comunidad recomienda esta combinación como el «punto ideal»: máxima capacidad, pero con aprobación obligatoria para cada comando.⁸

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 dirigir las solicitudes de revisión a través de un subagente Guardian en lugar de exigir la aprobación de una persona para cada acción. La sesión de Guardian persiste entre aprobaciones para reutilizar la caché de prompts y evitar la sobrecarga del inicio. Cada revisión recibe un historial limpio (las decisiones anteriores no se filtran a revisiones 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 lugar de usar indiscriminadamente approval_policy = "never".

Clasificación más estricta de PowerShell (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. Así se cierra una brecha por la que el código de PowerShell ofuscado o construido dinámicamente podía evadir 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 incluyen motivos de rechazo más claros en lugar de una denegación opaca, lo que resulta útil cuando ajustas políticas de aprobación y necesitas saber por qué se bloqueó un comando.¹¹⁰

Habilitar el acceso a la red

Codex bloquea el acceso a la red de forma predeterminada 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 proxy de WebSocket (v0.104.0+)

Para entornos corporativos que dirigen el tráfico de WebSocket a través de 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 realidad la compatibilidad con «todas las capas de transporte». Los proxies configurados ahora 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 corporativo 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 sea la explicación.

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, por lo que las Mac corporativas que reciben la configuración del proxy mediante perfiles ya no necesitan variables de entorno del proxy específicas para cada shell en el tráfico de autenticación.¹⁰⁵ Desde v0.143.0, esto se extiende a Windows y al tráfico de API de Responses: Codex dirige tanto la autenticación como las llamadas de API de Responses a través del proxy del sistema de macOS o Windows, incluida la configuración automática mediante PAC y WPAD, con lo que cierra la última brecha para las redes corporativas restringidas en 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 bajo 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 detección

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 comprueba AGENTS.override.md > AGENTS.md > nombres de archivo alternativos
3. Combinación: Los archivos se concatenan desde la raíz hacia abajo; los 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

Proyectos de varias carpetas en la aplicación de escritorio (26.715, 23 de julio de 2026): El recorrido anterior describe el 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 la detección tomando exactamente una de ellas como referencia: «Los chats nuevos, las operaciones de Git y la detección automática de AGENTS.md, skills y config.toml usan 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 opción controla simultáneamente tres de los cinco sistemas principales de Codex: las instrucciones, 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 el principal o vuelve a declarar 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 del CLI; se trata del ámbito que la aplicación de escritorio asigna al proyecto.

Qué hace que un AGENTS.md sea excelente

Según las indicaciones 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 cierre: ¿Qué significa que algo esté «terminado»? (las pruebas pasan, no hay errores de lint, 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 encuentres un bloqueo o un estado inesperado

QUÉ NO HACER: - Incluir guías de estilo completas sin reglas de ejecución - Usar directrices ambiguas («ten cuidado», «optimiza») - Combinar prioridades contradictorias (velocidad + verificación exhaustiva + ausencia de 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 sesiones de agentes

Considera 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 para capturar instantáneas del shell y ocultar variables de entorno, mientras que el sistema de memoria analiza las escrituras en memoria para detectar secretos. 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 exigida 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 con alta probabilidad de ser un secreto; y adopta hooks preventivos solo después de comprobar el proceso manual de higiene. La lección pública consiste en el mapa de superficies y los criterios de aceptación, no en los valores de tokens privados, las rutas exactas ni el funcionamiento interno de los detectores.⁹⁵

El mecanismo de reemplazo

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

• Congelamientos de versiones: «No se permiten funciones nuevas; solo correcciones»
• Modo de incidente: «El personal de guardia debe revisar todos los cambios»
• 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 incorporó hooks en la v0.99.0 (AfterAgent) y la v0.100.0 (AfterToolUse). Después añadió en la v0.114.0 un motor experimental de hooks con los eventos SessionStart y Stop.⁷⁰ Desde la v0.124.0 (23 de abril de 2026), los hooks son estables.⁸⁵ Ahora pueden configurarse directamente en config.toml y requirements.toml, sin necesidad de un archivo separado para scripts de hooks, y observan las herramientas de MCP junto con apply_patch y las sesiones prolongadas de Bash. El sistema ahora abarca el ciclo de vida de las sesiones y la automatización a nivel de herramienta, con lo que cierra la brecha respecto al modelo de hooks de Claude Code.

Eventos de hooks disponibles

Configuración de hooks

Los hooks se configuran en .codex/config.toml:

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

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 iniciar la sesión.

Cómo reproducir los patrones de hooks de Claude Code

Si estás migrando desde Claude Code, puedes lograr una automatización similar de esta manera:

Consejo para expertos: Desde la v0.124.0 (23 de abril de 2026), el motor de hooks es estable. Continúan incorporándose nuevos eventos de hooks en las versiones; consulta el registro de cambios de Codex.

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 habilitar o deshabilitar 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 de AfterToolUse durante una sesión de edición intensiva.⁸⁹

¿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á actualmente marcado 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: Las herramientas ahora se registran con un namespace, por lo que los nombres de las herramientas en los listados aparecen como <server>:<tool> en lugar de nombres sin calificar; actualiza cualquier script o prompt que use grep con nombres de herramientas sin calificar. Se incorpora una nueva flag supports_parallel_tool_calls a los MCP incluidos, lo que habilita la ejecución en paralelo para los servidores que declaren compatibilidad. Los metadatos del estado del sandbox ahora se transmiten a través de los metadatos de las herramientas de MCP, para que los servidores puedan adaptar su comportamiento (por ejemplo, advertir si se ejecutan en un sandbox de solo lectura). La solicitud personalizada codex/sandbox-state se ha eliminado; usa la ruta de metadatos en su lugar. La fase 3 del despliegue de Apps de MCP llega aquí con compatibilidad para llamadas a herramientas; ahora también se admiten llamadas diferidas a herramientas aplanadas para servidores que usan el patrón de llamadas diferidas.⁸²

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

Cambios de MCP en v0.147.0 (7 de agosto de 2026): Codex añade compatibilidad opcional con la revisión 2026-07-28 del protocolo MCP: descubrimiento paginado (los catálogos grandes de herramientas se transmiten por páginas en lugar de en un único listado demasiado grande), solicitudes de múltiples rondas (un servidor puede mantener un intercambio de varios pasos dentro de una solicitud lógica) e inicio de servidores sin bloqueo, con herramientas MCP almacenadas en caché disponibles antes de que el servidor termine de iniciar, para que un servidor lento ya no retrase el inicio de la sesión. Es opcional, por lo que los servidores con la revisión anterior continúan funcionando sin cambios.¹¹⁶

Configuración de servidores 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 de 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 la sesión: /mcp muestra los servidores activos y las herramientas disponibles. /mcp verbose (v0.123.0+)⁸⁴ devuelve diagnósticos completos del servidor, recursos y plantillas de recursos; resulta útil cuando un servidor no se carga o las herramientas no aparecen donde deberían. El comando /mcp normal se mantiene rápido. A partir de la v0.144.0, las herramientas de MCP pueden solicitar autenticación de forma interactiva sin una activación experimental: un servidor que necesita autenticación durante la sesión muestra una solicitud mediante el flujo normal, en vez de fallar hasta que te autentiques previamente con codex mcp login.¹⁰⁷

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

Ejecutar Codex COMO servidor MCP

Codex puede exponerse como un servidor MCP para la orquestación de múltiples agentes:¹²

codex mcp-server                        # Start as MCP server (stdio transport)

El servidor expone dos herramientas: 1. codex(): Inicia una nueva sesión 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 el 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 MCP destacados

Patrones prácticos

Patrón 1: Desarrollo con 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 aproximadamente 25K caracteres. Para las herramientas que devuelven cargas útiles grandes (consultas de bases de datos, capturas de registros), usa enabled_tools para restringirlas a herramientas específicas y mantener las respuestas enfocadas.

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

Patrón 3: Gobernanza empresarial de MCP — Restringe qué servidores de MCP 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" }

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

Modo de código [EXPERIMENTAL]

El modo de código (v0.114.0) proporciona flujos de trabajo de programación más aislados al restringir el alcance del agente a operaciones enfocadas en código.⁷⁰ Cuando está activado, el agente se centra en leer, escribir y probar código sin interacciones más amplias con el sistema.

A partir de v0.139.0, el modo de código puede llamar a la búsqueda web independiente directamente —incluso desde llamadas anidadas a herramientas de JavaScript— y recibe resultados en texto sin formato, por lo que un flujo en modo de código puede obtener información actual sin salir del contexto de programación aislado por sandbox.¹²² La v0.146.0 extiende la búsqueda web independiente a proveedores de modelos personalizados compatibles, de modo que la capacidad ya no se limita a los modelos alojados por OpenAI.¹¹⁴

La v0.146.0 permite que app-server se conecte a hosts remotos de Code Mode mediante WebSocket, por lo que el entorno de ejecución del modo de código ya no tiene que estar en la misma computadora que el cliente.¹¹⁴

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

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 promovió mediante 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 eliminadas.⁸⁶

No agregues 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 una tarea que Codex carga cuando se necesitan. 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 mediante vínculos simbólicos.

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
• Proporcionadas por el ejecutor (v0.146.0): Codex detecta las skills ofrecidas por el ejecutor y lee sus recursos asociados, incluidas las skills que seleccionas explícitamente¹¹⁴

Los límites de contexto truncan los catálogos de skills. v0.146.0 conserva más skills disponibles cuando el contexto es limitado y advierte cuando se debe truncar un catálogo.¹¹⁴ Antes, una biblioteca extensa 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 de muchas skills, presta atención a esa advertencia.

Activar/desactivar

[[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 debe 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 tu prompt términos de la description de la skill para mejorar la coincidencia implícita

Ejemplo de producción: skill de despliegue

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

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 apps en un solo paquete instalable (v0.110.0+).⁶⁵ Desde v0.117.0, los plugins son componentes de primera clase: los plugins con ámbito de producto se sincronizan automáticamente al inicio y /plugins ofrece un explorador dentro de la TUI para descubrirlos y administrarlos.⁷⁵ v0.128.0 amplió los flujos de trabajo de plugins con instalación desde marketplaces, almacenamiento en caché de paquetes remotos, APIs de desinstalación remota, hooks incluidos en plugins, estado de habilitación de hooks e importación de configuración de agentes externos.⁸⁶ v0.129.0 (7 de mayo de 2026) añade uso compartido de plugins en el workspace (envía un conjunto de plugins a tus compañeros sin volver a publicarlo), controles de acceso para compartir (habilitar/deshabilitar por destinatario, revocar), filtrado de fuentes (limita desde qué marketplaces obtiene contenido un workspace) y operaciones de marketplace que se pueden invocar directamente desde el explorador /plugins en lugar de la CLI.⁸⁹ v0.133.0 (21 de mayo de 2026) facilita auditar el descubrimiento de plugins: la salida de lista reconoce el marketplace, las versiones instaladas son visibles, se enumeran las raíces de los marketplaces y las colecciones de plugins remotos pueden mostrarse sin tener que adivinar de qué registro proviene un resultado.⁹⁸ v0.130.0 (8 de mayo de 2026) hace que el empaquetado de plugins sea más transparente y que el flujo para compartir sea más controlable:⁹¹

• Hooks incluidos visibles en los detalles del plugin. La vista de detalles de /plugins ahora enumera cada hook de ciclo de vida que incluye un plugin (SessionStart, UserPromptSubmit, Stop, etc.). Antes de instalar un plugin, puedes ver exactamente qué hooks registrará en tu sesión; se acabaron los efectos secundarios inesperados de hooks de un plugin en el que confías solo por sus herramientas.
• Metadatos para compartir plugins en shareContext. Cuando se comparte un plugin desde un workspace, la carga útil del enlace compartido ahora expone metadatos del enlace (creador, ámbito, vigencia) para que las sesiones receptoras puedan mostrar su procedencia y decidir si aceptarlo.
• Controles de descubrimiento en la configuración para compartir. La configuración para compartir expone un interruptor de descubrimiento para que los equipos puedan publicar plugins en workspaces o listas de destinatarios específicos sin hacerlos visibles de forma general en toda una organización.

v0.143.0 (8 de julio de 2026) habilita los plugins remotos de forma predeterminada. Los plugins remotos ahora están habilitados sin una opción de activación, el catálogo de /plugins obtiene filas más completas (fuentes de marketplace npm junto con git y fuentes locales), y cada entrada muestra tanto su versión remota como la instalada localmente para que las diferencias sean visibles de un vistazo.¹⁰⁶ Para un equipo que estandariza un conjunto de plugins compartido, la activación remota predeterminada elimina el paso de habilitación por máquina que antes impedía el despliegue.

Fuentes de plugins

Desde v0.147.0, la búsqueda de plugins abarca los catálogos locales, personales, de workspace y remotos en una sola consulta: buscas una capacidad, no el catálogo que resulta contenerla. Junto con los paquetes portables Agent Plugin, un plugin creado en un entorno se instala correctamente en otro en lugar de quedar vinculado a la máquina o al workspace donde se creó.¹¹⁶

Descubrimiento de plugins

Codex informa al modelo qué plugins están habilitados al iniciar la sesión (v0.111.0), lo que mejora el descubrimiento de MCPs, apps y skills instalados.⁶⁵ El modelo puede sugerir plugins relevantes durante una sesión según el contexto de la tarea. En v0.117.0, los plugins con ámbito de producto se sincronizan al inicio, lo que garantiza que el catálogo de plugins más reciente esté disponible sin intervención manual.⁷⁵ Desde v0.142.0, el menú /plugins organiza los plugins remotos en las secciones OpenAI Curated, Workspace y Shared with me, y los turnos elegibles pueden recomendar e instalar plugins relevantes en línea.¹⁰⁴

Menciones de @plugin (v0.112.0+)

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

@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 MCP y conectores de apps.

Marketplace de plugins (v0.113.0+)

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

Cómo agregar marketplaces de terceros (v0.121.0+)

La documentación actual de OpenAI Codex mantiene la administración de fuentes de marketplace en codex plugin marketplace. Esto formaliza la distribución de plugins de terceros más allá del marketplace propio de OpenAI y admite abreviaturas de repositorios GitHub, URL de Git 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 respaldados por 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 agregado, los plugins de un marketplace aparecen en el explorador /plugins junto con los predeterminados. Quienes llaman al app server (integraciones de IDE/escritorio) cuentan con un punto de conexión paralelo 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. Evalúa las fuentes antes de agregarlas y prefiere la ejecución en sandbox durante las primeras ejecuciones.

Agent Plugins: el estándar multiplataforma (v0.146.0–v0.147.0)

“Agent Plugins” no es solo el nombre de una función de Codex: es un estándar abierto y neutral respecto a proveedores para empaquetado, publicado como Agent Plugins 1.0.0 el 6 de agosto de 2026, cuyo sitio oficial lo resume como “A portable package format for reusable components that extend AI agents.”¹¹⁸ Un plugin es un directorio con un manifiesto plugin.json obligatorio (un esquema cerrado de exactamente diez campos de nivel superior permitidos: $schema, name, version, description, author, homepage, repository, license, keywords, extensions, donde “Clients MUST report and ignore each unknown field”), una carpeta opcional skills/ (cada directorio hijo inmediato que contenga un SKILL.md es un skill), un mcp.json opcional que declara servidores stdio, Streamable HTTP o HTTP+SSE heredado, y directorios opcionales de espacios de nombres de clientes con dominio inverso que otros clientes “MUST ignore.” Su alcance normativo es el empaquetado: la especificación “defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable plugins”; Agent Skills y MCP conservan sus propias especificaciones por debajo de ella.¹¹⁸

La gobernanza es la historia. 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 abarca Amazon, Cursor, Microsoft, OpenAI y Vercel, y Google anunció el día del lanzamiento que se unirá a los responsables principales.¹¹⁸ Los clientes de lanzamiento mencionados abarcan ChatGPT, Codex, Cursor, GitHub Copilot, Kiro y VS Code. Hay una ausencia notable: Anthropic, que creó el formato subyacente Agent Skills y MCP en sí, no figura entre los responsables; Claude Code mantiene su propio formato de plugins, y Codex cierra la brecha desde su lado con la fuente de marketplace Claude Code (v0.146.0) y /import.¹¹⁸

En términos de Codex: v0.146.0 añade manifiestos de Agent Plugins, publicación de plugins en el workspace y dos marketplaces de plugins adicionales: Amazon Bedrock y Claude Code¹¹⁴; v0.147.0 completa el ciclo con la instalación de Agent Plugins portables y la búsqueda en catálogos locales, personales, de workspace y remotos.¹¹⁶ La publicación en el workspace es la mitad operativamente útil para los equipos: publica plugins en tu propio workspace en lugar de crear un marketplace público o pedir a cada desarrollador que agregue manualmente una fuente de Git.

Las notas de lanzamiento anuncian las superficies de Codex sin publicar sus claves de configuración ni la sintaxis de CLI. Esta entrada registra que la capacidad llegó y qué especifica el estándar, no cómo usarla desde Codex; considera el flujo de creación de manifiestos y cualquier invocación de codex plugin publish como no verificados hasta que la documentación de OpenAI los cubra.

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

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

Consejo para expertos: Los plugins consolidan lo que antes requería configuración MCP independiente, instalación de skills y configuración de conectores de apps. Un solo plugin puede incluir los tres, lo que acelera la incorporación de equipos y hace que la configuración sea más portátil.

Modo de planificación y colaboración

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

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 apruebas - Transmite el plan en una vista específica de la TUI

Modo de orientación

El modo de orientación (activado de forma predeterminada desde v0.98.0) te permite introducir nuevas instrucciones mientras Codex trabaja activamente, sin interrumpir la tarea en curso.¹⁴

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 de orientación siempre está activo en la TUI. Si prefieres esperar a que Codex termine antes de darle instrucciones, escribe normalmente cuando concluya 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 los diffs integrados. 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.⁶¹ Desde v0.107.0, las sesiones de voz en tiempo real permiten seleccionar los dispositivos de micrófono y altavoz, para que puedas elegir hardware específico de entrada y salida de audio.⁶² Eliminada en v0.140.0 y reincorporada en v0.145.0: los controles de voz experimentales de /realtime y sus dependencias de audio se eliminaron de la TUI en v0.140.0 (la transcripción de voz mediante la barra espaciadora no se vio afectada).¹⁰² v0.145.0 reincorpora 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 incluso cuando se dividen entre varias líneas de la TUI (v0.105.0)⁶¹ - Los enlaces a archivos locales se muestran con un formato mejorado (v0.106.0)⁶⁰ - El markdown de la TUI mantiene activos los enlaces web mediante metadatos OSC 8, y las tablas con poco espacio se convierten en registros legibles de clave/valor sin perder los destinos de los enlaces (v0.136.0)¹²⁵ - Se corrigió el manejo de Ctrl+C para que los sub-agents finalicen 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 con 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 de flujo de trabajo: «Ejecuta siempre el linter antes de mostrarme un diff»

Memoria en pipelines

Cuando ejecutas codex exec, las memorias se cargan automáticamente. Esto significa que los pipelines de CI/CD y los scripts aprovechan el 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)

• Eliminación de secretos: Las memorias se analizan automáticamente para detectar secretos antes de guardarlas en el disco
• Reconocimiento del CWD: Los archivos de memoria ahora incluyen el contexto del directorio de trabajo para recuperar 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 con el usuario
• Olvido basado en diffs (v0.106.0): La memoria ahora utiliza un mecanismo de olvido basado en diffs para eliminar datos obsoletos y mantener el almacén de memoria compacto y relevante 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 relevantes recientemente⁶⁰
• Memorias configurables (v0.107.0): Las memorias ahora son totalmente configurables. Usa codex debug clear-memories para restablecer todas las memorias almacenadas y comenzar desde cero; esto 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 valor 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 en 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 individuales y usar un botón de restablecimiento. Ahora, restablecer la memoria conserva los rollouts anteriores en lugar de invalidarlos, por lo que el restablecimiento borra la información disponible para futuras recuperaciones sin afectar la reproducción de sesiones.⁸²

Memoria frente a AGENTS.md

Consejo: Usa /m_update para los datos que deban persistir de manera indefinida. Para el contexto específico de una sesión, indícaselo directamente a Codex 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 reanudar, bifurcar y gestionar flujos de trabajo con múltiples hilos entre CLI y las interfaces de escritorio.

v0.146.0 hace que los hilos sean direccionables. /new y /clear ahora aceptan un nombre de sesión, los hilos importantes se pueden fijar y las conversaciones secundarias permanecen abiertas en lugar de obligarte a 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 fecha. v0.147.0 añade secciones de conversación: las conversaciones se organizan en secciones persistentes ordenadas manualmente, y las transcripciones extensas se exploran de forma incremental en lugar de cargarse por completo.¹¹⁶

Reanudar

Retoma 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 de hilos paginado (v0.145.0) [EXPERIMENTAL]: Un historial de hilos paginado experimental incorpora una reanudación eficiente, búsqueda en todo el historial, nombres de hilos persistentes, compatibilidad con sub-agents y memorias a la gestión de sesiones; el historial se carga página por página en lugar de todo a la vez, algo importante para directorios de trabajo de larga duración con cientos de sesiones. Es experimental: la interfaz puede cambiar entre versiones.¹¹²

Bifurcar

Crea una rama de 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. A partir de v0.146.0, el historial de bifurcaciones está paginado y las bifurcaciones se pueden crear como temporales: una bifurcación temporal no aparece en las listas de hilos, lo que mantiene los experimentos desechables fuera de la lista de hilos que realmente navegas.¹¹⁴ Los cambios 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 arriesgados de forma segura.

Bifurcación de hilos en sub-agents (v0.107.0): Ahora los hilos pueden bifurcarse en sub-agents independientes, lo que permite que una conversación genere flujos de trabajo paralelos que se ejecutan de forma autónoma. Esto amplía el modelo de bifurcación existente: en lugar de solo ramificar la conversación, el hilo bifurcado se convierte en un sub-agent con su propio contexto de ejecución.⁶² A partir de v0.117.0, los sub-agents usan direcciones basadas en rutas (por ejemplo, /root/agent_a) con 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 crear o enviar mensajes a un sub-agent. Los parámetros de mensaje de spawn_agent, send_message y followup_task se marcan como cifrados: Responses API cifra la carga útil cuando el modelo principal emite la llamada a la herramienta, Codex que se ejecuta localmente solo transporta texto cifrado (InterAgentCommunication.encrypted_content, con contenido de texto plano vacío), y API lo descifra en el servidor al entregarlo al modelo receptor.¹⁰⁸ Tres consecuencias prácticas:

• Los registros de tu sesión local ya no contienen texto plano de delegación. Puedes ver que un agente principal creó un sub-agent y qué recibió de vuelta, pero no la instrucción exacta que envió. Si auditas o depuras ejecuciones multiagente desde el historial de sesiones, ese registro ya no está; el issue de regresión abierto que realiza el seguimiento no tenía una corrección vinculada a mediados de julio de 2026.¹⁰⁹ Los eventos del ciclo de vida de extensiones (inicio/detención de subagents, ejecución de herramientas, metadatos de turnos — v0.133.0+) y la observabilidad del app-server son los mecanismos restantes para reconstruir lo ocurrido.⁹⁸
• Los modelos de proveedores personalizados pueden fallar. Un endpoint de modelo que no está configurado para el uso de herramientas cifradas rechaza el esquema cifrado de spawn_agent con un 400 ("declares encrypted parameters but is not configured for encrypted tool use"). Si la delegación multiagente falla con ese error en un proveedor personalizado, se debe al cambio de cifrado, no a tu configuración.¹⁰⁹
• Las notificaciones generadas por Codex siguen siendo legibles. Las notificaciones de finalización de agentes secundarios las produce Codex, por lo que permanecen en texto plano y ahora se muestran como elementos tipados de agent_message en lugar de envoltorios serializados de JSON.¹⁰⁸

OpenAI no ha publicado el modelo de amenazas detrás de este cambio; el PR describe el flujo de texto cifrado sin indicar contra qué protege.

Multi-agent v2 estabilizado (v0.145.0, opción activable): La experiencia de multi-agent v2 que debutó en v0.137.0 y obtuvo delegación cifrada en v0.138.0 ahora está estabilizada como una función activable. v0.145.0 añade modelos de sub-agents configurables, niveles de razonamiento por sub-agent, concurrencia configurable, roles multiagente restaurados y una navegación entre agentes mejorada. Si esperaste para adoptar v2 durante el período de ajustes de v0.137/v0.138, esta es la versión en la que la superficie de configuración se estabiliza: las elecciones de modelo y razonamiento de los sub-agents ahora residen en la configuración en lugar de estar fijadas por el entorno de ejecución.¹¹²

Lista de hilos

Consulta y gestiona las sesiones activas:

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

En la app de escritorio, los hilos se ven en la barra lateral con el historial completo y vistas previas de diferencias.

Ciclo de vida de la sesión

Las sesiones se sincronizan entre CLI y la app 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 --ask-for-approval on-request "fix the CI failure"
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 combinarlo con las canalizaciones estándar de Unix.

Archivado de sesiones (v0.136.0)

Puedes archivar sesiones para mantener enfocada la lista de sesiones que puedes reanudar o bifurcar sin eliminar el historial. Archívalas desde la TUI con /archive o desde la shell:¹²⁵

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

Una sesión archivada queda protegida contra operaciones para reanudarla o bifurcarla hasta que la desarchives, una medida de seguridad para evitar que continúes por accidente una sesión que pretendías retirar. En la misma versión, codex app-server --stdio inicia app-server en modo stdio para integraciones con editores y hosts, y ahora se impide que /diff ejecute asistentes de Git proporcionados por el repositorio (una corrección de seguridad de comandos). En Windows, una ruta de aprovisionamiento alfa añade 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 con 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.

Aviso de inicio de codex exec (v0.130.0). El aviso de inicio de codex exec ya no muestra el texto heredado «research preview». Si tu CI analiza la salida de inicio, ahora el texto del aviso es más breve; los eventos estructurados de --json no han cambiado.⁹¹

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 que otro proceso lo controle: extensiones de IDE, orquestadores personalizados o planos de control remotos. 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 ejecutarse en primer plano, esperar hasta estar listo, informar el estado de la máquina y seguir ofreciendo los comandos explícitos start / stop, al estilo de un daemon, para configuraciones de controladores de larga duración.⁹⁸ La versión v0.143.0 añade 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 enlace de descubrimiento automático; esto resulta útil cuando el proceso controlador se encuentra en un host o segmento de red diferente 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 en memoria todos los turnos a la vez.

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

Ahora los clientes de app-server pueden paginar hilos extensos mediante tres 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 con eficiencia hilos de larga duración, especialmente en implementaciones de remote-control donde el orquestador puede encontrarse en una máquina diferente de la que almacena los archivos de ejecución.⁸² La versión v0.143.0 amplía lo que puede inspeccionar un controlador: ahora los clientes de app-server pueden enumerar los entornos disponibles, listar los hilos descendientes de un hilo y bifurcar el historial a partir de un turno específico; son los elementos básicos que necesita una interfaz de usuario para ramificar una ejecución desde un punto anterior sin tener que reproducirla hasta ese momento.¹⁰⁶

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

Ahora los hilos activos de app-server incorporan los cambios en 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 es la corrección de errores complementaria de codex remote-control: un servidor sin interfaz gráfica y de larga duración puede reconfigurarse en el lugar, en vez de detenerlo.⁹¹

Ejecutores remotos cifrados (v0.141.0)

A partir de 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 tienen que confiar en el relé que los conecta, algo importante cuando tu orquestador controla un app-server a través de los límites de una red. La misma versión hizo que la ejecución remota multiplataforma conserve el directorio de trabajo y la shell nativos del ejecutor, por lo que un controlador de un sistema operativo que maneja un ejecutor de otro ya no provoca que las rutas ni la semántica de la shell se reescriban de forma subyacente. TLS ahora también acepta firmas de certificados P-521 para ofrecer compatibilidad con proxies empresariales.¹⁰³

Codex Cloud y tareas en segundo plano [EXPERIMENTAL]

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 no tienes control sobre la infraestructura.

Codex Cloud ejecuta tareas de forma asíncrona en entornos administrados por OpenAI.⁴ Consulta también GitHub Action y CI/CD para integrar Codex en tu canalización de CI.

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 manera independiente: lee código, ejecuta pruebas y realiza cambios
4. Al terminar, Codex crea una PR o proporciona un diff para que lo revises
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 por entorno:

• Desactivado: El agente no tiene acceso a Internet (opción predeterminada)
• Activado: Lista opcional de dominios permitidos y 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 apto (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 de Cloud

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 Codex

La aplicación de escritorio 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 hacen que la aplicación de escritorio sea una fuente de contexto más completa, en lugar de limitarse a administrar hilos. Usa Appshots cuando Codex necesite conocer el estado de otra aplicación de Mac antes de actuar: Codex captura la ventana que está en primer plano y el texto visible o fuera de pantalla que la aplicación pone a disposición, y guarda el archivo adjunto localmente en el historial de la sesión.⁹⁹

Para trabajar en sitios web y frontend, usa primero el navegador integrado cuando la página no requiera autenticación: les ofrece a Codex y a ti una vista previa renderizada compartida, admite acciones en el navegador como hacer clic, tomar capturas de pantalla, descargar recursos e inspeccionar JavaScript en modo de solo lectura, y te permite marcar regiones de la página con comentarios que Codex puede atender en el siguiente turno.⁹⁹ Para sitios donde hayas iniciado sesión, continúa usando la extensión de Chrome.

Usa Computer Use únicamente cuando una integración estructurada o una vista previa en el navegador no permita verificar la tarea. Puede inspeccionar y operar aplicaciones de Mac autorizadas, pero hereda las aprobaciones y las reglas de sandbox de Codex para editar archivos y ejecutar comandos de shell. El uso con la computadora bloqueada mantiene un alcance limitado: Codex puede acceder temporalmente a las aplicaciones autorizadas durante turnos activos y confiables de Computer Use después de que la Mac se bloquea, con mecanismos para volver a bloquearla y detección de entradas locales.⁹⁹

Modos de hilo

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

Mecánica de aislamiento de Worktree:

Cuando inicias un hilo de Worktree, la aplicación de escritorio: 1. Crea un nuevo git worktree (git worktree add) en un directorio temporal 2. Obtiene 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 una revisión de las diferencias al finalizar; tú eliges qué cambios integrar

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

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 Git, las automatizaciones usan worktrees dedicados 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 para la ejecución de la automatización (App v26.312)⁷² 6. Las automatizaciones se ejecutan según lo programado y ponen los resultados en cola para su revisión

Ejemplos de uso: - Clasificación de incidencias: Clasifica y prioriza automáticamente las incidencias nuevas - Monitoreo de CI: Detecta fallas en las compilaciones y sugiere soluciones - Respuesta a alertas: Reacciona a las alertas de monitoreo con un análisis de diagnóstico - Actualizaciones de dependencias: Busca 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 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 equivalencia total de funciones, incluidas skills, automatizaciones y worktrees, sin necesidad de WSL.⁶⁶

GitHub Action y CI/CD

La GitHub Action oficial 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 desencadenar flujos de trabajo de Codex.

Codex SDK

El TypeScript SDK incorpora 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 de eventos asíncrono para actualizaciones intermedias
• Autenticación de Python SDK (v0.132.0+): El inicio de sesión con clave de API, los flujos de navegador/código de dispositivo de ChatGPT, la inspección de cuentas y el cierre de sesión son rutas principales de SDK.⁹⁷
• Comodidad para turnos de solo texto (v0.132.0+): Los APIs de turno de Python aceptan cadenas simples y devuelven metadatos más completos de TurnResult, con elementos recopilados, tiempos y uso.⁹⁷
• outputSchema: Fuerza una salida final con la estructura de JSON
• Entrada multimodal: Pasa texto + imágenes locales ({ type: "local_image", path: "..." })
• Flujos de trabajo con imágenes (v0.117.0): view_image devuelve URL, las imágenes generadas se pueden volver a abrir y el historial de imágenes se conserva al reanudar una sesión⁷⁵
• view_image en varios entornos (v0.130.0): Para las sesiones que abarcan varios entornos (introducidas en v0.124.0 con selección de entorno + directorio de trabajo por turno, y perfeccionadas en v0.125.0 con entornos persistentes), view_image ahora resuelve las rutas de archivo mediante el entorno seleccionado, en lugar 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 que ejecuta SDK.⁹¹

Configuración de threads 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.

Tiempo 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 actual GPT-5.6 (Sol, Terra, Luna) funciona con una ventana de 272K; GPT-5.5, el modelo insignia de la generación anterior, ofrece 400K en Codex (1M en el API); GPT-5.4 / GPT-5.4-mini (que se retirarán de Codex el 31 de agosto de 2026) ofrecen 1M / 400K; la familia heredada GPT-5.3-Codex funcionaba con 272K de entrada + 128K de salida (400K de presupuesto total). Todos se llenan más rápido de lo que esperarías: adminístralos 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 y documentación local de alta calidad reducen la sobrecarga de exploración (que consume contexto)
3. Usa @ para adjuntar archivos específicos: Haz referencia a los archivos directamente en vez de pedirle a Codex que los encuentre
4. Mantén los prompts enfocados: Los prompts delimitados con archivos exactos consumen menos contexto que una exploración abierta

Eficiencia de tokens

Optimización de velocidad

1. gpt-5.3-codex-spark: Variante de menor latencia para trabajo en pareja interactivo
2. --profile fast: gpt-5.6-luna preconfigurado con razonamiento bajo
3. Ejecución paralela de herramientas: Codex ejecuta lecturas y comprobaciones independientes de forma simultánea, así que estructura los prompts para habilitarlo
4. Bucles orientados a resultados: Pide «implementa, prueba, corrige y detente cuando todo esté en verde» en lugar de 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 reportar un error o depurar una instalación dañada. Recopila el entorno de ejecución local, la configuración, la autenticación, la terminal, la red y el estado en un solo informe, y la propia plantilla de issues 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 se organiza en secciones estables, para que puedas revisar rápidamente la que necesitas:¹²⁰

Cada comprobación incluye un marcador de estado – ✓ correcto, ✗ error, ⚠ advertencia, ○ inactivo – junto con una línea de resumen. --json identifica cada comprobación mediante un identificador estable, lo que permite usarlo en CI o en un script de soporte, en lugar de solo revisarlo visualmente.¹²⁰

El comando ha crecido entre versiones: llegó en v0.131.0, incorporó informes del entorno, Git, la terminal, el servidor de la app y el inventario de hilos en v0.135.0, y agregó detalles del editor y del paginador (con valores sensibles ocultos en JSON) en v0.139.0.^96126122

Úsalo primero, no al final. La mayoría de los reportes de “Codex está dañado” se deben a algo que doctor ya identifica: un modo de autenticación obsoleto, un config.toml que no pudo analizarse o una segunda instalación que oculta la que está 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 TUI durante la sesión:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Nota: codex --verbose no es un flag válido de nivel superior. Usa los subcomandos de depuración y los diagnósticos de 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, degradar después de una versión defectuosa o eliminar por completo el estado, consulta Actualizar, degradar o desinstalar.

Modo de depuración

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

Reportar problemas

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

O reporta problemas en github.com/openai/codex/issues.¹

Codex Security [PREVIEW]

Codex Security entró en la vista previa de investigación el 6 de marzo de 2026, incorporando la revisión de seguridad de aplicaciones con conocimiento del contexto a la pila de Codex.⁷⁷ Está disponible para clientes de ChatGPT Pro, Enterprise, Business y Edu a través de Codex web.

Cómo funciona: Codex Security analiza repositorios para crear un modelo de amenazas específico para cada proyecto, identifica vulnerabilidades clasificadas según su impacto en el mundo real y pone a prueba los hallazgos en un entorno sandbox para validarlos. El agente presenta hallazgos con mayor grado de confianza junto con correcciones, lo que reduce el ruido de errores insignificantes.

Rendimiento: Durante la vista previa de investigación, Codex Security analizó 1,2 millones de commits e identificó 10.561 vulnerabilidades de alta gravedad. La precisión mejoró con el tiempo — redujo el ruido en un 84 %, la gravedad sobreinformada en más de un 90 % y las tasas de falsos positivos a la mitad. El sistema ha encontrado vulnerabilidades reales en OpenSSH, GnuTLS y Chromium, con 14 CVE asignados.⁷⁷

Nota: Codex Security es independiente del modelo de seguridad de sandbox integrado de CLI. El sandbox protege tu máquina de Codex; Codex Security protege tu base de código de vulnerabilidades.

Implementación empresarial

Controles de administración (requirements.toml)

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

v0.146.0 agrega reconocimiento de planes empresariales y controles de administrador sobre las actualizaciones dentro de la aplicación.¹¹⁴ En una flota administrada, esto marca la diferencia entre que los desarrolladores actualicen por su cuenta CLI cuando noten una nueva versión y que el administrador decida cuándo se distribuye una versión. Las notas de la versión anuncian el control sin publicar su clave de requirements.toml; considera el nombre exacto del ajuste como no verificado hasta que OpenAI lo documente.

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

# 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 de config.toml a nivel de usuario, que establece preferencias, requirements.toml es una capa de restricciones estrictas que limita los valores que los usuarios pueden seleccionar y que estos no pueden anular. Las reglas de requisitos de administración solo pueden solicitar o prohibir (nunca permitir silenciosamente).

Configuración de MDM en macOS

Distribuye mediante MDM usando el dominio de preferencias com.openai.codex.²¹ Codex respeta las cargas útiles estándar de MDM de macOS (Jamf Pro, Fleet, Kandji, etc.). Codifica TOML en base64 sin ajuste 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 campos de requisitos no establecidos, por lo que las capas administradas de mayor precedencia siempre ganan. Los requisitos de la nube se aplican según el mejor esfuerzo; si la obtención falla o se agota el tiempo de espera, Codex continúa sin la capa de nube.

Integración de OpenTelemetry

Codex admite la propagación del contexto de trazas de OpenTelemetry desde las variables de entorno estándar de OTel hasta las llamadas de OpenAI API. 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_* (endpoint, nombre del servicio, atributos de recursos)
• El contexto de trazas se propaga a través de Codex hasta las llamadas de API, lo que permite una observabilidad de extremo a extremo
• Usa atributos de recursos para etiquetar las trazas por equipo, entorno o proyecto
• Ten en cuenta los requisitos de privacidad al habilitar el registro de prompts/herramientas: las trazas pueden contener fragmentos de código
• Metadatos de trazas de OpenTelemetry configurables (v0.130.0+). Además de la envoltura estándar de OTEL_RESOURCE_ATTRIBUTES, el crate codex-otel ahora expone metadatos de trazas configurables para que los administradores puedan etiquetar trazas con dimensiones específicas de la organización (centro de costos, ID de proyecto, referencia de ticket) sin reconstruir OTEL_RESOURCE_ATTRIBUTES desde cero en cada invocación. Combina esto con los análisis más completos de revisión/comentarios incorporados en la misma versión para depuración y clasificación unificadas en las sesiones de CLI, app-server y control remoto.⁹¹

Acceso empresarial

• ChatGPT Business / Enterprise / Edu: Acceso controlado por administradores de la organización, con requisitos obtenidos de la nube que se aplican automáticamente. 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/proyecto estándar de API. OpenAI publica informes SOC 2 Tipo II y SOC 3; 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 a nivel de sistema de archivos

Manejo de datos y cumplimiento: - Las entradas/salidas de API no se usan para entrenamiento según los términos de Business/Enterprise/API de OpenAI - Para residencia de datos, el tráfico de API de OpenAI se enruta de forma predeterminada a través de infraestructura ubicada en EE. UU.; para requisitos de residencia de datos en la UE, consulta al equipo de ventas Enterprise de OpenAI - Las transcripciones de sesión se almacenan localmente; solo las llamadas de API salen de la máquina - ChatGPT Enterprise admite marcos de cumplimiento que incluyen SOC 2, GDPR y CCPA

Estrategia de implementación

Implementación gradual recomendada para organizaciones:

1. Piloto (semana 1-2): Implementa para 3-5 ingenieros senior con requirements.toml que imponga el modo de sandbox untrusted y búsqueda web cached. Recopila comentarios sobre patrones de AGENTS.md y necesidades de servidores MCP.
2. Expansión del equipo (semana 3-4): Implementa para todo el equipo. Distribuye config.toml estándar del equipo mediante MDM o el repositorio. Habilita el sandbox workspace-write para repositorios de confianza.
3. Integración de CI (semana 5-6): Agrega codex-action a las canalizaciones de CI/CD para revisión automatizada de PR y generación de pruebas. Usa --ephemeral para mantener los costos previsibles.
4. Toda la organización (mes 2+): Implementa mediante MDM con requirements.toml que imponga servidores MCP aprobados, políticas de sandbox y listas de modelos permitidos.

Patrones de auditoría

Haz seguimiento del uso de Codex y aplica el cumplimiento:

• Trazas de OpenTelemetry: Supervisa el volumen de llamadas de API, el uso de tokens y la latencia por equipo
• Persistencia de sesiones: Audita ~/.codex/sessions/ para revisión de cumplimiento (deshabilítala con --ephemeral en contextos sensibles)
• Aplicación de identidad de MCP: requirements.toml registra intentos de servidores bloqueados; revísalos para detectar uso no autorizado de herramientas
• Registro de auditoría de Git: Todos los cambios de archivos de Codex pasan por git estándar; revísalos mediante el historial de ramas y los diffs de PR

Mejores Prácticas y Antipatrones

Patrones de prompting

1. Prompts guiados por restricciones: Comienza con los límites. “NO cambies los contratos de API. Solo refactoriza la implementación interna.”
2. Pasos de reproducción estructurados: Los pasos numerados generan mejores correcciones de errores que las descripciones vagas
3. Solicitudes de verificación: Termina con “Ejecuta lint + el conjunto de pruebas relevante más pequeño. Informa los comandos y los resultados.”
4. Referencias a archivos: Usa @filename para adjuntar archivos específicos al contexto
5. Bucles guiados por resultados: “Implementa, ejecuta pruebas, corrige los fallos y detente solo cuando todas las pruebas pasen.” Codex itera hasta terminar

Filosofía de pruebas

La comunidad coincide en la colaboración con IA guiada por 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 patrones de programación de Tiger Style
• Proporciona el texto exacto de los archivos al solicitar parches. Codex usa coincidencias estrictas, no aplicación de parches difusa basada en AST

Mejores prácticas de gestión del contexto

• Proporciona documentación local de alta calidad en lugar de depender de búsquedas web
• Mantén Markdown estructurado 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 rastreados para evitar fallos al aplicar parches
• Mantén AGENTS.md conciso, ya que las instrucciones largas se expulsan del contexto

Flujo de trabajo con Git

• Siempre crea una rama nueva antes de ejecutar Codex en repositorios desconocidos
• Usa flujos de trabajo basados en parches (git diff / git apply) en lugar de ediciones directas
• Revisa las sugerencias de Codex como si fueran PRs de revisión de código
• Usa /diff para verificar los cambios antes de hacer commit

Skills y prompts de la comunidad

El repositorio feiskyer/codex-settings proporciona 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 PRs - github-pr-reviewer [pr-number]: Flujos de trabajo de revisión de 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 entre varias sesiones con seguimiento del progreso - deep-research: Orquestación paralela de subtareas - kiro-skill: Canalización de requisitos → diseño → tareas → ejecución

Antipatrones

Errores comunes que desperdician tokens, producen malos resultados o generan flujos de trabajo frustrantes.

Antipatrones de costo

Antipatrones de contexto

Antipatrones de flujo de trabajo

Antipatrones de prompts

Recetas de flujo de trabajo

Patrones integrales para escenarios de desarrollo comunes.

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 diario de desarrollo

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 haz 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 redirígelo:

[Tab] Also add a migration script using Alembic

Después de que Codex ejecute el plan, 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."

Consulta el progreso más tarde:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Aplica la corrección localmente cuando termine:

codex apply <TASK_ID>

Guía de migración

Desde Claude Code

Diferencias clave que debes entender:

• El sandbox está en el nivel del sistema operativo: Codex usa Seatbelt/Landlock, no contenedores. Las restricciones operan en el nivel del kernel, por debajo de la capa de aplicación.
• Los hooks se están ampliando: Codex ahora admite 5 eventos de hooks: SessionStart, Stop y UserPromptSubmit (v0.114.0–v0.116.0, experimentales), además de AfterAgent (v0.99.0) y AfterToolUse (v0.100.0). El sistema cubre el ciclo de vida de la sesión, la interceptación de prompts y la automatización a nivel de herramientas, aunque los más de 12 eventos de ciclo de vida de Claude Code aún ofrecen una cobertura más amplia. Para patrones de automatización que todavía no están cubiertos, usa instrucciones de AGENTS.md o skills.
• Sub-agents v2 (v0.117.0): Los sub-agentes ahora usan direcciones basadas en rutas (por ejemplo, /root/agent_a), con mensajería estructurada entre agentes y listado de agentes.⁷⁵ Esto amplía la maquinaria existente (máximo 6 simultáneos, reducido desde 12 en v0.91.0). Los roles multiagente siguen siendo personalizables mediante configuración (v0.104.0+).⁴⁷ La v0.105.0 añadió spawn_agents_on_csv para distribuir trabajo entre filas con seguimiento de progreso y ETA.⁶¹ Codex todavía carece de la UX explícita de la herramienta Task de Claude Code para la delegación dirigida por el usuario; usa cloud tasks u orquestación de SDK para patrones de delegación.
• AGENTS.md funciona entre herramientas: Tu AGENTS.md funciona en Cursor, Copilot, Amp, Jules, Gemini CLI y más de 60.000 proyectos de código abierto. CLAUDE.md es exclusivo de Claude.
• Los perfiles sustituyen el cambio manual: En lugar de cambiar indicadores en cada ejecución, define perfiles en config.toml.

Desde GitHub Copilot

Lo que obtienes: - Sandboxing en el nivel del sistema operativo (Seatbelt/Landlock: aplicado por el kernel frente a un enfoque basado en contenedores) - Delegación de cloud tasks con codex apply - Perfiles de configuración para cambiar de flujo de trabajo - Aplicación de escritorio con aislamiento mediante worktrees

Desde Cursor

Tarjeta de referencia rápida

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                 ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers               ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Aug 2026)                                            ║
║  gpt-5.6-sol           Recommended default ("Power", 272K)    ║
║  gpt-5.6-terra         Everyday model (272K)                  ║
║  gpt-5.6-luna          Fast + affordable (272K)               ║
║  gpt-5.5               Previous-gen flagship (400K in Codex)  ║
║  gpt-5.4 / -mini       Retire from Codex Aug 31, 2026         ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Registro de cambios