Codex CLI: La referencia técnica definitiva

TL;DR: Codex es un agente de programación multisuperficie que lee tu codebase, ejecuta comandos en un sandbox a nivel del sistema operativo, parchea archivos y delega tareas a la nube. Domina 5 sistemas centrales (config.toml, modelo de sandbox/aprobación, AGENTS.md, MCP y skills) y Codex se convierte en un multiplicador de fuerza. Usa profiles para cambiar de contexto, /compact para administrar el presupuesto de contexto, /goal para objetivos de trabajo persistentes y AGENTS.md para instrucciones de proyecto entre herramientas que funcionan en Codex, Cursor, Amp y más. GPT-5.5 (lanzado el 23 de abril de 2026) es el valor predeterminado recomendado en Codex: ventana de contexto de 400K en Codex (1M en API), $5/$30 por MTok, 82,7 % en Terminal-Bench 2.0 SOTA.⁸³ A partir de CLI v0.140.0 (stable, 15 de junio de 2026), /usage muestra la actividad diaria, semanal y acumulada de tokens de la cuenta, las sesiones pueden eliminarse permanentemente con codex delete / /delete (con salvaguardas de confirmación), /import migra selectivamente la configuración inicial, la configuración de proyecto y los chats recientes desde Claude Code, al escribir @ se abre de forma predeterminada un menú unificado de menciones para archivos, plugins y skills, y la autenticación administrada con clave de API de Amazon Bedrock llega junto con almacenamiento local cifrado para credenciales de CLI y MCP OAuth; los controles de voz experimentales de /realtime se eliminaron de la TUI.¹⁰² A partir de CLI v0.139.0 (stable, 9 de junio de 2026), code mode puede llamar directamente a la búsqueda web independiente (incluso desde llamadas de herramienta JavaScript anidadas) y recibir resultados en texto plano; los esquemas de entrada de herramientas/conectores ahora preservan construcciones oneOf/allOf para mejorar la compatibilidad con esquemas grandes y MCP; codex doctor agrega detalles del entorno del editor y pager (ocultando valores sensibles en JSON); y el marketplace de plugins expone fuentes en codex plugin marketplace list --json, con listados más rápidos gracias al catálogo en caché.¹⁰³ v0.138.0 (8 de junio) agregó /app para pasar 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 de esfuerzo de razonamiento y dio a la automatización de plugins una salida JSON estructurada.¹⁰⁴ v0.137.0 (4 de junio) lanzó multi-agent v2 (runtime conservado por thread, seguimientos y valores predeterminados de metadatos más limpios, 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.¹⁰⁵ A partir de CLI v0.135.0 (28 de mayo de 2026), codex doctor informa un inventario más completo del entorno, Git, terminal, app-server y threads; /status muestra detalles de conexión remota y versión del servidor cuando la TUI está conectada de forma remota; el modo vim incorporó edición con objetos de texto, mejor comportamiento de palabra/fin de línea y una interrupción de turno configurable; /permissions ahora entiende profiles de permisos con nombre y muestra los personalizados; las compilaciones empaquetadas de Codex descubren y usan el helper zsh parcheado incluido en macOS compatibles; y Python SDK expone presets amigables de Sandbox para APIs de thread y turno.¹⁰⁷ v0.134.0 (26 de mayo de 2026) introdujo búsqueda en el historial local de conversaciones, con coincidencias de contenido sin distinguir mayúsculas/minúsculas y vistas previas de resultados; hizo de --profile el selector principal de profiles en CLI, permisos de TUI y flujos de sandbox (las configuraciones de profiles heredadas se rechazan con guía de migración); mejoró la configuración de MCP con destino de entorno por servidor y opciones OAuth para servidores HTTP streamable; hizo más confiables los esquemas de herramientas de conectores al preservar $ref/$defs locales y compactar esquemas demasiado grandes; permitió que herramientas MCP de solo lectura se ejecuten concurrentemente cuando anuncian readOnlyHint; y agregó contexto más rico para extensiones y hooks, incluido el historial de conversación para herramientas de extensión.¹⁰¹ v0.133.0 (21 de mayo de 2026) activó goals por defecto, con almacenamiento dedicado y seguimiento de progreso; codex remote-control recibió preparación/estado en primer plano, además de inicio/detención estilo daemon; los profiles de permisos incorporaron listas de APIs, herencia, requirements.toml administrado, actualización en runtime y una integración más sólida con el sandbox de Windows; el descubrimiento de plugins muestra versiones instaladas, raíces de marketplace y colecciones remotas; y las extensiones pueden observar inicio/detención de subagentes, ejecución de herramientas, metadatos de turno y procesamiento asíncrono de aprobaciones/turnos. La actualización del 21 de mayo de la app Codex agregó Appshots para las ventanas frontales de Mac, Goal mode GA en app/IDE/CLI, mejoras en la anotación del navegador dentro de la app y Computer Use bloqueado opcional para usuarios de Mac elegibles.⁹⁹¹⁰⁰ v0.132.0 (20 de mayo de 2026) agregó autenticación de Python SDK de primera clase, APIs de turno solo texto más simples, TurnResult más completo, codex exec resume --output-schema, inicio más rápido de la TUI, registro de executor remoto respaldado por autenticación y preservación de fidelidad de imagen en turnos de app-server. Sigue prefiriendo flags explícitos de sandbox/aprobación o profiles de permisos por encima del --full-auto heredado; js_repl sigue eliminado.^{86878991969798}

Codex opera como un agente de programación multisuperficie, no como un chatbot que escribe código. CLI lee tu codebase, ejecuta comandos en un sandbox, parchea archivos, se conecta a servicios externos mediante MCP y delega tareas de larga duración a la nube. Se ejecuta localmente, pero piensa de forma global; la misma inteligencia impulsa 5 superficies distintas según tu forma de trabajar, incluida la nueva extensión de Chrome que ejecuta Codex en tu navegador sin tomarlo por completo.⁹⁰

La diferencia entre un uso casual y uno efectivo de Codex se reduce a 5 sistemas centrales. Domínalos y Codex se convierte en un multiplicador de fuerza:

1. Sistema de configuración: controla el comportamiento mediante config.toml
2. Modelo de sandbox y aprobación: delimita lo que Codex puede hacer
3. AGENTS.md: define contratos operativos a nivel de proyecto
4. Protocolo MCP: amplía las capacidades hacia servicios externos
5. Sistema de Skills: empaqueta experiencia de dominio reutilizable

Pasé meses usando Codex junto con Claude Code en codebases de producción, pipelines de CI/CD y flujos de trabajo de equipo. Esta guía destila esa experiencia en la referencia completa que me habría gustado tener al empezar. Cada función incluye sintaxis real, ejemplos de configuración concretos y los casos límite que suelen hacer tropezar incluso a usuarios con experiencia.

Nota de estabilidad: Las funciones marcadas como [EXPERIMENTAL] o under development pueden cambiar entre versiones. A partir de v0.133.0 (21 de mayo de 2026), goals está activado por defecto, los profiles 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 app-server en primer plano o daemonizado. Codex Cloud y code mode siguen siendo experimentales o están en desarrollo, mientras que CLI central, sandboxing, AGENTS.md, config.toml, Skills, hooks, herramientas multi-agent, plugins, Browser, Computer Use y Appshots son superficies estables o documentadas para usuarios según la plataforma y el plan. v0.132.0 completa la autenticación de Python SDK y la automatización estructurada de resume; v0.131.0 agregó codex doctor, búsqueda unificada de menciones con @, comandos de marketplace para CLI, uso compartido de plugins con conciencia de versión, remote-control administrado por daemon con activación/desactivación en runtime, entornos respaldados por registro y hardening adicional del sandbox de Windows.⁹⁶⁹⁷⁹⁸ El --full-auto heredado sigue obsoleto y js_repl sigue eliminado.⁸⁶⁸⁷

Puntos clave

• Cinco superficies, un solo cerebro: CLI, la app de escritorio, la extensión de IDE, las tareas en la nube y la nueva extensión de Chrome comparten la misma inteligencia GPT-5.x-Codex, así que elige la superficie que mejor encaje con tu flujo de trabajo.⁹⁰
• Sandboxing a nivel del sistema operativo: Codex aplica restricciones de sistema de archivos y 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 open source. Escribe una vez y úsalo en todas partes.
• Los perfiles ahorran el costo de cambiar de contexto: Define presets de configuración con nombre (fast, careful, auto) y cambia entre ellos con --profile.
• La gestión del contexto importa: GPT-5.5 ofrece una ventana de contexto de 400K en Codex y de 1M en API; GPT-5.4 mini también ofrece 400K para trabajo con subagentes de menor latencia; GPT-5.3-Codex ofrece 272K de entrada. 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 2.500 líneas; empieza donde encaje tu nivel de experiencia:

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

Cómo funciona Codex: el modelo mental

Antes de profundizar en las funciones, entiende cómo la arquitectura de Codex moldea todo lo que haces con él. El sistema opera en cuatro 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   │
├─────────────────────────────────────────────────────────┤
│  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. Al 23 de abril de 2026, gpt-5.5 es el modelo recomendado cuando está disponible: contexto de 400K en Codex (1M en API), 82,7% en Terminal-Bench 2.0 SOTA. gpt-5.4 sigue siendo el valor predeterminado alternativo durante el despliegue (contexto de 1M, uso nativo de computadora).⁸³⁶⁴ Lee archivos, escribe patches, ejecuta comandos de shell y razona sobre tu codebase. 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 a syscalls. El sandbox opera a nivel del kernel, no dentro de contenedores. Luego, la política de aprobación decide cuándo pedir confirmación humana.

Capa de extensión: MCP conecta servicios externos (GitHub, Figma, Sentry). Skills empaqueta flujos de trabajo reutilizables que Codex carga bajo demanda. Las apps se conectan a conectores de ChatGPT. La búsqueda web agrega contexto en tiempo real desde internet.

Capa de superficie: CLI para usuarios avanzados de terminal y automatización. App de escritorio para gestión de proyectos multihilo. Extensión de IDE para ciclos de edición-compilación-prueba. Cloud para tareas asíncronas que se ejecutan de forma independiente.

La idea clave: La mayoría de los usuarios solo usa una superficie. Los usuarios avanzados usan las cinco: Cloud para tareas de larga duración, CLI para operaciones deterministas de repositorio, extensión de IDE para ciclos de programación ajustados, la app de escritorio para planificación y coordinación, y Chrome para flujos de trabajo en navegador con sesión iniciada.

Tabla de contenidos

1. ¿Cómo instalo Codex?
2. Inicio rápido: tu primera sesión
3. Superficies principales de interacción
4. Análisis profundo 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. Code Mode
13. Runtime REPL de JavaScript
14. ¿Qué son Skills?
15. Plugins
16. Plan Mode y colaboración
17. Sistema de memoria
18. Gestión de sesiones
19. Modo no interactivo (codex exec)
20. Codex Cloud y tareas en segundo plano
21. La Codex Desktop App
22. GitHub Action y CI/CD
23. Codex SDK
24. Optimización del rendimiento
25. ¿Cómo depuro problemas?
26. Implementación empresarial
27. Mejores prácticas y anti-patrones
28. Recetas de flujo de trabajo
29. Guía de migración
30. Tarjeta de referencia rápida
31. Changelog
32. Referencias

¿Cómo instalo Codex?

Administradores 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

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

Para macOS y Linux, hay disponible un script de instalación de una sola 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 por plataforma desde GitHub Releases¹:

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 (promovido desde experimental en v0.100.0). WSL también es compatible²

Autenticación

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

Dos rutas de autenticación:

1. Cuenta de ChatGPT (recomendada): Inicia sesión con tu suscripción existente Plus, Pro, Team, Business, Edu o Enterprise. Acceso completo a 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 (cloud threads) 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, con respaldo en archivo).

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

Verificar la instalación

codex --version
# codex-cli 0.133.0

Inicio rápido: tu primera sesión

Pasa de cero a 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 el codebase. No se hacen cambios en el modo predeterminado suggest.

5. Haz 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 apruébalo para iniciar la ejecución.

7. Revisa tu trabajo:

> /diff

Consulta todos los cambios que Codex hizo 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 Profiles) - Prueba codex exec para automatización no interactiva (consulta Modo no interactivo)

Superficies principales de interacción

Codex ofrece cuatro interfaces distintas respaldadas por la misma inteligencia. Cada superficie optimiza 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 terminal UI es una aplicación de pantalla completa con:

• Composer: 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 clave de TUI:

Cambio en la línea de estado (v0.121.0): El antiguo medidor de ventana de contexto en 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 flujo de trabajo (v0.129.0): Resume y fork ahora son más fáciles de acceder desde un selector rediseñado, y un nuevo modo raw scrollback te permite desplazarte por la transcripción sin renderizar cuando necesitas copiar comandos o salida del modelo literalmente. Útil al clasificar una sesión larga de depuración o al canalizar salida a otra herramienta.⁸⁹

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

2. Codex Desktop App (macOS + Windows)

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

La app de escritorio agrega capacidades que CLI no tiene:

• Multitarea: Ejecuta varios agentes en paralelo en distintos proyectos al mismo tiempo
• Aislamiento con git worktree: Cada hilo trabaja sobre una copia aislada de tu repo
• Revisión de diff integrada: 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 issues, monitoreo de CI, respuesta a alertas)
• Appshots: Adjunta la ventana frontal de una app de Mac a un hilo con una captura de pantalla más el texto disponible
• Comentarios en navegador integrado: Previsualiza páginas locales o públicas, deja comentarios sobre elementos/áreas y permite que Codex atienda comentarios visuales precisos
• Computer Use: Permite que Codex opere apps de Mac permitidas para trabajo GUI acotado; el uso bloqueado es opcional para turnos elegibles de Computer Use en Mac remota

Cuándo usar la app frente a CLI: Usa la app de escritorio cuando coordines varios flujos de trabajo o necesites revisión visual de diff. Usa CLI cuando quieras composición con terminal, scripting 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:

• Agent mode de forma predeterminada: Lee archivos, realiza ediciones, ejecuta comandos
• Ediciones inline: Sugerencias sensibles al contexto en tus archivos activos
• Sesiones compartidas: Las sesiones se sincronizan entre CLI y la extensión IDE
• Misma autenticación: Inicia sesión con una cuenta de ChatGPT o clave API

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

4. Codex Cloud [EXPERIMENTAL]

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

• Fire and forget: Pon en cola tareas que se ejecutan independientemente de tu máquina local
• Ejecución en paralelo: Ejecuta varias tareas en la nube simultáneamente
• Creación de PR: Codex crea pull requests a partir del trabajo completado
• Aplicación local: Trae los resultados de la nube a tu repo local con codex apply <TASK_ID>

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

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

5. Codex for Chrome [NEW]

Codex se distribuye como una extensión de navegador para Chrome, lo que agrega una quinta superficie junto a CLI, la app de escritorio, la extensión IDE y la nube. La extensión está diseñada para acompañar tu navegación normal en lugar de tomarla por completo: Codex trabaja en paralelo en varias pestañas en segundo plano, y tú mantienes el control sobre qué sitios puede tocar.⁹⁰

• Ejecución en pestañas paralelas: Codex opera en varias pestañas a la vez sin bloquear la pestaña en primer plano.
• Control por sitio: Defines una lista de sitios web con los que Codex puede interactuar; de forma predeterminada, no tiene acceso.
• El navegador como banco de trabajo: La extensión es ideal para trabajo en 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; no reemplaza a CLI en repos locales.
• Mismo cerebro: Codex for Chrome ejecuta la misma inteligencia GPT-5.x-Codex que usan las otras superficies, por lo que una configuración de AGENTS.md o de skills que funciona en CLI lleva las mismas convenciones al trabajo impulsado por navegador.

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

Análisis profundo del sistema de configuración

Codex usa TOML para la configuración. Entender la jerarquía de precedencia es fundamental porque determina qué configuración prevalece cuando hay conflictos.

Precedencia (de mayor a menor)

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

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

Ubicaciones de archivos de configuración

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

Referencia completa de configuración

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.5"                      # Recommended model when available
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 400000           # 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

Profiles

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

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

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

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

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

Activa un profile:

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

Consejo experto: Define un profile 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 cable chat/completions (wire_api = "chat") quedó obsoleta para modelos alojados por OpenAI, y OpenAI anunció su eliminación en febrero de 2026.³⁴ Es posible que los proveedores locales (Ollama, LM Studio) aún acepten 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 defínelo en la configuración:

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

Anulaciones de configuración en línea

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

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

¿Qué modelo debo elegir?

Modelos disponibles (abril de 2026)

GPT-5.5 (23 de abril de 2026) es la opción recomendada por OpenAI para la mayoría de las tareas de Codex: codificación compleja, uso de computadora, 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 expone la totalidad del 1M. Precios (API): $5 entrada / $30 salida por MTok (2× la tarifa de GPT-5.4; OpenAI indica un aumento efectivo de ~20% tras las mejoras de eficiencia de tokens). Benchmarks: 82,7% Terminal-Bench 2.0 (SOTA actual entre los modelos disponibles públicamente), 84,9% GDPval (44 ocupaciones), 78,7% OSWorld-Verified, 98,0% Tau2-bench Telecom (sin ajuste de prompt). OpenAI usó GPT-5.5 + Codex internamente para reescribir la infraestructura de servicio antes del lanzamiento — produjo un aumento del 20% en la velocidad de generación de tokens.⁸³

GPT-5.4 sigue disponible en todas las superficies de Codex (CLI, app, extensión IDE, cloud).⁶⁴ La lista exacta de modelos varía según la cuenta y el despliegue. Revisa tu caché local: ~/.codex/models_cache.json.

Nota de obsolescencia (11 de marzo de 2026): Los modelos GPT-5.1 ya no están disponibles en ChatGPT. Las conversaciones existentes continúan automáticamente en GPT-5.3 Instant, GPT-5.4 Thinking o GPT-5.4 Pro. GPT-5.1-Codex-Mini sigue disponible vía API y CLI para cargas de trabajo sensibles al costo.⁷¹

Nota sobre el plan gratuito (5 de mayo de 2026): GPT-5.5 Instant se desplegó al plan gratuito de ChatGPT el 5 de mayo de 2026. Esto amplía la audiencia para la familia GPT-5.5 más allá de los planes pagos, aunque el acceso a Codex CLI sigue requiriendo una suscripción Plus / Pro / Business / Enterprise / Edu / Go válida o una clave 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 — usa solo el 30% de la cuota de GPT-5.4. Ideal para delegación de subagentes: deja que GPT-5.4 maneje la planificación y coordinación mientras los subagentes de GPT-5.4 mini se encargan de subtareas más acotadas (búsqueda en el código, revisión de archivos, procesamiento de documentos) en paralelo.⁷⁶

Diagrama de selección de modelo

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ 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.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

Esfuerzo de razonamiento

Controla cuánto “piensa” el modelo antes de responder:

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

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

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

Controles rápidos de razonamiento en TUI (v0.124.0+).⁸⁵ En una sesión TUI interactiva, Alt+, baja el razonamiento un nivel y Alt+. lo sube un nivel — útil cuando un problema difícil a mitad de sesión amerita una escalada temporal medium → high → xhigh sin recurrir a /effort o -c. Cuando aceptas una actualización de modelo a mitad de sesión, el razonamiento se restablece al predeterminado del nuevo modelo en lugar de mantener el nivel anterior.

Cambio de modelo

Cambia de modelo a mitad de sesión con el comando slash /model, o configúralo por 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 modelo para conocer las capacidades y Marcos de decisión para elegir el modelo adecuado para cada tarea.

Acceso a través de los planes de ChatGPT

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

Actualización de precios de abril de 2026: El precio anual de Business bajó de $25 a $20/asiento/mes. Los asientos solo Codex con precios de pago por uso ya están disponibles para los espacios de trabajo Business y Enterprise — sin tarifa fija de asiento, facturados según el consumo de tokens.⁷⁹ Los límites promocionales 2x para los planes pagos (desde el lanzamiento de la Desktop App en febrero de 2026) siguen activos.¹⁶

Aumento de límites de uso de mayo de 2026 (hasta el 31 de mayo de 2026): Codex en el plan Plus funciona con un límite de 25× cada 5 horas (frente al aumento estándar de 20×), y el nivel de $100/mes está duplicado durante la misma ventana. Aprovecha este período para ejecutar lotes más largos de tareas en la nube o ejecuciones de agentes con mayor rendimiento sin chocar con tu límite normal de 5 horas.⁸⁹

Costos de créditos

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

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

Cuando uses Codex a través de la API, OpenAI factura el uso por token según los precios estándar de la API de OpenAI para el modelo seleccionado (más cualquier descuento aplicable por almacenamiento en caché de prompts). Consulta la página oficial de precios de API para ver las tarifas actuales.²⁰

Estrategias de optimización de costos

1. Usa perfiles: Crea un perfil fast con gpt-5.1-codex-mini y model_reasoning_effort = "low" para tareas rutinarias
2. Reserva el razonamiento alto: Solo usa xhigh para problemas genuinamente difíciles, ya que cuesta 3-5x más tokens
3. Usa --ephemeral: Omite la persistencia de sesión 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 para flujos de trabajo de automatización
6. Monitorea el uso: Consulta /status en la TUI y los paneles de facturación de tu organización

Ejemplos de costos del mundo real

Costos representativos de API para tareas comunes (gpt-5.3-codex a precios estándar, razonamiento medio):

Los costos varían según el esfuerzo de razonamiento, el almacenamiento en caché y la longitud de la conversación. Usa gpt-5.1-codex-mini para tareas rutinarias para reducir los costos en un ~40-60%. Los tokens de entrada en caché se facturan con descuento.

Sobrecarga oculta de tokens

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

Consejo experto: Monitorea tu uso real vía /status en la TUI. El conteo de tokens incluye toda la sobrecarga, no solo tus mensajes visibles. Si los costos te sorprenden, revisa cuántos servidores de MCP están conectados — cada uno añade definiciones de herramientas a cada llamada de API.

Gestión de costos en equipo

Estrategias para el control de costos en equipo: - Configura requirements.toml para imponer límites de modelo y esfuerzo de razonamiento a nivel de toda la organización - Usa gpt-5.1-codex-mini para CI/CD — los pipelines automatizados rara vez necesitan el máximo razonamiento - Presupuestos basados en perfiles — define perfiles ci, review y dev con techos de costo apropiados - Monitorea vía OpenTelemetry — las implementaciones empresariales pueden exportar telemetría de uso a stacks de observabilidad existentes

Marcos de Decisión

Cuándo Usar Cada Superficie

Cuándo Usar Cada Modo de Sandbox

Cuándo Usar Cada Nivel de Razonamiento

Modo Plan vs 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 vs Tab

Regla práctica: Enter = “detente, escucha esto ahora”. Tab = “cuando termines, haz también esto”.

Desktop App vs 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?

Empareja tu tarea con un perfil preconfigurado:

Configuración de config.toml:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

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

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

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Cambia de perfil por sesión: codex --profile careful

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

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

Capa 1: Sandbox (lo que 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 por modo compilados en tiempo de ejecución y aplicados por el kernel⁶. A partir de v0.121.0, los perfiles de sandbox de macOS pueden permitir Unix sockets específicos (por ejemplo, docker.sock, sockets IPC del editor), y la resolución DNS privada ya no está bloqueada de forma predeterminada.⁸²
• Linux: Landlock para restricciones del sistema de archivos + seccomp para filtrado de syscall. Un proceso auxiliar independiente (codex-linux-sandbox) proporciona aislamiento de defensa en profundidad.⁵ Bubblewrap (bwrap) se incluye como dependencia vendorizada y se compila como parte de la build de Linux (promovido desde opcional en v0.100.0)⁷. v0.117.0 mejoró la confiabilidad del sandbox en distribuciones antiguas con configuraciones de kernel heredadas.⁷⁵ v0.129.0 reforzó el inicio del sandbox en Linux y actualizó Bubblewrap vendorizado a 0.11.2 con parches de seguridad upstream; v0.130.0 agregó más refuerzos de inicio.⁸⁹⁹¹
• Windows: sandbox nativo con tokens restringidos (promovido desde experimental en v0.100.0). WSL también es compatible (hereda Landlock + seccomp de Linux). v0.117.0 incluye mejoras del sandbox con tokens restringidos para un mejor aislamiento de procesos.⁷⁵ v0.130.0 otorga a los usuarios del sandbox acceso a la caché de binarios del runtime de escritorio para que el sandbox de Windows pueda resolver binarios de runtime de forma confiable para usuarios con workspace-sandbox.⁹¹

Por qué esto importa: a diferencia del sandboxing basado en contenedores (Docker), el sandboxing a nivel del sistema operativo es más rápido, más ligero y más difícil de evadir. El kernel aplica las restricciones antes de que Codex siquiera vea la llamada al sistema.

Correcciones de seguridad: - Omisión del sandbox mediante zsh-fork (v0.106.0): se corrigió una vulnerabilidad donde la ejecución de shell mediante bifurcación de zsh podía eludir las restricciones del sandbox.⁶⁰ Si estás en una versión anterior, actualiza de inmediato. - Límite de tamaño de entrada (v0.106.0): Codex ahora aplica un límite de entrada de aproximadamente 1 millón de caracteres para evitar bloqueos por payloads excesivamente grandes.⁶⁰ - Perfil seguro de devcontainer (v0.121.0): un nuevo perfil de cliente reforzado para devcontainers de Docker usa Bubblewrap para sandboxing dentro del contenedor. WSL2 es compatible; WSL1 se rechaza explícitamente (Bubblewrap es incompatible con la capa de compatibilidad del kernel de WSL1).⁸² - Revisión Guardian + hooks (v0.121.0): los hooks están deshabilitados durante las sesiones de revisión Guardian para que los hooks previos/posteriores a herramientas no interfieran con las decisiones del subagent Guardian.⁸² Si dependes de hooks para logging o validación, ten en cuenta que una revisión Guardian los omite; recurre a la observabilidad del servidor de la aplicación si necesitas una pista de auditoría completa. - Sistema de archivos /dev en Linux (v0.105.0): los comandos con sandbox en Linux ahora reciben un sistema de archivos /dev mínimo, lo que mejora la compatibilidad con herramientas que esperan nodos de dispositivo.⁶¹

Política ReadOnlyAccess (v0.100.0+): una forma de política configurable para control granular de acceso de lectura. Úsala para restringir qué directorios puede leer Codex, incluso en 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 pausa para pedir confirmación humana:

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

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

Codex ahora asigna ID de aprobación distintos a cada comando dentro de una ejecución de shell de varios pasos. Esto significa que las aprobaciones son granulares: aprobar un comando en una secuencia no aprueba automáticamente los siguientes dentro de la misma invocación de shell.⁴⁹

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

El flujo de aprobación ahora admite permisos de sandbox adicionales y rechazo granular:⁶¹

• Permisos de sandbox adicionales: cuando un comando necesita acceso más allá del modo de sandbox actual, Codex puede solicitar permisos adicionales específicos en lugar de requerir un cambio completo de modo
• Rechazo granular: rechaza llamadas individuales a herramientas con comentarios para que Codex pueda ajustar su enfoque en vez de simplemente volver a intentar el mismo comando

Solicitudes de permisos en runtime (v0.113.0+)

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

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

Los perfiles de permisos dividen las políticas de sandbox del sistema de archivos y la red en secciones con nombre y reutilizables. Define default_permissions con un perfil integrado como :read-only, :workspace, o apúntalo a una tabla personalizada [permissions.<name>].⁸⁷ v0.133.0 promueve los perfiles como una superficie administrada: los APIs de lista exponen metadatos de perfiles disponibles, los perfiles pueden heredar unos de otros, requirements.toml administrado puede declarar requisitos de permisos, los perfiles activos se actualizan en runtime, y la configuración del sandbox de Windows ahora consume el perfil resuelto en lugar de una política ad hoc separada.⁹⁸

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 sensibles y globs que deberían ser ilegibles incluso cuando la raíz del proyecto sea escribible. Para excepciones puntuales de comandos, prefiere reglas antes que ampliar un perfil de forma general.⁸⁷

Guía heredada de --full-auto

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

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 lista para ejecuciones interactivas. Usa los flags explícitos anteriores o un perfil de permisos con nombre.⁸⁶

Confiabilidad del sandbox (v0.129.0): el refuerzo del inicio del sandbox en Linux reduce condiciones de carrera en sistemas de archivos lentos o checkouts con symlinks; las mejoras de confiabilidad del sandbox en Windows corrigen varios crashes de casos límite durante ejecuciones largas; y Bubblewrap vendorizado se actualiza a 0.11.2 con parches de seguridad upstream. No se requieren cambios de configuración. Ejecuta codex update para obtener estas mejoras.⁸⁹

Configuraciones recomendadas

Desarrollo diario (valor predeterminado seguro):

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 combinación es el “punto ideal” recomendado por la comunidad: capacidad máxima, pero con aprobación requerida para cada comando.⁸

Automatización CI/CD:

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

Aprobaciones inteligentes con subagent Guardian (v0.115.0+)

Smart Approvals puede enrutar solicitudes de revisión mediante un subagent guardian en lugar de requerir aprobación humana para cada acción. La sesión del guardian persiste entre aprobaciones para reutilizar la caché del prompt y evitar la sobrecarga de inicio. Cada revisión obtiene un historial limpio (las decisiones previas no se filtran a revisiones posteriores).⁷³

Configura el revisor en config.toml:

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

Esto es especialmente útil para flujos de trabajo CI/CD donde quieres revisión automatizada con razonamiento, en lugar de un approval_policy = "never" generalizado.

Habilitar acceso de red

Codex bloquea el acceso de red de forma predeterminada en 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 enrutan el tráfico de WebSocket mediante un proxy, Codex ahora admite las variables de entorno WS_PROXY y WSS_PROXY:⁴⁹

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

Estas complementan la compatibilidad existente con HTTPS_PROXY y proxy SOCKS5 (v0.93.0+), cubriendo todas las capas de transporte.

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 workspace. Si alguno de los comandos tiene éxito, tu configuración de sandbox necesita investigación.

¿Cómo funciona AGENTS.md?

AGENTS.md es el sistema de instrucciones de proyecto de Codex: un estándar abierto⁹ que ahora gobierna la Agentic AI Foundation de Linux Foundation. Cuenta con soporte de 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 ver paquetes reutilizables de experiencia que complementan AGENTS.md.

Jerarquía de descubrimiento

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

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

Qué hace excelente a un AGENTS.md

Según la orientación directa del propio Codex y patrones de la comunidad¹⁰:

HAZ ESTO: - Sé específico: "Use rg --files for discovery" es mejor que "search efficiently" - Define el cierre: ¿qué significa “terminado”? (tests aprobados, lint limpio, etc.) - Incluye comandos: compilación, tests, lint, formato (invocaciones exactas) - Organiza por tarea: secciones de desarrollo, revisión, release e incidentes/debug - Define la escalación: qué hacer cuando hay un bloqueo o aparece un estado inesperado

NO HAGAS ESTO: - Volcar guías de estilo completas sin reglas de ejecución - Usar directivas ambiguas (“ten cuidado”, “optimiza”) - Mezclar prioridades contradictorias (velocidad + verificación exhaustiva + sin presupuesto de runtime) - Escribir documentación explicativa (AGENTS.md es política operativa, no README)

Ejemplo: AGENTS.md de 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.

Manejo de secretos en sesiones de agente

Trata el historial visible para Codex como una superficie de seguridad, no solo como código fuente. Las release notes de Codex documentan el trabajo de capturas del shell y redacción de variables de entorno, y el sistema de memoria analiza las escrituras de memoria en busca de secretos, pero esas protecciones no convierten la salida de comandos, transcripciones de sesión, capturas del shell, logs locales ni scripts auxiliares en lugares seguros para imprimir credenciales.³⁷⁵⁵⁹⁵

La regla operativa es simple: no imprimas secretos para que el modelo los inspeccione; mantén las credenciales auxiliares en configuración requerida por el entorno; separa el código fuente ejecutable, la documentación, las cachés generadas, las transcripciones de sesión, las capturas del shell, los logs y los almacenes intencionales de secretos durante las auditorías; redacta el historial local cuando aparezca una forma de secreto de alta confianza; y promueve hooks de prevención solo después de que el ciclo manual de higiene esté probado. La lección pública es el mapa de superficie y los criterios de aceptación, no valores privados de tokens, rutas exactas ni detalles internos del detector.⁹⁵

El mecanismo de override

AGENTS.override.md en cualquier nivel de directorio reemplaza el AGENTS.md normal para ese ámbito. Úsalo para:

• Congelamientos de release: “Sin funciones nuevas, solo correcciones”
• Modo incidente: “Todos los cambios deben ser revisados por la persona on-call”
• Endurecimiento temporal: “Sin actualizaciones de dependencias en 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 scaffold

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

O verifica tu cadena de instrucciones:

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

Hooks

Codex introdujo hooks en v0.99.0 (AfterAgent) y v0.100.0 (AfterToolUse), y luego agregó un motor experimental de hooks en v0.114.0 con eventos SessionStart y Stop.⁷⁰ Desde v0.124.0 (23 de abril de 2026), los hooks son estables.⁸⁵ Ahora se pueden configurar inline en config.toml y requirements.toml — ya no se requiere un archivo separado de scripts de hooks — y observan herramientas MCP junto con apply_patch y sesiones de Bash de larga duración. El sistema ahora cubre el ciclo de vida de la sesión y la automatización a nivel de herramienta, cerrando la brecha con el 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)'"

El stdout del hook SessionStart alimenta el contexto del modelo, por lo que es ideal para inyectar información dinámica (fechas, nombres de ramas, variables de entorno) al inicio de la sesión.

Replicar patrones de hooks de Claude Code

Si estás migrando desde Claude Code, así puedes lograr una automatización similar:

Consejo experto: Desde v0.124.0 (23 de abril de 2026), el motor de hooks es estable. Los nuevos eventos de hooks siguen llegando en releases: revisa el changelog de Codex.

Explorador de hooks en la TUI (v0.129.0): Ejecuta /hooks en la TUI para descubrir los hooks disponibles, ver cuáles están activos actualmente y activar o desactivar hooks individuales sin editar config.toml. Útil para diagnosticar un hook incluido en un plugin que se comporta mal o para desactivar temporalmente un linter AfterToolUse durante una sesión de edición enfocada.⁸⁹

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

Configurar 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

Gestió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

En 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; es útil cuando un servidor no se carga o las herramientas no aparecen donde esperabas. /mcp simple se mantiene rápido.

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

Ejecutar Codex COMO un servidor MCP

Codex puede exponerse a sí mismo como un servidor MCP para orquestación multiagente:¹²

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 prompt

Uso con Agents SDK (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 consciente del contexto — Combina Context7 con la documentación de tu framework para que Codex siempre tenga referencias API actuales:

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

Patrón 2: Límites de salida — Las respuestas de herramientas MCP se truncan de forma predeterminada en ~25 K caracteres. Para herramientas que devuelven cargas útiles grandes (consultas de bases de datos, capturas de logs), 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, renders de gráficos— los pasen directamente al modelo para su análisis.⁶²

Patrón 3: Gobernanza empresarial de MCP — Restringe qué servidores 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 inicio. Consulta Implementación empresarial para ver la configuración completa de políticas.

Code Mode [EXPERIMENTAL]

Code mode (v0.114.0) ofrece flujos de trabajo de codificación más aislados al restringir el alcance del agente a operaciones centradas en código.⁷⁰ Cuando está habilitado, el agente se enfoca en leer, escribir y probar código sin interacciones más amplias con el sistema.

A partir de v0.139.0, code mode puede llamar directamente a búsqueda web independiente, incluso desde llamadas de herramientas JavaScript anidadas, y recibe resultados en texto plano, por lo que un flujo en code mode puede obtener información en vivo sin salir del contexto de codificación aislado por sandbox.¹⁰³

Esta función es experimental. Revisa las notas de la versión para ver actualizaciones.

Runtime REPL de JavaScript [REMOVED]

Codex v0.100.0 agregó un runtime REPL experimental de JavaScript (js_repl) y v0.106.0 lo promovió a través de la superficie /experimental.⁶⁰ Esa orientación ahora es histórica. En v0.128.0, el changelog 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 versionados, herramientas MCP o una skill de Codex con un directorio scripts/ cuando necesites lógica ejecutable repetible.

¿Qué son los Skills?

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

Estructura de un 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 descubrimiento

Codex almacena los skills instalados por el usuario en $CODEX_HOME/skills (predeterminado: ~/.codex/skills), incluidos los skills de sistema integrados bajo .system/. Codex admite carpetas de skills enlazadas mediante symlink.

Crear un 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)

Metadata (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ícito: menú /skills o mención $skill-name en el prompt
• Implícito: Codex detecta automáticamente skills coincidentes a partir de la descripción de la tarea (si allow_implicit_invocation: true)
• Creador: Usa $skill-creator para crear un skill nuevo de forma interactiva
• Instalador: Usa $skill-installer install <name> para instalar skills de la comunidad

Activar/desactivar

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

Skills vs Slash Commands

Depurar Skills

Si un skill no se activa:

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

Ejemplo de producción: Deploy Skill

Un skill completo de varios archivos que muestra referencias y scripts funcionando juntos:

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ócalo con: $deploy to staging o $deploy production with canary rollout

Plugins

Plugins unifica skills, entradas MCP, hooks y conectores de apps en un solo paquete instalable (v0.110.0+).⁶⁵ A partir de v0.117.0, plugins son ciudadanos de primera clase: los plugins con alcance de producto se sincronizan automáticamente al iniciar y /plugins ofrece un navegador dentro de la TUI para descubrimiento y gestión.⁷⁵ v0.128.0 amplió los flujos de trabajo de plugins con instalación desde marketplace, almacenamiento en caché de bundles 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) agrega uso compartido de workspace para plugins (envía un conjunto de plugins a compañeros de equipo sin volver a publicarlo), controles de acceso compartido (habilitar/deshabilitar por destinatario, revocar), filtrado de fuentes (limita de qué marketplaces obtiene contenido un workspace) y operaciones de marketplace que pueden invocarse directamente desde el navegador /plugins en lugar de CLI.⁸⁹ v0.133.0 (21 de mayo de 2026) facilita auditar el descubrimiento de plugins: la salida de lista reconoce marketplaces, las versiones instaladas son visibles, se listan las raíces de marketplace y las colecciones remotas de plugins pueden mostrarse sin adivinar de qué registro provino un resultado.⁹⁸ v0.130.0 (8 de mayo de 2026) hace que el empaquetado de plugins sea más transparente y que el flujo de uso compartido sea más controlable:⁹¹

• Hooks incluidos visibles en los detalles del plugin. La vista de detalle de /plugins ahora lista 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 sorpresa de hooks provenientes de un plugin en el que confías solo por sus herramientas.
• Metadatos de uso compartido de plugins en shareContext. Cuando un plugin se comparte desde un workspace, la carga útil del enlace compartido ahora expone metadatos del enlace (creador, alcance, vigencia) para que las sesiones receptoras puedan mostrar la procedencia y decidir si aceptarlo.
• Controles de detectabilidad en la configuración de uso compartido. La configuración de uso compartido expone un interruptor de detectabilidad para que los equipos puedan publicar plugins en workspaces específicos o listas de destinatarios sin hacerlos listables de forma general en toda una organización.

Fuentes de plugins

Descubrimiento de plugins

Codex le indica al modelo qué plugins están habilitados al inicio de 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 alcance de producto se sincronizan al iniciar, lo que garantiza que el catálogo de plugins más reciente esté disponible sin intervención manual.⁷⁵

Menciones @plugin (v0.112.0+)

Referencia 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.

Plugin Marketplace (v0.113.0+)

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

Agregar marketplaces de terceros (v0.121.0+)

La documentación actual de OpenAI Codex mantiene la gestión de fuentes de marketplace bajo codex plugin marketplace. Esto formaliza la distribución de plugins de terceros más allá del marketplace propio de OpenAI y admite abreviaturas de repos GitHub, URLs Git HTTP(S), URLs SSH y directorios raíz de marketplace locales; usa --ref para fijar una referencia de Git y repite --sparse PATH solo para repos de marketplace 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 [email protected]: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 navegador /plugins junto con los predeterminados. Los llamadores del servidor de app (integraciones de IDE/escritorio) tienen un endpoint paralelo para registrar marketplaces de forma programática.⁸²

Consideración de seguridad: Los marketplaces de terceros ejecutan código arbitrario de plugins con tus permisos de Codex. Revisa las fuentes antes de agregarlas y prefiere la ejecución en sandbox durante los primeros usos.

Gestionar 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 experto: Plugins consolida lo que antes requería configuración separada de MCP, instalación de skills y configuración de conectores de apps. Un solo plugin puede incluir los tres, lo que acelera la incorporación del equipo y hace que la configuración sea más portable.

Plan Mode y colaboración

Plan mode permite que Codex diseñe un enfoque antes de ejecutar cambios. Está habilitado de forma predeterminada (desde v0.94.0).¹⁴ Consulta Marcos de decisión para el árbol de decisión “Plan Mode vs Direct Execution”.

Entrar en Plan Mode

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

En plan mode, Codex: - Lee archivos y analiza el codebase - Propone un plan de implementación - No realiza cambios hasta que lo apruebes - Transmite el plan en una vista dedicada de la TUI

Steer Mode

Steer mode (habilitado de forma predeterminada desde v0.98.0) te permite insertar nuevas instrucciones mientras Codex está trabajando activamente, sin interrumpir su tarea actual.¹⁴

Hay dos métodos de inserción:

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

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

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

Resaltado de sintaxis (v0.105.0): La TUI ahora resalta la sintaxis de bloques de código delimitados y diffs en línea. 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 transcripción de voz. Esta función es experimental y puede requerir permisos de micrófono.⁶¹ A partir de v0.107.0, las sesiones de voz en tiempo real admiten la selección de dispositivos de micrófono y altavoz, lo que te permite elegir hardware específico de entrada/salida de audio.⁶² Eliminado en v0.140.0: los controles de voz experimentales /realtime y sus dependencias de audio se quitaron de la TUI; la transcripción de voz con barra espaciadora no se ve afectada.¹⁰²

Otras mejoras: - Los enlaces largos ahora siguen siendo clicables incluso cuando se ajustan en varias líneas de la TUI (v0.105.0)⁶¹ - Los enlaces a archivos locales se renderizan con formato mejorado (v0.106.0)⁶⁰ - El markdown de la TUI mantiene los enlaces web clicables mediante metadatos OSC 8, y las tablas estrechas recurren a registros legibles de clave/valor sin perder los destinos de los enlaces (v0.136.0)¹⁰⁶ - Se corrigió el manejo de Ctrl+C para subagentes para terminar correctamente los procesos hijos (v0.106.0)⁶⁰

Sistema de memoria

Codex tiene 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 usa para orientar su comportamiento en todas las sesiones futuras.

Qué almacenar

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

• Convenciones del proyecto: “This project uses tabs, not spaces” 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 workflow: “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 se benefician del mismo contexto que las sesiones interactivas, sin necesidad de repetir instrucciones en cada invocación.

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

• Saneamiento de secretos: Las memorias se escanean automáticamente en busca de secretos antes de escribirse en el disco
• Conciencia del CWD: Los archivos de memoria ahora incluyen el contexto del directorio de trabajo para una recuperación específica del proyecto
• Exclusión de mensajes de desarrollador: Los mensajes de desarrollador/sistema se excluyen de la entrada de memoria de fase 1, lo que mejora la calidad de la memoria al enfocarse en las interacciones del usuario
• Olvido basado en diff (v0.106.0): La memoria ahora usa olvido basado en diff para eliminar datos obsoletos, manteniendo el almacén de memoria ligero y relevante con el tiempo⁶⁰
• Selección consciente del uso (v0.106.0): La recuperación de memoria ahora tiene en cuenta el uso, priorizando memorias consultadas con frecuencia y recientemente relevantes⁶⁰
• Memorias configurables (v0.107.0): Las memorias ahora son completamente configurables. Usa codex debug clear-memories para restablecer todas las memorias almacenadas y empezar desde cero; es útil cuando cambias de contexto entre proyectos no relacionados o cuando el estado de la memoria se ha desviado⁶²
• Actualización del modelo de fase 2 (v0.121.0): El modelo de consolidación de memoria de fase 2 ahora es gpt-5.4 (en lugar del valor predeterminado anterior). El pipeline de fase 2 se ejecuta entre sesiones para destilar transcripciones de fase 1 en datos duraderos; el cambio de modelo mejora la calidad de recuperación con el mismo costo de tokens.⁸²
• Menú de memorias en TUI (v0.121.0): Una nueva UI dentro de la sesión expone el modo de memoria, la eliminación de memorias individuales y un botón de restablecimiento. El restablecimiento de memoria ahora preserva rollouts anteriores en lugar de invalidarlos, de modo que restablecer limpia la superficie de recuperación futura sin romper la reproducción de sesiones.⁸²

Memoria vs AGENTS.md

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

Gestión de sesiones

Codex persiste las sesiones en ~/.codex/sessions/, lo que permite reanudar, bifurcar y manejar workflows de varios hilos entre CLI y las superficies de escritorio.

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.

Bifurcar

Ramifica 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. Los cambios en una bifurcación no afectan a la otra. Esto es útil para comparar enfoques (por ejemplo, “bifurca y prueba Redis en lugar de Memcached”) o explorar cambios riesgosos de forma segura.

Bifurcación de hilos en sub-agents (v0.107.0): Los hilos ahora 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 depurable.⁷⁵

Lista de hilos

Ve y gestiona sesiones activas:

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

En la desktop app, los hilos son visibles en la barra lateral con historial completo y vistas previas de diff.

Ciclo de vida de la sesión

Las sesiones se sincronizan entre CLI y la desktop app: empieza en una y continúa en la otra.

Modo no interactivo (codex exec)

codex exec ejecuta Codex de forma no interactiva para scripting, 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. El diseño permite componerlo con pipelines Unix estándar.

Archivado de sesiones (v0.136.0)

Las sesiones se pueden archivar para mantener enfocada la lista de reanudación/fork sin eliminar el historial. Archiva 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 de reanudación o fork hasta que la desarchives: una medida de seguridad para evitar que continúes por accidente una sesión que querías retirar. En la misma versión: codex app-server --stdio inicia el app-server en modo stdio para integraciones con editores/hosts, y ahora /diff tiene bloqueada la ejecución de helpers Git proporcionados por el repositorio (una corrección de seguridad de comandos). En Windows, una ruta de aprovisionamiento alpha agrega codex sandbox setup --elevated para administradores.¹⁰⁶

Salida de líneas JSON

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

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

Tipos de evento: 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 forma de la respuesta con JSON Schema:

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

Flags clave

Autenticación en CI

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

Banner de inicio de codex exec (v0.130.0). El banner de inicio de codex exec ya no imprime el texto heredado “research preview”. Si tu CI extrae información de la salida de inicio, el texto del banner ahora es más breve; los eventos estructurados de --json no cambian.⁹¹

codex remote-control (v0.130.0+)

codex remote-control es un comando de nivel superior que inicia un app-server headless pensado para ser controlado por otro proceso: extensiones de IDE, orquestadores personalizados o planos de control remotos. Reemplaza la invocación de codex app-server con múltiples flags que muchos integradores estaban armando a mano, y le da a las herramientas de terceros un único punto de entrada estable al mismo runtime de app-server que se distribuye bajo las superficies de escritorio e IDE.⁹¹ v0.133.0 mejora la forma de ejecución del comando: puede ejecutarse como un comando en primer plano, esperar a estar listo, informar el estado de la máquina y seguir exponiendo comandos explícitos de estilo daemon start / stop para configuraciones de controladores de larga duración.⁹⁸

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

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

Combina codex remote-control con los APIs de paginación del app-server a continuación cuando estés creando UIs que necesitan enumerar historiales extensos de threads sin cargar todos los turns en memoria de una sola vez.

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

Los clientes del app-server ahora pueden paginar threads grandes mediante 3 vistas distintas de elementos de turn:⁹¹

Combina la paginación con la interfaz ThreadStore introducida en v0.121.0 para recorrer threads de larga duración de forma eficiente, especialmente en despliegues de remote-control donde el orquestador puede estar en una máquina distinta a la de los archivos de rollout.⁸²

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

Los threads activos del app-server ahora incorporan cambios de config.toml sin requerir reinicio: edita la configuración, guarda y el thread en ejecución refleja los nuevos valores en su siguiente turn. Esta es la corrección de bug que complementa a codex remote-control: un servidor headless de larga duración puede reconfigurarse en el lugar en vez de desmontarse.⁹¹

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 pipeline de CI.

Cómo funciona

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

Acceso a Internet en Cloud

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

• Off: Sin acceso del agente a Internet (predeterminado)
• On: Allowlist opcional de dominios + restricciones de métodos HTTP

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

Los scripts de configuración aún pueden usar 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 thread de Slack para iniciar una tarea en la nube.

Requisitos previos: 1. Plan de ChatGPT elegible (Plus, Pro, Business, Enterprise o Edu) 2. Cuenta de GitHub conectada 3. Al menos un entorno en la nube configurado 4. App de Slack instalada para tu workspace

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

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 Codex Desktop App

La Codex desktop app (macOS y Windows) ofrece una interfaz gráfica optimizada para gestionar varios proyectos.¹⁶ La versión para Windows se lanzó el 4 de marzo de 2026 con soporte nativo para PowerShell y sandbox nativo de Windows.⁶⁶

Instalación

codex app                      # Auto-downloads and installs on first run

O descarga directamente: Codex.dmg (macOS) | Disponible en Microsoft Store (Windows)

Funciones principales

Appshots, comentarios del navegador y Computer Use

Las actualizaciones de la app del 21 de mayo convierten la desktop app en una superficie de contexto más sólida, no solo en un gestor de hilos. Usa Appshots cuando Codex necesite conocer el estado de otra app de Mac antes de actuar: Codex captura la ventana en primer plano, el texto visible y fuera de pantalla disponible que expone la app, y almacena el adjunto localmente en el historial de la sesión.⁹⁹

Para trabajo web y frontend, usa primero el navegador integrado cuando la página no requiera autenticación: les da a Codex y a ti una previsualización renderizada compartida, admite acciones de uso del navegador como clics, capturas de pantalla, descargas de recursos e inspección JavaScript de solo lectura, y te permite marcar regiones de la página con comentarios que Codex puede abordar en el siguiente turno.⁹⁹ Para sitios con sesión iniciada, sigue usando la extensión de Chrome.

Usa Computer Use solo cuando una integración estructurada o una previsualización del navegador no pueda verificar la tarea. Puede inspeccionar y operar apps de Mac permitidas, pero hereda las aprobaciones y reglas de sandbox de Codex para ediciones de archivos y comandos de shell, y el uso bloqueado se mantiene acotado: Codex puede acceder temporalmente a apps permitidas durante turnos activos y confiables de Computer Use después de que la Mac se bloquea, con protecciones de rebloqueo y detección de entrada local.⁹⁹

Modos de hilo

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

Mecánica de aislamiento de Worktree:

Cuando inicias un hilo Worktree, la desktop app: 1. Crea un nuevo git worktree (git worktree add) en un directorio temporal 2. Hace checkout de una rama nueva desde tu HEAD actual 3. Ejecuta el agente dentro del worktree: todos los cambios de archivos quedan aislados 4. Presenta una revisión de diff al finalizar: tú eliges qué cambios fusionar de vuelta

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

Automatizaciones

Las automatizaciones se ejecutan localmente en la app, así que la app debe estar abierta y el proyecto disponible en disco:

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

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

Ejemplos de uso: - Clasificación de issues: Categoriza y prioriza automáticamente nuevos issues - Monitoreo de CI: Observa fallas de build y sugiere correcciones - Respuesta a alertas: Reacciona a alertas de monitoreo con análisis diagnóstico - Actualizaciones de dependencias: Busca y aplica parches de seguridad

Los resultados aparecen en una cola de revisión para aprobación humana.

Soporte para Windows

La Codex Desktop App se lanzó en Windows el 4 de marzo de 2026 (App v26.304) con soporte nativo para PowerShell, sandbox nativo de Windows y paridad completa de funciones, incluidas skills, automatizaciones y worktrees sin requerir 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 respuesta final de Codex para pasos/jobs posteriores.

Estrategias de seguridad

Controles de acceso

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

Predeterminado: Solo los colaboradores con acceso de escritura pueden activar workflows de Codex.

Codex SDK

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

Instalación

npm install @openai/codex-sdk

Uso básico

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

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

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

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

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

Funciones avanzadas de SDK

• runStreamed(...): Flujo de eventos asíncrono para actualizaciones intermedias
• Auth de SDK de Python (v0.132.0+): El inicio de sesión con clave API, los flujos de ChatGPT en navegador/código de dispositivo, la inspección de cuentas y el cierre de sesión son rutas de SDK de primera clase.⁹⁷
• Comodidad de turnos solo de texto (v0.132.0+): Las APIs de turno de Python aceptan cadenas simples y devuelven metadatos TurnResult más completos con elementos recopilados, tiempos y uso.⁹⁷
• outputSchema: Aplica una salida final con forma 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 sobrevive al reanudar la sesión⁷⁵
• view_image multi-entorno (v0.130.0): Para sesiones que abarcan varios entornos (introducido en v0.124.0 con selección de entorno + directorio de trabajo por turno, y refinado en v0.125.0 con entornos persistentes), view_image ahora resuelve rutas de archivo a través del 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 el SDK.⁹¹

Configuración de hilos y clientes

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

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

Las sesiones persisten en ~/.codex/sessions.

Runtime: Node.js 18+.

Optimización del rendimiento

Gestión del contexto

Las ventanas de contexto varían según el modelo. A abril de 2026: GPT-5.5 en Codex ofrece 400K (1M en la API). GPT-5.4 / GPT-5.4-mini ofrecen 1M / 400K respectivamente (equivalente a API en Codex). La familia GPT-5.3-Codex / GPT-5.2-Codex funciona con 272K de entrada + 128K de salida (presupuesto total de 400K). Todas se llenan más rápido de lo que esperarías; gestiónalas de forma proactiva:

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

Eficiencia de tokens

Optimización de velocidad

1. gpt-5.3-codex-spark: Variante de menor latencia para trabajo interactivo en pareja
2. --profile fast: Modelo mini preconfigurado con razonamiento bajo
3. Ejecución paralela de herramientas: Codex ejecuta lecturas/comprobaciones independientes en paralelo, así que estructura los prompts para permitirlo
4. Bucles orientados a resultados: Pide “implementa, prueba, corrige, detente cuando esté en verde” en lugar de dar instrucciones paso a paso

¿Cómo depuro problemas?

Problemas comunes y soluciones

Referencia de mensajes de error

Herramientas de diagnóstico

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 dentro de 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

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 issues en github.com/openai/codex/issues.¹

Codex Security [PREVIEW]

Codex Security entró en research preview el 6 de marzo de 2026, incorporando revisión de seguridad de aplicaciones consciente del contexto al stack de Codex.⁷⁷ Está disponible para clientes de ChatGPT Pro, Enterprise, Business y Edu mediante Codex web.

Cómo funciona: Codex Security analiza repositorios para construir un modelo de amenazas específico del proyecto, identifica vulnerabilidades clasificadas por impacto en el mundo real y somete los hallazgos a pruebas de presión en un entorno sandbox para validarlos. El agente presenta hallazgos de mayor confianza con correcciones, lo que reduce el ruido de bugs insignificantes.

Rendimiento: Durante el research preview, Codex Security escaneó 1,2 millones de commits e identificó 10.561 vulnerabilidades de alta severidad. La precisión mejoró con el tiempo: redujo el ruido en un 84%, disminuyó la severidad sobreinformada en más del 90% y redujo a la mitad las tasas de falsos positivos. 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 en CLI. El sandbox protege tu máquina de Codex; Codex Security protege tu codebase de vulnerabilidades.

Implementación Enterprise

Controles de administración (requirements.toml)

Los administradores aplican la política empresarial mediante requirements.toml, un archivo de configuración impuesto por administración que limita la configuración sensible de seguridad que los usuarios no pueden sobrescribir:²¹

# /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 estricta que limita los valores que los usuarios pueden seleccionar, y los usuarios no pueden sobrescribirla. Las reglas de requisitos de administración solo pueden solicitar confirmación o prohibir (nunca permitir de forma silenciosa).

Configuración MDM para macOS

Distribúyelo mediante MDM usando el dominio de preferencias com.openai.codex.²¹ Codex respeta las cargas útiles estándar de macOS MDM (Jamf Pro, Fleet, Kandji, etc.). Codifica TOML como base64 sin saltos de línea:

Precedencia (de mayor a menor):

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

Los requisitos en la nube solo completan campos de requisitos no definidos, por lo que las capas administradas con mayor precedencia siempre prevalecen. Los requisitos en la nube funcionan con el mejor esfuerzo posible; si la obtención falla o agota el tiempo de espera, Codex continúa sin la capa en la nube.

Integración con OpenTelemetry

Codex admite la propagación del contexto de trazas de OpenTelemetry desde variables de entorno OTel estándar hasta las llamadas de OpenAI API. Define 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 traza se propaga a través de Codex hasta las llamadas API, lo que permite observabilidad de extremo a extremo
• Usa atributos de recursos para etiquetar trazas por equipo, entorno o proyecto
• Ten presentes los requisitos de privacidad al habilitar el registro de prompts/herramientas: las trazas pueden contener fragmentos de código
• Metadatos de traza OpenTelemetry configurables (v0.130.0+). Más allá del contenedor estándar OTEL_RESOURCE_ATTRIBUTES, el crate codex-otel ahora expone metadatos de traza 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/feedback incluidos en la misma versión para depuración y triaje unificados entre sesiones de CLI, app-server y remote-control.⁹¹

Acceso Enterprise

• ChatGPT Business / Enterprise / Edu: acceso controlado por administradores de la organización, con requisitos obtenidos desde la nube aplicados 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 Type II y SOC 3; BAA de HIPAA disponible para el nivel Enterprise
• Codex SDK: intégralo en herramientas y flujos de trabajo internos
• Aplicación de políticas a escala: usa requirements_toml_base64 distribuido por MDM o /etc/codex/requirements.toml a nivel del sistema de archivos

Manejo de datos y cumplimiento: - Las entradas/salidas de API no se usan para entrenamiento según los términos Business/Enterprise/API de OpenAI - Para residencia de datos, el tráfico de OpenAI API se enruta de forma predeterminada por 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 API salen de la máquina - ChatGPT Enterprise admite marcos de cumplimiento, incluidos SOC 2, GDPR y CCPA

Estrategia de despliegue

Despliegue por fases recomendado para organizaciones:

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

Patrones de auditoría

Rastrea el uso de Codex y aplica el cumplimiento:

• Trazas de OpenTelemetry: monitorea el volumen de llamadas API, el uso de tokens y la latencia por equipo
• Persistencia de sesiones: audita ~/.codex/sessions/ para revisión de cumplimiento (desactívala con --ephemeral en contextos sensibles)
• Aplicación de identidad 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 diffs de PR

Mejores prácticas y anti-patrones

Patrones de prompting

1. Prompts guiados por restricciones: Empieza 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 producen mejores correcciones de bugs que las descripciones vagas
3. Solicitudes de verificación: Termina con “Run lint + the smallest relevant test suite. Report commands and results.”
4. Referencias de archivos: Usa @filename para adjuntar archivos específicos al contexto
5. Bucles orientados al resultado: “Implementa, ejecuta las pruebas, corrige las fallas y detente solo cuando todas las pruebas pasen.” Codex itera hasta terminar

Filosofía de pruebas

La comunidad converge en una colaboración con AI guiada por pruebas:²²

• Define las pruebas desde el inicio como señales de finalización
• Deja que Codex itere hasta que las pruebas pasen (red → green → refactor)
• Adopta patrones de programación Tiger Style
• Proporciona el texto exacto del archivo cuando solicites parches. Codex usa coincidencias estrictas, no parches difusos basados en AST

Mejores prácticas de gestión de 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 vs CRLF) en los archivos versionados para evitar fallas en los parches
• Mantén AGENTS.md conciso, ya que las instrucciones largas se desplazan fuera del contexto

Flujo de trabajo con Git

• Crea siempre una rama nueva antes de ejecutar Codex en repositorios que no conoces
• Usa flujos basados en parches (git diff / git apply) en lugar de ediciones directas
• Revisa las sugerencias de Codex como revisarías PRs de código
• Usa /diff para verificar los cambios antes de hacer commit

Skills y prompts de la comunidad

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

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

Skills de la comunidad: - claude-skill: Transfiere tareas a Claude Code con modos de permisos - autonomous-skill: Automatización de tareas en varias sesiones con seguimiento de progreso - deep-research: Orquestación de subtareas en paralelo - kiro-skill: Requisitos → diseño → tareas → pipeline de ejecución

Anti-patrones

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

Anti-patrones de costo

Anti-patrones de contexto

Anti-patrones de flujo de trabajo

Anti-patrones de prompts

Recetas de flujo de trabajo

Patrones de extremo a extremo 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 de desarrollo diario

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

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

Revisa con /diff y luego haz commit.

Receta 3: Refactorización compleja con Plan Mode

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. Aprueba o guía:

[Tab] Also add a migration script using Alembic

Después de que Codex ejecute, verifica:

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

Receta 4: Revisión de PR con codex exec

codex exec --model gpt-5.1-codex-mini \
  "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."

Revisa 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 funciona a nivel del sistema operativo: Codex usa Seatbelt/Landlock, no contenedores. Las restricciones operan a nivel del kernel, por debajo de la capa de la aplicación.
• Los hooks se están expandiendo: Codex ahora admite 5 eventos de hooks: SessionStart, Stop y UserPromptSubmit (v0.114.0–v0.116.0, experimental), 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 todavía ofrecen una cobertura más amplia. Para patrones de automatización que aún no estén cubiertos, usa instrucciones en AGENTS.md o skills.
• Sub-agents v2 (v0.117.0): Los sub-agents 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 concurrentes, reducido desde 12 en v0.91.0). Los roles multiagente siguen siendo personalizables mediante la configuración (v0.104.0+).⁴⁷ v0.105.0 agregó spawn_agents_on_csv para distribuir trabajo entre filas con seguimiento de progreso y ETA.⁶¹ Codex todavía no tiene la UX explícita de herramienta Task de Claude Code para delegación dirigida por el usuario; usa tareas en la nube u orquestación con SDK para patrones de delegación.
• AGENTS.md es compatible entre herramientas: Tu AGENTS.md funciona en Cursor, Copilot, Amp, Jules, Gemini CLI y más de 60.000 proyectos open source. CLAUDE.md es solo para Claude.
• Los perfiles reemplazan el cambio manual: En lugar de cambiar flags en cada ejecución, define perfiles en config.toml.

Desde GitHub Copilot

Lo que ganas: - Sandbox a nivel del sistema operativo (Seatbelt/Landlock, aplicado por el kernel en lugar de basado en contenedores) - Delegación de tareas en la nube con codex apply - Perfiles de configuración para cambiar de flujo de trabajo - App de escritorio con aislamiento de 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 (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Registro de cambios

Referencias

Nota sobre URL del blog de OpenAI: Las referencias ¹⁶, ²⁵-³⁰, ³³, ⁶⁴, ⁶⁶, ⁶⁷, ⁷⁶ y ⁷⁷ enlazan a publicaciones de blog en openai.com/index/ que devuelven HTTP 403 al acceso automatizado debido a la protección contra bots de Cloudflare. Estas URL son válidas cuando se accede a ellas desde un navegador web estándar.