Codex CLI: La referencia técnica definitiva

En resumen: Codex es un agente de programación multisuperficie que lee tu código fuente, ejecuta comandos en un sandbox a nivel de sistema operativo, modifica archivos y delega tareas a la nube. Domina cinco sistemas fundamentales (config.toml, el modelo de sandbox/aprobación, AGENTS.md, MCP y skills) y Codex se convierte en un multiplicador de fuerza. Usa perfiles para cambiar de contexto, /compact para gestionar el presupuesto de contexto, y AGENTS.md para instrucciones de proyecto compatibles con Codex, Cursor, Amp y más. GPT-5.4 es ahora el modelo recomendado con ventanas de contexto de 1M.

Codex funciona como un agente de programación multisuperficie, no como un chatbot que escribe código. El CLI lee tu código fuente, ejecuta comandos en un sandbox, modifica 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 cuatro superficies distintas según tu forma de trabajar.

La diferencia entre un uso casual y uno efectivo de Codex se reduce a cinco sistemas fundamentales. 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: determina qué puede hacer Codex
3. AGENTS.md: define contratos operativos a nivel de proyecto
4. Protocolo MCP: extiende las capacidades hacia servicios externos
5. Sistema de skills: empaqueta experiencia de dominio reutilizable

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

Nota de estabilidad: las funciones marcadas como [EXPERIMENTAL] están sujetas a cambios entre versiones. Codex Cloud, el grupo de comandos MCP, code mode y hooks engine son experimentales a partir de la v0.117.0. El CLI principal, sandbox, AGENTS.md, config.toml, Skills y el sistema de plugins son estables.

Puntos Clave

• Cuatro superficies, un solo cerebro: CLI, la app de escritorio, la extensión para IDE y las tareas en la nube comparten la misma inteligencia GPT-5.x-Codex, así que elige la superficie que mejor se adapte a tu flujo de trabajo.
• Sandboxing a nivel de 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 es multi-herramienta: Tus instrucciones de proyecto funcionan en Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed y más de 60.000 proyectos de código abierto. Escríbelas una vez, úsalas en todas partes.
• Los perfiles eliminan 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.4 ofrece 1M de contexto; GPT-5.3-Codex proporciona 272K de entrada. En cualquier caso, 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 — comienza donde se ajuste a tu nivel de experiencia:

La Tarjeta de Referencia Rápida al final ofrece un resumen escaneable de todos los comandos principales.

Cómo Funciona Codex: El Modelo Mental

Antes de profundizar en las funciones, es importante entender cómo la arquitectura de Codex determina todo lo que haces con él. El sistema opera a través de 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-Codex impulsa todo. A partir de la v0.111.0, gpt-5.4 es el modelo recomendado — el modelo frontier insignia de OpenAI que combina las capacidades de codificación de GPT-5.3-Codex con razonamiento más sólido, uso nativo de computadora y ventanas de contexto de 1M.⁶⁶ Lee archivos, escribe parches, ejecuta comandos de shell y razona sobre tu base de código. Cuando el contexto se llena, Codex compacta la conversación para liberar espacio. Esta capa consume tokens.

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

Capa de Extensiones: MCP conecta servicios externos (GitHub, Figma, Sentry). Los Skills empaquetan 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. La app de escritorio para gestión de proyectos multihilo. La extensión de IDE para ciclos rápidos de edición-compilación-prueba. La nube para tareas asíncronas que se ejecutan de forma independiente.

La idea clave: La mayoría de los usuarios solo utilizan una superficie. Los usuarios avanzados usan las cuatro: la nube para tareas de larga duración, CLI para operaciones deterministas en el repositorio, la extensión de IDE para ciclos de codificación ajustados y la app de escritorio para planificación y coordinación.

Tabla de Contenidos

1. ¿Cómo Instalo Codex?
2. Inicio Rápido: Tu Primera Sesión
3. Superficies de Interacción Principales
4. Configuración del Sistema a Fondo
5. ¿Qué Modelo Debo Elegir?
6. ¿Cuánto Cuesta Codex?
7. Frameworks de Decisión
8. ¿Cómo Funciona el Sandbox y el Sistema de Aprobación?
9. ¿Cómo Funciona AGENTS.md?
10. Hooks
11. ¿Qué Es MCP (Model Context Protocol)?
12. Code Mode
13. JavaScript REPL Runtime
14. ¿Qué Son los Skills?
15. Plugins
16. Modo Plan y Colaboración
17. Sistema de Memoria
18. Gestión de Sesiones
19. Modo No Interactivo (codex exec)
20. Codex Cloud y Tareas en Segundo Plano
21. La App de Escritorio de Codex
22. GitHub Action y CI/CD
23. Codex SDK
24. Optimización de Rendimiento
25. ¿Cómo Depuro Problemas?
26. Despliegue 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. Registro de Cambios
32. Referencias

¿Cómo Instalo Codex?

Gestores de Paquetes

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

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 asset de release en GitHub:⁶²

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

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

Descargas de Binarios

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

Requisitos del Sistema

• macOS: Apple Silicon o Intel (soporte completo de sandbox vía Seatbelt)
• Linux: x86_64 o arm64 (sandbox vía Landlock + seccomp)
• Windows: Sandbox nativo con tokens restringidos (promovido de experimental en v0.100.0). También es compatible con WSL²

Autenticación

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

Dos rutas de autenticación:

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

Consejo experto: El almacenamiento de credenciales es configurable mediante cli_auth_credentials_store en config.toml. Opciones: file (por defecto), keyring (llavero del SO) o auto (keyring si está disponible, file como respaldo).

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 v0.104.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. Navega a un proyecto:

cd ~/my-project                  # Any git repo works

3. Inicia Codex:

codex

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

4. Haz una pregunta:

> What does this project do? Summarize the architecture.

Codex lee los archivos clave y explica la base de código. En el modo suggest predeterminado no se realizan cambios.

5. Realiza un cambio:

> Add input validation to the login endpoint

Codex propone ediciones como un diff. Revisa y aprueba con y, o rechaza con n.

6. Usa un slash command:

> /plan Refactor the database layer to use connection pooling

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

7. Verifica tu trabajo:

> /diff

Consulta todos los cambios que Codex ha realizado en la sesión actual.

¿Qué sigue? - Configura AGENTS.md con las instrucciones de tu proyecto (consulta ¿Cómo funciona AGENTS.md?) - Configura un perfil para tu flujo de trabajo (consulta Perfiles) - Prueba codex exec para automatización no interactiva (consulta Modo no interactivo)

Superficies de interacción principales

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

1. CLI interactiva (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

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

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

Atajos clave de la TUI:

Slash commands disponibles en la TUI:

2. Codex Desktop App (macOS + Windows)

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

La aplicación de escritorio agrega capacidades que la CLI no tiene:

• Multitarea: Ejecuta múltiples agentes en paralelo en diferentes proyectos simultáneamente
• Aislamiento con git worktree: Cada hilo trabaja sobre una copia aislada de tu repositorio
• Revisión de diffs en línea: Prepara, revierte y confirma cambios sin salir de la aplicación
• Terminal integrada: Terminal por hilo para ejecutar comandos
• Bifurcación de conversaciones: Ramifica conversaciones para explorar alternativas
• Ventanas emergentes flotantes: Separa conversaciones en ventanas portátiles
• Automatizaciones: Programa tareas recurrentes (triaje de issues, monitoreo de CI, respuesta a alertas)

¿Cuándo usar la app vs la CLI? Usa la aplicación de escritorio cuando estés coordinando múltiples flujos de trabajo o necesites revisión visual de diffs. Usa la CLI cuando quieras composabilidad en terminal, scripting o integración con CI/CD.

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

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

• Modo agente por defecto: Lee archivos, realiza ediciones, ejecuta comandos
• Ediciones en línea: Sugerencias contextuales en tus archivos activos
• Sesiones compartidas: Las sesiones se sincronizan entre la CLI y la extensión del IDE
• Misma autenticación: Inicia sesión con tu cuenta de ChatGPT o tu clave de API

Instálala desde el 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 gestionados por OpenAI:

• Lanza y olvida: Encola tareas que se ejecutan independientemente de tu computadora local
• Ejecución en paralelo: Ejecuta múltiples tareas en la nube simultáneamente
• Creación de PR: Codex crea pull requests a partir del trabajo completado
• Aplicación local: Descarga los resultados de la nube a tu repositorio local con codex apply <TASK_ID>

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

Las tareas en la nube también son accesibles desde chatgpt.com/codex.⁴

Análisis profundo del sistema de configuración

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

Precedencia (de mayor a menor)

1. Sobrecargas de sesión (mayor): flags de CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) y sobrecargas -c key=value
2. Configuración del proyecto (.codex/config.toml, descubierto desde el directorio de trabajo actual hacia arriba hasta la raíz del proyecto; el directorio más cercano prevalece)
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 restricción de políticas que limita los valores que los usuarios pueden seleccionar después de la fusión normal de configuración. Consulte Implementación empresarial.

Ubicaciones de archivos de configuración

Consejo avanzado: La variable de entorno CODEX_HOME sobrescribe el directorio predeterminado ~/.codex. Útil para CI/CD o configuraciones con múltiples cuentas.

Referencia completa de configuración

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K input context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.2-codex"         # Model for /review command
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-failure|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

# ─── 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)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

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

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

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

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

Perfiles

Presets de configuración con nombre para diferentes 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"

Active un perfil:

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

Consejo avanzado: Establezca un perfil predeterminado con profile = "fast" en el nivel superior de su configuración. Sobrescríbalo por sesión con --profile.

Proveedores de modelos personalizados

Conéctese a Azure, 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"

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

Advertencia: El wire API de chat/completions (wire_api = "chat") fue descontinuado para modelos alojados en OpenAI, con OpenAI anunciando su eliminación en febrero de 2026.³⁶ Los proveedores locales (Ollama, LM Studio) pueden seguir aceptando este formato. Para endpoints de OpenAI, utilice wire_api = "responses" en su lugar.

Utilice modelos locales con el flag --oss:

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

O configúrelo en el archivo de configuración:

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

Sobrecargas de configuración en línea

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

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

¿Qué modelo debería elegir?

Modelos disponibles (marzo de 2026)

GPT-5.4 está disponible en todas las superficies de Codex (CLI, aplicación, extensión de IDE, nube).⁶⁶ La lista exacta de modelos varía según la cuenta y el despliegue. Consulte su 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 a través de API y CLI para cargas de trabajo sensibles al costo.⁷³

Diagrama de flujo para 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
   │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │  └─ No → gpt-5.4 (recommended: coding + reasoning + computer use, 1M context)
   └─ Still unsure? → gpt-5.4

Esfuerzo de razonamiento

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

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

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

Consejo avanzado: El razonamiento xhigh puede consumir entre 3 y 5 veces más tokens que medium para el mismo prompt. Resérvelo para problemas genuinamente difíciles donde el razonamiento adicional vale la pena.

Cambio de modelo

Cambie de modelo durante la sesión con el slash command /model, o configúrelo por ejecución con --model / -m:

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

¿Cuánto cuesta Codex?

Consulte también Selección de modelo para conocer las capacidades y Marcos de decisión para elegir el modelo adecuado según la tarea.

Acceso a través de los planes de ChatGPT

La disponibilidad de Codex depende de su plan de ChatGPT y la configuración de su organización:⁵³

Tarifas promocionales: El acceso gratuito para Free/Go y los límites de uso 2x para planes de pago coincidieron con el lanzamiento de Codex Desktop App (febrero de 2026). Estos límites más altos se aplican en todas las superficies: aplicación, CLI, IDE y nube. OpenAI no ha anunciado una fecha de finalización.¹⁷

Costos de créditos

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

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

Facturación de API

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

Estrategias de optimización de costos

1. Use perfiles: Cree un perfil fast con gpt-5.1-codex-mini y model_reasoning_effort = "low" para tareas rutinarias
2. Reserve el razonamiento alto: Solo use xhigh para problemas genuinamente difíciles, ya que cuesta entre 3 y 5 veces más tokens
3. Use --ephemeral: Omita la persistencia de sesión en CI/CD para reducir la sobrecarga
4. Minimice los resúmenes de razonamiento: Configure model_reasoning_summary = "none" cuando no necesite explicaciones
5. Agrupe con modo exec: codex exec evita la sobrecarga del TUI para flujos de automatización
6. Monitoree el uso: Consulte /status en el TUI y los paneles de facturación de su organización

Ejemplos de costos reales

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. Use gpt-5.1-codex-mini para tareas rutinarias y reduzca los costos entre un 40 y un 60%. Los tokens de entrada en caché se facturan con descuento.

Sobrecarga oculta de tokens

Cada llamada a herramienta agrega tokens más allá de su prompt visible:

Consejo avanzado: Monitoree su uso real a través de /status en el TUI. El conteo de tokens incluye toda la sobrecarga, no solo sus mensajes visibles. Si los costos le sorprenden, verifique cuántos servidores MCP están conectados — cada uno agrega definiciones de herramientas a cada llamada de API.

Gestión de costos para equipos

Estrategias para el control de costos en equipos: - Configure requirements.toml para imponer límites de modelo y esfuerzo de razonamiento en toda la organización - Use gpt-5.1-codex-mini para CI/CD — los pipelines automatizados rara vez necesitan razonamiento máximo - Presupuesto basado en perfiles — defina perfiles ci, review y dev con límites de costo apropiados - Monitoree vía OpenTelemetry — los despliegues empresariales pueden exportar telemetría de uso a los 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 general: Enter = “detente, escucha esto ahora.” Tab = “cuando termines, también haz 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 Usar?

Asocie su 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"

Cambiar perfil por sesión: codex --profile careful

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

Codex utiliza un modelo de seguridad de dos capas que separa lo que es técnicamente posible de cuándo Codex solicita aprobación humana. El enfoque difiere fundamentalmente del sistema de permisos de Claude Code: Codex aplica las restricciones a nivel del kernel del sistema operativo.⁵ Consulta también Enterprise Deployment para conocer las restricciones de requirements.toml que los administradores aplican a 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:

Implementación según la plataforma:

• macOS: El framework Seatbelt de Apple mediante sandbox-exec con perfiles específicos por modo, compilados en tiempo de ejecución y aplicados por el kernel⁶
• Linux: Landlock para restricciones del sistema de archivos + seccomp para filtrado de syscalls. Un proceso auxiliar independiente (codex-linux-sandbox) proporciona aislamiento con defensa en profundidad.⁵ Bubblewrap (bwrap) se incluye como dependencia vendored y se compila como parte del build de Linux (promovido de opcional en v0.100.0)⁷. La v0.117.0 mejoró la fiabilidad del sandbox en distribuciones antiguas con configuraciones de kernel legacy.⁷⁷
• Windows: Sandbox nativo con tokens restringidos (promovido de experimental en v0.100.0). WSL también es compatible (hereda Landlock + seccomp de Linux). La v0.117.0 incluye mejoras en el sandbox de tokens restringidos para un mejor aislamiento de procesos.⁷⁷

Por qué esto importa: A diferencia del sandboxing basado en contenedores (Docker), el sandboxing a nivel de 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: - Bypass de sandbox por fork de zsh (v0.106.0): Se corrigió una vulnerabilidad donde la ejecución de shell mediante forking 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 aproximadamente 1 millón de caracteres en la entrada para evitar bloqueos por payloads excesivamente grandes.⁶² - Sistema de archivos /dev en Linux (v0.105.0): Los comandos en sandbox en Linux ahora reciben un sistema de archivos /dev mínimo, mejorando 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 desde 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 detiene para solicitar confirmación humana:

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

Codex ahora asigna IDs de aprobación distintos a cada comando dentro de una ejecución de shell de múltiples pasos. Esto significa que las aprobaciones son granulares: aprobar un comando en una secuencia no aprueba automáticamente los siguientes en la misma invocación de shell.⁵¹

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

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

• Permisos adicionales de sandbox: 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 a herramientas individuales con retroalimentación para que Codex pueda ajustar su enfoque en lugar de simplemente reintentar el mismo comando

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

Codex ahora incluye una herramienta integrada request_permissions que permite al modelo solicitar permisos adicionales en tiempo de ejecución.⁷¹ Cuando el modelo encuentra una tarea que requiere acceso elevado, puede solicitar formalmente permisos específicos (rutas del sistema de archivos, acceso a red, etc.) a través del flujo de aprobación del TUI en lugar de fallar silenciosamente o requerir que reinicies con diferentes flags.

Lenguaje de configuración de perfiles de permisos (v0.113.0+)

Un nuevo lenguaje de configuración para perfiles de permisos divide las políticas de sandbox de sistema de archivos y red en secciones separadas y componibles:⁷¹

[permission_profile.filesystem]
read = ["~/Projects", "/usr/local"]
write = ["~/Projects/my-app"]

[permission_profile.network]
allow = ["api.github.com", "registry.npmjs.org"]
deny = ["*"]   # Global wildcard domains now rejected (hardened in v0.113.0)

Esto reemplaza el modo de sandbox monolítico con políticas granulares por recurso. Los perfiles de permisos ejecutables también se integran con la política de sandbox por turno para la ejecución de skills (v0.112.0).⁷⁰

El flag --full-auto

--full-auto es un alias de conveniencia para:

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

Detalle crítico: --full-auto anula cualquier valor explícito de --sandbox. Si pasas --full-auto --sandbox read-only, obtienes workspace-write porque --full-auto tiene precedencia.⁸

Configuraciones recomendadas

Desarrollo diario (opción segura por defecto):

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

Usuario avanzado (acceso completo, humano en el bucle):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

Esta combinación es el “punto óptimo” recomendado por la comunidad: máxima capacidad, pero con aprobación requerida para cada comando.⁹

Automatización CI/CD:

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

Smart Approvals con Guardian Subagent (v0.115.0+)

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

Configura el revisor en config.toml:

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

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

Habilitar acceso a la red

Codex bloquea el acceso a la red por defecto 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

Soporte de proxy WebSocket (v0.104.0+)

Para entornos corporativos que enrutan el tráfico WebSocket a través de un proxy, Codex ahora es compatible con las variables de entorno WS_PROXY y WSS_PROXY:⁵¹

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

Estas complementan el soporte existente de proxy HTTPS_PROXY y 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 --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

Si el sandbox funciona correctamente, ambos comandos deberían fallar con un error de permiso denegado: el sandbox impide la lectura de archivos sensibles del sistema incluso en modo --full-auto. Si alguno de los comandos tiene éxito, la configuración de tu sandbox necesita investigación.

¿Cómo funciona AGENTS.md?

AGENTS.md es el sistema de instrucciones de proyecto de Codex — un estándar abierto¹⁰ ahora gobernado por la Agentic AI Foundation de la Linux Foundation. Compatible con Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode y más de 60.000 proyectos de código abierto. Define cómo se comporta Codex dentro de un repositorio o directorio específico. Consulta Skills para paquetes de experiencia reutilizables 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 (raíz de git hasta el directorio actual): Cada nivel se revisa buscando 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 tienen prioridad sobre las instrucciones anteriores

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

Qué hace un buen AGENTS.md

Basado en orientación directa de Codex y patrones de la comunidad¹¹:

SÍ: - Sé específico: "Use rg --files for discovery" es mejor que "search efficiently" - Define el cierre: ¿Qué significa “terminado”? (tests pasan, lint limpio, etc.) - Incluye comandos: Build, test, lint, format (invocaciones exactas) - Organiza por tarea: Secciones de codificación, revisión, release, incidentes/depuración - Define la escalación: Qué hacer cuando te bloqueas o encuentras un estado inesperado

NO: - 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 ejecución) - Escribir documentación en prosa (AGENTS.md es política operativa, no un 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.

El mecanismo de override

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

• Congelación de releases: “Sin funciones nuevas, solo correcciones”
• Modo de incidente: “Todos los cambios deben ser revisados por el guardia de turno”
• Endurecimiento temporal: “Sin actualizaciones de dependencias 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), luego agregó un motor de hooks experimental en v0.114.0 con los eventos SessionStart y Stop.⁷² El sistema ahora cubre el ciclo de vida de la sesión y la automatización a nivel de herramientas, 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)'"

La salida stdout del hook SessionStart se inyecta en el contexto del modelo, lo que lo hace ideal para incorporar información dinámica (fechas, nombres de rama, 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 avanzado: El motor de hooks es experimental y se está expandiendo activamente. Consulta el changelog de Codex para conocer nuevos eventos de hooks en cada versión.

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

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

Configuración de servidores MCP

Servidores STDIO (procesos locales):

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

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

Servidores HTTP (remotos):

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

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

Durante la sesión: /mcp muestra los servidores activos y las herramientas disponibles.

Ejecutar Codex COMO servidor MCP

Codex puede exponerse como servidor MCP para orquestación multi-agente:¹³

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 el 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 con contexto — Combina Context7 con la documentación de tu framework para que Codex siempre tenga referencias actualizadas de la API:

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

Patrón 2: Límites de salida — Las respuestas de herramientas MCP se truncan a ~25K caracteres por defecto. Para herramientas que devuelven grandes volúmenes de datos (consultas a bases de datos, capturas de logs), usa enabled_tools para restringir a herramientas específicas y mantener las respuestas enfocadas.

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

Patrón 3: Gobernanza empresarial de MCP — Controla 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 será bloqueado al iniciar. Consulta Enterprise Deployment para 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.

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

Entorno de ejecución REPL de JavaScript [EXPERIMENTAL]

Codex v0.100.0 agregó un entorno de ejecución REPL experimental de JavaScript (js_repl) que mantiene el estado entre llamadas a herramientas. En la v0.106.0, el REPL fue promovido al slash command /experimental con verificaciones de compatibilidad al inicio — requiere Node.js 22.22.0 o posterior.⁶²

Habilitación del JS REPL:

# In config.toml
[features]
js_repl = true

O actívalo durante la sesión mediante /experimental en el TUI.

Ejemplo de uso: Cuando está habilitado, Codex puede mantener el estado entre llamadas a herramientas dentro de una sesión:

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

Requisitos: Node.js 22.22.0+ (las verificaciones al inicio comprueban la compatibilidad). La v0.105.0 añadió informes de errores mejorados y recuperación ante fallos del REPL.⁶³

Esta función es experimental. La interfaz puede cambiar entre versiones.

¿Qué son los skills?

Los skills son paquetes de capacidades reutilizables y orientados a tareas específicas 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 (por defecto: ~/.codex/skills), incluyendo los skills del sistema integrados en .system/. Codex admite carpetas de skills con enlaces simbólicos.

Creación de un skill

Formato de SKILL.md:

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

## Procedimiento de auditoría de seguridad

1. Busca secretos codificados usando `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Verifica inyección SQL: busca interpolación de cadenas en consultas
3. Valida la entrada en todos los endpoints de API
4. Revisa vulnerabilidades en dependencias: `pip audit` o `npm audit`
5. Revisa los patrones de autenticación y autorización
6. Reporta los hallazgos con niveles de severidad (Crítico/Alto/Medio/Bajo)

Metadatos (agents/openai.yaml):

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

policy:
  allow_implicit_invocation: false    # Require explicit $skill

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

Invocar skills

• Explí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 construir un nuevo skill de forma interactiva
• Instalador: Usa $skill-installer install <name> para instalar skills de la comunidad

Habilitar/Deshabilitar

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

Skills vs Slash Commands

Depurar skills

Si un skill no se activa:

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

Ejemplo de producción: Deploy Skill

Un skill completo con múltiples archivos que muestra referencias y scripts trabajando 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

Los plugins unifican skills, entradas de MCP y conectores de aplicaciones en un único paquete instalable (v0.110.0+).⁶⁷ A partir de v0.117.0, los plugins son ciudadanos de primera clase: los plugins con alcance de producto se sincronizan automáticamente al iniciar, /plugins proporciona un navegador dentro del TUI para descubrimiento y gestión, y las operaciones de instalación/eliminación funcionan tanto desde CLI como desde el TUI.⁷⁷

Fuentes de plugins

Descubrimiento de plugins

Codex informa al modelo qué plugins están habilitados al inicio de la sesión (v0.111.0), mejorando el descubrimiento de MCPs, aplicaciones y skills instalados.⁶⁷ El modelo puede sugerir plugins relevantes durante una sesión según el contexto de la tarea. En v0.117.0, los plugins con alcance de producto se sincronizan al iniciar, asegurando que el catálogo de plugins más reciente esté disponible sin intervención manual.⁷⁷

Menciones @plugin (v0.112.0+)

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

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

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

Marketplace de plugins (v0.113.0+)

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

Gestionar plugins

codex plugin list              # Show installed plugins
codex plugin install <name>    # Install from marketplace
codex plugin uninstall <name>  # Remove plugin and config (v0.113.0+)

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

Consejo avanzado: Los plugins consolidan lo que antes requería configuración separada de MCP, instalación de skills y configuración de conectores de aplicaciones. Un solo plugin puede agrupar los tres, lo que hace la incorporación de equipos más rápida y la configuración más portable.

Plan Mode y colaboración

Plan mode permite que Codex diseñe un enfoque antes de ejecutar cambios. Está habilitado por defecto (desde v0.94.0).¹⁵ Consulta Marcos de decisión para el árbol de decisión “Plan Mode vs Ejecución directa”.

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 código base - Propone un plan de implementación - No realiza cambios hasta que apruebes - Transmite el plan en una vista dedicada del TUI

Steer Mode

Steer mode (habilitado por defecto desde v0.98.0) te permite inyectar nuevas instrucciones mientras Codex está trabajando activamente, sin interrumpir su tarea actual.¹⁵

Hay dos métodos de inyecció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 está siempre activo en el TUI. Si prefieres esperar a que Codex termine antes de dar instrucciones, simplemente escribe normalmente después de que el turno se complete — no se necesita ningún modo especial.

Mejoras del TUI (v0.105.0–v0.106.0)

Resaltado de sintaxis (v0.105.0): El TUI ahora resalta con sintaxis los bloques de código delimitados y los diffs en línea. Usa /theme para elegir un esquema de colores.⁶³

Nuevos comandos del 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 selección de dispositivos de micrófono y altavoz, permitiéndote elegir hardware específico de entrada/salida de audio.⁶⁴

Otras mejoras: - Los enlaces largos ahora permanecen clicables incluso cuando se ajustan a lo largo de las líneas del TUI (v0.105.0)⁶³ - Los enlaces a archivos locales se renderizan con formato mejorado (v0.106.0)⁶² - El manejo de Ctrl+C para sub-agentes fue corregido para terminar correctamente los procesos hijos (v0.106.0)⁶²

Sistema de memoria

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

Comandos de memoria

Los recuerdos se almacenan en archivos markdown bajo ~/.codex/memory/. Codex los carga al iniciar cada sesión y los utiliza para guiar su comportamiento en todas las sesiones futuras.

Qué almacenar

Los recuerdos funcionan mejor para preferencias persistentes y hechos del proyecto:

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

Memoria en pipelines

Al ejecutar codex exec, los recuerdos 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)

• Sanitización de secretos: Los recuerdos se escanean automáticamente en busca de secretos antes de escribirse en disco
• Reconocimiento del directorio de trabajo: Los archivos de memoria ahora incluyen el contexto del directorio de trabajo para una recuperación específica por proyecto
• Exclusión de mensajes del desarrollador: Los mensajes del desarrollador y del sistema se excluyen de la entrada de memoria en fase 1, lo que mejora la calidad al enfocarse en las interacciones del usuario
• Olvido basado en diffs (v0.106.0): La memoria ahora utiliza olvido basado en diffs para eliminar hechos obsoletos, manteniendo el almacén de memoria ligero y relevante con el tiempo⁶²
• Selección según uso (v0.106.0): La recuperación de memoria ahora considera el uso, priorizando los recuerdos accedidos con frecuencia y los más relevantes recientemente⁶²
• Memorias configurables (v0.107.0): Las memorias son ahora completamente configurables. Usa codex debug clear-memories para restablecer todos los recuerdos almacenados y empezar desde cero — útil al cambiar de contexto entre proyectos no relacionados o cuando el estado de la memoria ha divergido⁶⁴

Memoria vs AGENTS.md

Consejo: Usa /m_update para hechos 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 del equipo, usa AGENTS.md.

Gestión de sesiones

Codex persiste las sesiones en ~/.codex/sessions/, lo que permite reanudar, bifurcar y trabajar con múltiples hilos a través de CLI y la aplicación de escritorio.

Reanudación

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 del TUI abre el mismo selector interactivo con búsqueda.

Bifurcación

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 resulta útil para comparar enfoques (por ejemplo, “bifurcar e intentar con Redis en lugar de Memcached”) o explorar cambios arriesgados de forma segura.

Bifurcación de hilos en sub-agentes (v0.107.0): Los hilos ahora pueden bifurcarse en sub-agentes independientes, lo que permite que una conversación genere flujos de trabajo paralelos que se ejecutan de forma autónoma. Esto extiende el modelo de bifurcación existente: en lugar de simplemente ramificar la conversación, el hilo bifurcado se convierte en un sub-agente con su propio contexto de ejecución.⁶⁴ A partir de v0.117.0, los sub-agentes utilizan direcciones basadas en rutas (p. ej., /root/agent_a) con mensajería estructurada entre agentes, lo que hace la coordinación multiagente más explícita y depurable.⁷⁷

Listado de hilos

Visualiza y gestiona las sesiones activas:

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

En la aplicación de escritorio, los hilos son visibles en la barra lateral con historial completo y vistas previas de diffs.

Ciclo de vida de las sesiones

Las sesiones se sincronizan entre CLI y la aplicación de escritorio: puedes iniciar en uno y continuar en el otro.

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 --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Por defecto, codex exec escribe el progreso y los eventos en stderr y el mensaje final del agente en stdout. Este diseño lo hace componible con pipelines estándar de Unix.

Salida en líneas JSON

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

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

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

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

Salida estructurada

Impón la 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 principales

Autenticación en CI

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

Codex Cloud y tareas en segundo plano [EXPERIMENTAL]

Estado: Codex Cloud es una función experimental. Las interfaces, precios y disponibilidad pueden cambiar. OpenAI gestiona los entornos en la nube, y no tienes control sobre la infraestructura.

Codex Cloud ejecuta tareas de forma asíncrona en entornos gestionados 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 (a través de chatgpt.com/codex, la integración con Slack o CLI)
2. Codex clona tu repositorio en un sandbox aislado en la nube
3. El agente trabaja de forma independiente: lee código, ejecuta tests y realiza cambios
4. Al terminar, 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 la nube

El acceso a internet del agente está desactivado por defecto y se configura por entorno:

• Desactivado: Sin acceso a internet para el agente (por defecto)
• Activado: Lista opcional de dominios permitidos + restricciones de métodos HTTP

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

Los scripts de configuración inicial pueden usar internet para instalar dependencias, incluso cuando el acceso a internet del agente está desactivado.

Integración con Slack

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

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

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

CLI en la nube

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

La Aplicación de Escritorio Codex

La aplicación de escritorio Codex (macOS y Windows) proporciona una interfaz gráfica optimizada para la gestión de múltiples proyectos.¹⁷ La versión de Windows se lanzó el 4 de marzo de 2026 con soporte nativo de 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 la Microsoft Store (Windows)

Funciones principales

Modos de hilo

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

Mecánica de aislamiento de Worktree:

Cuando inicias un hilo en modo Worktree, la aplicación de escritorio: 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 están aislados 4. Presenta una revisión de diferencias al terminar — tú eliges qué cambios fusionar de vuelta

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

Automatizaciones

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

• En repositorios Git, las automatizaciones usan worktrees dedicados en segundo plano (aislados de tu directorio de trabajo)
• En proyectos sin Git, las ejecuciones se realizan 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 aplicación de escritorio 2. Haz clic en la pestaña Automations en la barra lateral 3. Define un disparador (programado, webhook o manual) 4. Escribe la indicación y selecciona el modo de ejecución (local o worktree) 5. Establece el nivel de razonamiento para la ejecución de la automatización (App v26.312)⁷⁴ 6. Las automatizaciones se ejecutan según lo programado y ponen los resultados en cola para revisión

Casos de uso de ejemplo: - Triaje de issues: Categoriza y prioriza automáticamente los issues nuevos - Monitoreo de CI: Observa fallos de compilación y sugiere correcciones - Respuesta a alertas: Reacciona a alertas de monitoreo con análisis de diagnóstico - Actualizaciones de dependencias: Verifica 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 de PowerShell, sandbox nativo de Windows y paridad completa de funciones, incluyendo skills, automatizaciones y worktrees sin necesidad de WSL.⁶⁸

GitHub Action y CI/CD

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

Uso básico

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

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

Opciones de configuración

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

Estrategias de seguridad

Controles de acceso

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

Por defecto: solo los colaboradores con acceso de escritura pueden activar flujos de trabajo de Codex.

Codex SDK

El TypeScript SDK 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 del SDK

• runStreamed(...): Flujo de eventos asíncrono para actualizaciones intermedias
• outputSchema: Impone una salida final con forma JSON
• Entrada multimodal: Pasa texto + imágenes locales ({ type: "local_image", path: "..." })
• Flujos de trabajo con imágenes (v0.117.0): view_image devuelve URLs, las imágenes generadas se pueden reabrir y el historial de imágenes sobrevive al reanudamiento de sesión⁷⁷

Configuración de hilos y cliente

// 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.2-codex" },
});

Las sesiones persisten en ~/.codex/sessions.

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

Optimización del rendimiento

Gestión de contexto

Los modelos insignia tienen ventanas de entrada de 272K tokens (128K de salida, 400K de presupuesto total), pero aun así se llenan más rápido de lo que piensas. Gestiona proactivamente:

1. Usa /compact regularmente: Resume el historial de conversación para liberar tokens
2. Proporciona documentación local: 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: Referencia archivos directamente en lugar de pedirle a Codex que los busque
4. Mantén las indicaciones enfocadas: Indicaciones con alcance definido y 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/verificaciones independientes de forma concurrente, así que estructura las indicaciones para habilitar esto
4. Bucles orientados a resultados: Pide “implementa, prueba, corrige, detente cuando pase” en lugar de 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 del TUI durante la sesión:

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

Nota: codex --verbose no es un flag válido de nivel superior. Usa los subcomandos de depuración y los diagnósticos del TUI descritos arriba.

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)

También puedes crear issues en github.com/openai/codex/issues.¹

Despliegue empresarial

Controles de administrador (requirements.toml)

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

# /etc/codex/requirements.toml

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

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

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

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

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

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

A diferencia del config.toml de usuario que establece preferencias, requirements.toml es una capa de restricciones estrictas que limita los valores que los usuarios pueden seleccionar, y estos no pueden sobreescribirla. Las reglas de requisitos del administrador solo pueden solicitar confirmación o prohibir (nunca permitir silenciosamente).

Configuración MDM para macOS

Distribuye mediante MDM usando el dominio de preferencias com.openai.codex.²² Codex respeta los payloads estándar de MDM de macOS (Jamf Pro, Fleet, Kandji, etc.). Codifica el TOML en base64 sin ajuste de línea:

Precedencia (de mayor a menor):

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

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

Integración con OpenTelemetry

Codex soporta la propagación de contexto de trazas OpenTelemetry desde las variables de entorno estándar de OTel hacia las llamadas a la API de OpenAI. Establece 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

• Las variables de entorno estándar OTEL_* son respetadas (endpoint, nombre del servicio, atributos de recurso)
• El contexto de trazas se propaga a través de Codex hacia las llamadas a la API, habilitando observabilidad de extremo a extremo
• Usa atributos de recurso para etiquetar trazas por equipo, entorno o proyecto
• Ten en cuenta los requisitos de privacidad al habilitar el registro de prompts/herramientas — las trazas pueden contener fragmentos de código

Acceso empresarial

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

Manejo de datos y cumplimiento: - Las entradas/salidas de la API no se utilizan para entrenamiento bajo los términos de Business/Enterprise/API de OpenAI - Para residencia de datos, el tráfico de la API de OpenAI se enruta a través de infraestructura en EE.UU. por defecto; 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 a la API salen de la máquina - ChatGPT Enterprise soporta marcos de cumplimiento incluyendo SOC 2, GDPR y CCPA

Estrategia de despliegue

Despliegue por fases recomendado para organizaciones:

1. Piloto (Semana 1-2): Despliega a 3-5 ingenieros senior con requirements.toml imponiendo el modo sandbox untrusted y búsqueda web cached. Recopila retroalimentación 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 vía MDM o repositorio. Habilita el sandbox workspace-write para repositorios de confianza.
3. Integración CI (Semana 5-6): Agrega codex-action a los pipelines de CI/CD para revisión automatizada de PRs y generación de pruebas. Usa --ephemeral para mantener los costos predecibles.
4. Toda la organización (Mes 2+): Despliega vía 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 asegura el cumplimiento:

• Trazas OpenTelemetry: Monitorea el volumen de llamadas a la API, uso de tokens y latencia por equipo
• Persistencia de sesiones: Audita ~/.codex/sessions/ para revisiones de cumplimiento (deshabilita con --ephemeral en contextos sensibles)
• Imposición de identidad MCP: requirements.toml registra intentos de servidores bloqueados — revisa para detectar uso no autorizado de herramientas
• Trazabilidad en Git: Todos los cambios de archivo de Codex pasan por git estándar — revisa mediante el historial de ramas y diffs de PRs

Buenas prácticas y antipatrones

Patrones de prompts

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

Filosofía de testing

La comunidad converge en la colaboración con IA basada en pruebas:²³

• Define las pruebas por adelantado como señales de completitud
• Deja que Codex itere hasta que las pruebas pasen (rojo → verde → refactorizar)
• Adopta patrones de programación Tiger Style
• Proporciona el texto exacto del archivo cuando solicites parches. Codex usa coincidencia estricta, no parcheo difuso basado en AST

Buenas 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 rastreados para prevenir fallos en los parches
• Mantén AGENTS.md conciso, ya que instrucciones largas se desplazan fuera del contexto

Flujo de trabajo con Git

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

Skills y prompts de la comunidad

El repositorio feiskyer/codex-settings proporciona configuraciones mantenidas por la comunidad:²⁴

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

Skills de la comunidad: - claude-skill: Delega tareas a Claude Code con modos de permisos - autonomous-skill: Automatización de tareas multi-sesión con seguimiento de progreso - deep-research: Orquestación paralela de subtareas - kiro-skill: Pipeline de requisitos → diseño → tareas → ejecución

Antipatrones

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

Antipatrones de costos

Antipatrones de contexto

Antipatrones de flujo de trabajo

Antipatrones de prompts

Recetas de flujo de trabajo

Patrones de extremo a extremo para escenarios comunes de desarrollo.

Receta 1: Configuración de 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, 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 dirige:

[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."

Consulta el progreso después:

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 opera a nivel de sistema operativo: Codex usa Seatbelt/Landlock, no contenedores. Las restricciones operan a nivel del kernel, por debajo de la capa de aplicación.
• Los hooks están en expansión: Codex ahora soporta 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, interceptación de prompts y automatización a nivel de herramientas, aunque los más de 12 eventos del ciclo de vida de Claude Code aún ofrecen mayor cobertura. 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 extiende la maquinaria existente (máx. 6 concurrentes, reducido de 12 en v0.91.0). Los roles multiagente siguen siendo personalizables mediante configuración (v0.104.0+).⁴⁹ La versión v0.105.0 agregó spawn_agents_on_csv para distribución en paralelo por filas con seguimiento de progreso y ETA.⁶³ Codex aún carece del UX explícito de la 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 de código abierto. CLAUDE.md es exclusivo de Claude.
• Los perfiles reemplazan la configuración manual: En lugar de cambiar flags por ejecución, define perfiles en config.toml.

Desde GitHub Copilot

Lo que ganas: - Sandbox a nivel de 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 entre flujos de trabajo - Aplicación de escritorio con aislamiento por worktree

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                   ║
║  --full-auto                workspace-write + on-request      ║
║  --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   /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 ║
║  /experimental Toggle experimental features (js_repl)        ║
║                                                               ║
║  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 --full-auto "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 list              List installed plugins        ║
║  codex plugin install <name>    Install from marketplace      ║
║                                                               ║
║  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-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (March 2026, v0.116.0)                                ║
║  gpt-5.4               Recommended flagship (1M context)     ║
║  gpt-5.3-codex         Coding specialist (272K in / 400K)    ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Registro de cambios

Referencias

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