Codex CLI: The Definitive Technical Reference

TL;DR: Codex es un agente de programación multisuperficie que lee su repositorio, ejecuta comandos en un sandbox a nivel de sistema operativo, modifica archivos y delega tareas a la nube. Domine cinco sistemas centrales (config.toml, el modelo de sandbox/aprobación, AGENTS.md, MCP y skills) y Codex se convertirá en un multiplicador de productividad. Use profiles para cambiar de contexto, /compact para gestionar el presupuesto de 272K tokens, y AGENTS.md para instrucciones de proyecto compatibles con Codex, Cursor, Amp y más.

Codex opera como un agente de programación multisuperficie, no como un chatbot que escribe código. El CLI lee su repositorio, 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 globalmente; la misma inteligencia impulsa cuatro superficies distintas según su forma de trabajar.

La diferencia entre un uso casual y un uso efectivo de Codex se reduce a cinco sistemas centrales. Domínelos y Codex se convertirá en un multiplicador de productividad:

1. Sistema de configuración: controla el comportamiento mediante config.toml
2. Modelo de sandbox y aprobación: regula lo que Codex puede hacer
3. AGENTS.md: define los 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 ejecutando Codex junto con Claude Code en repositorios de producción, pipelines de CI/CD y flujos de trabajo en equipo. Esta guía destila esa experiencia en la referencia completa que me hubiera gustado tener cuando empecé. Cada función incluye la sintaxis real, ejemplos de configuración concretos 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 y el grupo de comandos MCP son experimentales a partir de la versión v0.107.0. El CLI principal, el sandbox, AGENTS.md, config.toml y Skills son estables.

Puntos Clave

• Cuatro superficies, un cerebro: CLI, la aplicación de escritorio, la extensión para IDE y las tareas en la nube comparten la misma inteligencia GPT-5.x-Codex, así que elija la superficie que mejor se adapte a su 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 multiplataforma: Las instrucciones de su 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íbalas una vez, úselas en todas partes.
• Los perfiles ahorran el costo de cambiar de contexto: Defina presets de configuración con nombre (fast, careful, auto) y cambie entre ellos con --profile.
• El contexto de entrada de 272K se llena rápido: Use /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 — comience donde su nivel de experiencia lo indique:

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

Cómo Funciona Codex: El Modelo Mental

Antes de profundizar en las funciones, comprenda cómo la arquitectura de Codex determina todo lo que hace 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         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Capa Central: La familia de modelos GPT-5.x-Codex impulsa todo. A partir de la v0.107.0, gpt-5.3-codex es el modelo predeterminado con una ventana de contexto de entrada de 272K tokens (128K de salida, 400K de presupuesto total).³⁵ Lee archivos, escribe parches, ejecuta comandos de shell y razona sobre su 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 a través de 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 las llamadas al 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). Skills empaqueta flujos de trabajo reutilizables que Codex carga bajo demanda. Apps se conecta a conectores de ChatGPT. Web search agrega contexto en tiempo real desde internet.

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

La perspectiva clave: La mayoría de los usuarios solo utiliza una superficie. Los usuarios avanzados utilizan las cuatro: Cloud para tareas de larga duración, CLI para operaciones deterministas en repositorios, la extensión para IDE para ciclos de codificación ajustados, y la aplicación de escritorio para planificación y coordinación.

Tabla de Contenidos

1. ¿Cómo Instalo Codex?
2. Inicio Rápido: Su Primera Sesión
3. Superficies de Interacción Principales
4. Sistema de Configuración en Profundidad
5. ¿Qué Modelo Debo Elegir?
6. ¿Cuánto Cuesta Codex?
7. Marcos de Decisión
8. ¿Cómo Funciona el Sistema de Sandbox y Aprobación?
9. ¿Cómo Funciona AGENTS.md?
10. Hooks
11. ¿Qué Es MCP (Model Context Protocol)?
12. Entorno de Ejecución JavaScript REPL
13. ¿Qué Son los Skills?
14. Modo Plan y Colaboración
15. Sistema de Memoria
16. Gestión de Sesiones
17. Modo No Interactivo (codex exec)
18. Codex Cloud y Tareas en Segundo Plano
19. La Aplicación de Escritorio de Codex
20. GitHub Action y CI/CD
21. Codex SDK
22. Optimización de Rendimiento
23. ¿Cómo Depuro Problemas?
24. Despliegue Empresarial
25. Mejores Prácticas y Antipatrones
26. Recetas de Flujo de Trabajo
27. Guía de Migración
28. Tarjeta de Referencia Rápida
29. Registro de Cambios
30. Referencias

¿Cómo Instalo Codex?

Gestores de Paquetes

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

# Homebrew (macOS)
brew install --cask 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 línea como asset de GitHub Releases:⁶²

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

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

Descarga de Binarios

Para entornos sin npm ni Homebrew, descargue 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). WSL también compatible²

Autenticación

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

Dos vías de autenticación:

1. Cuenta de ChatGPT (recomendado): Inicie sesión con su 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 de API: Configúrela mediante la variable de entorno CODEX_API_KEY o codex login --with-api-key. Algunas funciones (hilos en la nube) pueden no estar disponibles.

Consejo avanzado: El almacenamiento de credenciales es configurable mediante cli_auth_credentials_store en config.toml. Opciones: file (predeterminado), keyring (llavero del sistema operativo) 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: Su Primera Sesión

Pase de cero a productivo en 5 minutos.

1. Instale y autentíquese:

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

2. Navegue a un proyecto:

cd ~/my-project                  # Any git repo works

3. Inicie Codex:

codex

Verá la interfaz interactiva TUI. Codex lee la estructura de su proyecto automáticamente.

4. Haga una pregunta:

> What does this project do? Summarize the architecture.

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

5. Realice un cambio:

> Add input validation to the login endpoint

Codex propone ediciones como un diff. Revise y apruebe con y, o rechace con n.

6. Use un slash command:

> /plan Refactor the database layer to use connection pooling

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

7. Verifique su trabajo:

> /diff

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

¿Qué sigue? - Configure AGENTS.md con las instrucciones del proyecto (consulte ¿Cómo Funciona AGENTS.md?) - Configure un perfil para su flujo de trabajo (consulte Perfiles) - Pruebe codex exec para automatización no interactiva (consulte 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 Interactivo (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 interfaz de terminal es una aplicación de pantalla completa con:

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

Atajos clave del TUI:

Slash commands disponibles en el TUI:

2. Codex Desktop App (macOS)

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

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

• Multitarea: Ejecute múltiples agentes en paralelo en diferentes proyectos simultáneamente
• Aislamiento con git worktree: Cada hilo trabaja en una copia aislada de su repositorio
• Revisión de diff integrada: Prepare, revierta y confirme cambios sin salir de la aplicación
• Terminal integrada: Terminal por hilo para ejecutar comandos
• Bifurcación de conversaciones: Ramifique conversaciones para explorar alternativas
• Ventanas flotantes emergentes: Separe conversaciones en ventanas portátiles
• Automatizaciones: Programe tareas recurrentes (clasificación de issues, monitoreo de CI, respuesta a alertas)

¿Cuándo usar la aplicación vs el CLI? Use la aplicación de escritorio cuando esté coordinando múltiples flujos de trabajo o necesite revisión visual de diffs. Use el CLI cuando desee composabilidad de 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 su editor:

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

Instálela 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 administrados por OpenAI:

• Lanzar y olvidar: Encole tareas que se ejecutan independientemente de su máquina local
• Ejecución en paralelo: Ejecute múltiples tareas en la nube simultáneamente
• Creación de PR: Codex crea pull requests a partir del trabajo completado
• Aplicación local: Incorpore los resultados de la nube a su 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é configuración prevalece cuando hay conflictos.

Precedencia (de mayor a menor)

1. Anulaciones de sesión (mayor): indicadores CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) y anulaciones -c key=value
2. Configuración de proyecto (.codex/config.toml, descubierta desde el directorio de trabajo actual hacia arriba hasta la raíz del proyecto; el directorio más cercano prevalece)
3. Configuración de 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 anula 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

Preajustes 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.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.3-codex"
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. Anúlelo 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 protocolo de conexión API 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 indicador --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"

Anulaciones de configuración en línea

Anule 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 (febrero de 2026)

La lista exacta de modelos varía según la cuenta y el despliegue. A partir de la v0.106.0, gpt-5.3-codex es visible en la lista de modelos de CLI para usuarios con clave de API.⁶² Verifique su caché local: ~/.codex/models_cache.json.

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 (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Esfuerzo de razonamiento

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

Los niveles disponibles 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 de 3 a 5 veces más tokens que medium para el mismo prompt. Resérvelo para problemas genuinamente difíciles donde el pensamiento adicional vale la pena.

Cambio de modelo

Cambie de modelo durante la sesión con el slash command /model, o establézcalo por ejecución mediante --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 mediante 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 Free/Go y los límites 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: app, 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 los créditos según la asignación del contrato. Verifique /status en el TUI para consultar 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 consume de 3 a 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: establezca model_reasoning_summary = "none" cuando no necesite explicaciones
5. Ejecute por lotes con exec mode: codex exec evita la sobrecarga del TUI en flujos de automatización
6. Monitoree el uso: verifique /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 medium):

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 herramientas agrega tokens más allá de su prompt visible:

Consejo avanzado: monitoree su uso real mediante /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 por equipo

Estrategias para el control de costos del equipo: - Configure requirements.toml para aplicar 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 topes de costo apropiados - Monitoree mediante OpenTelemetry: los despliegues empresariales pueden exportar telemetría de uso a las pilas 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

Plan Mode 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

Steer Mode: 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 perfiles 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 restricciones a nivel del kernel del sistema operativo.⁵ Consulte también Implementación empresarial para las restricciones de requirements.toml que los administradores aplican a nivel organizacional.

Capa 1: Sandbox (lo que es posible)

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

Implementación específica por 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 llamadas al sistema. Un proceso auxiliar independiente (codex-linux-sandbox) proporciona aislamiento con defensa en profundidad.⁵ Bubblewrap (bwrap) se incluye como dependencia y se compila como parte del build de Linux (promovido de opcional en v0.100.0)⁷
• Windows: Sandbox nativo con tokens restringidos (promovido de experimental en v0.100.0). WSL también es compatible (hereda Landlock + seccomp de Linux)

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 fork de zsh podía eludir las restricciones del sandbox.⁶² Si está usando una versión anterior, actualice de inmediato. - Límite de tamaño de entrada (v0.106.0): Codex ahora aplica un límite de entrada de aproximadamente 1 millón de caracteres para prevenir bloqueos por cargas 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. Úsela para restringir desde qué directorios Codex puede leer, 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: Rechace llamadas a herramientas individuales con retroalimentación para que Codex pueda ajustar su enfoque en lugar de simplemente reintentar el mismo comando

La flag --full-auto

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

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

Advertencia importante: --full-auto anula cualquier valor explícito de --sandbox. Si pasa --full-auto --sandbox read-only, obtendrá workspace-write porque --full-auto tiene precedencia.⁸

Configuraciones recomendadas

Desarrollo diario (configuración segura por defecto):

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

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

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

La combinación es el “punto ó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"

Habilitación del acceso a red

Codex bloquea el acceso a red por defecto en modo workspace-write. Habilítelo 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 de WebSocket a través de un proxy, Codex ahora admite las variables de entorno WS_PROXY y WSS_PROXY:⁵¹

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

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

Prueba del sandbox

Verifique 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, su configuración de sandbox requiere 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. Consulte 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 al directorio actual): Cada nivel se verifica para AGENTS.override.md > AGENTS.md > nombres de archivo alternativos
3. Fusión: Los archivos se concatenan de la raíz hacia abajo; los archivos más cercanos aparecen después en el prompt y anulan las instrucciones anteriores

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

Qué hace un buen AGENTS.md

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

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

NO: - Copiar guías de estilo completas sin reglas de ejecución - Usar directivas ambiguas (“tenga cuidado”, “optimice”) - Mezclar prioridades contradictorias (velocidad + verificación exhaustiva + sin presupuesto de ejecución) - Escribir documentación en prosa (AGENTS.md es política operativa, no README)

Ejemplo: AGENTS.md de producción

# Repository Guidelines

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

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

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

## Seguridad
- Nunca confirme secretos en el repositorio. Use `.env` para la configuración local.
- Valide todas las llamadas externas a API con un manejo adecuado de errores.

El mecanismo de anulación

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

• Congelación de versiones: “Sin funciones nuevas, solo correcciones”
• Modo de incidentes: “Todos los cambios deben ser revisados por el equipo de guardia”
• Endurecimiento temporal: “Sin actualizaciones de dependencias este sprint”

Configuración

# Nombres de archivo alternativos personalizados (además de AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Aumentar el tamaño máximo para archivos de instrucciones grandes
project_doc_max_bytes = 65536    # 64 KiB (predeterminado: 32 KiB)

Generación de estructura base

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

O verifique su cadena de instrucciones:

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

Hooks

Codex agregó hooks en v0.99.0 (AfterAgent) y v0.100.0 (AfterToolUse). El sistema de hooks se encuentra en una etapa temprana en comparación con los más de 12 eventos del ciclo de vida de Claude Code, pero proporciona puntos de entrada de automatización para flujos de trabajo comunes.

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"

Replicar patrones de hooks de Claude Code

Si está migrando desde Claude Code, aquí se explica cómo lograr una automatización similar sin el conjunto completo de eventos de hooks:

Consejo avanzado: El sistema de hooks se está expandiendo activamente. Consulte el registro de cambios de Codex para conocer los nuevos eventos de hooks en cada versión.

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

MCP extiende las capacidades de Codex conectándolo a herramientas y servicios externos. El grupo de comandos codex mcp está actualmente marcado como experimental, y los comandos y el formato de configuración pueden cambiar entre versiones. Codex soporta 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

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

Ejecutar Codex COMO un servidor MCP

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

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

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

Uso con el SDK de Agents (Python):

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

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

Servidores MCP destacados

Patrones prácticos

Patrón 1: Desarrollo con contexto — Combine Context7 con la documentación de su framework para que Codex siempre tenga referencias actualizadas de API:

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

Patrón 2: Límites de salida — Las respuestas de herramientas MCP se truncan a aproximadamente 25K caracteres de forma predeterminada. Para herramientas que devuelven cargas grandes (consultas a bases de datos, capturas de registros), use 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 salida multimodal (imágenes, contenido enriquecido) junto con texto. Esto permite que las herramientas que producen artefactos visuales — capturas de pantalla, diagramas, renderizados de gráficos — los pasen directamente al modelo para su análisis.⁶⁴

Patrón 3: Gobernanza empresarial de MCP — Restrinja 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 inicio. Consulte Implementación empresarial para la configuración completa de políticas.

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 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.⁶²

Habilitar el JS REPL:

# In config.toml
[features]
js_repl = true

O actívelo en 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 versión v0.105.0 agregó informes de errores mejorados y recuperación para 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 específicos para tareas que Codex carga bajo demanda. Siguen el estándar abierto de skills para agentes.¹⁴

Estructura de un skill

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

Ubicaciones de descubrimiento

Codex almacena los skills instalados por el usuario en $CODEX_HOME/skills (predeterminado: ~/.codex/skills), incluyendo los skills del sistema integrados en .system/. Codex soporta carpetas de skills con enlaces simbólicos.

Crear 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. Buscar secretos codificados de forma fija usando `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Verificar inyección SQL: buscar interpolación de cadenas en consultas
3. Verificar la validación de entrada en todos los endpoints de API
4. Verificar vulnerabilidades de dependencias: `pip audit` o `npm audit`
5. Revisar patrones de autenticación y autorización
6. Reportar 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: Use $skill-creator para construir interactivamente un nuevo skill
• Instalador: Use $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

Depuración de Skills

Si un skill no se activa:

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

Ejemplo de Producción: Skill de Despliegue

Un skill completo de 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`.

Invocar con: $deploy to staging o $deploy production with canary rollout

Modo Plan y Colaboración

El modo plan permite que Codex diseñe un enfoque antes de ejecutar cambios. Está habilitado por defecto (desde v0.94.0).¹⁵ Consulte Marcos de Decisión para el árbol de decisión “Modo Plan vs Ejecución Directa”.

Entrar al Modo Plan

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

En el modo plan, Codex: - Lee archivos y analiza el código base - Propone un plan de implementación - No realiza cambios hasta que usted apruebe - Transmite el plan en una vista dedicada del TUI

Modo Steer

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

Existen 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

El modo Steer siempre está activo en el TUI. Si prefiere esperar hasta que Codex termine antes de dar instrucciones, simplemente escriba 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 sintácticamente los bloques de código delimitados y las diferencias en línea. Use /theme para elegir un esquema de colores.⁶³

Nuevos comandos del TUI (v0.105.0+):⁶³

Transcripción de voz (v0.105.0, experimental): Presione la barra espaciadora para dictar prompts mediante transcripción de voz. Esta función es experimental y puede requerir permisos de micrófono.⁶³ A partir de v0.107.0, las sesiones de voz en tiempo real admiten la selección de dispositivos de micrófono y altavoz, lo que le permite elegir hardware de entrada/salida de audio específico.⁶⁴

Otras mejoras: - Los enlaces largos ahora permanecen clicables incluso cuando se ajustan entre 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 secundarios (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

Las memorias se almacenan en archivos markdown bajo ~/.codex/memory/. Codex las carga al inicio de la sesión y las utiliza para informar el comportamiento en todas las sesiones futuras.

Qué Almacenar

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

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

Memoria en Pipelines

Al ejecutar codex exec, las memorias se cargan automáticamente. Esto significa que los pipelines de CI/CD y los scripts se benefician del mismo contexto que las sesiones interactivas — no es necesario repetir instrucciones en cada invocación.

Refinamientos de Memoria (v0.101.0–v0.107.0)

• Sanitización de secretos: Las memorias 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 recuperación específica del proyecto
• Exclusión de mensajes del desarrollador: Los mensajes del desarrollador/sistema se excluyen de la entrada de memoria en fase 1, mejorando la calidad de la memoria al enfocarse en las interacciones del usuario
• Olvido basado en diferencias (v0.106.0): La memoria ahora utiliza olvido basado en diferencias para eliminar hechos obsoletos, manteniendo el almacén de memoria ligero y relevante a lo largo del tiempo⁶²
• Selección consciente del uso (v0.106.0): La recuperación de memoria ahora es consciente del uso, priorizando memorias accedidas frecuentemente y recientemente relevantes⁶²
• Memorias configurables (v0.107.0): Las memorias ahora son completamente configurables. Use codex debug clear-memories para restablecer todas las memorias almacenadas y empezar desde cero — útil al cambiar de contexto entre proyectos no relacionados o cuando el estado de la memoria se ha desviado⁶⁴

Memoria vs AGENTS.md

Consejo: Use /m_update para hechos que deban persistir indefinidamente. Para contexto específico de la sesión, simplemente indíquelo a Codex directamente en la conversación. Para contexto compartido del equipo, use AGENTS.md.

Gestión de sesiones

Codex conserva las sesiones en ~/.codex/sessions/, lo que permite reanudar, bifurcar y trabajar con múltiples hilos entre CLI y las interfaces de escritorio.

Reanudar

Retome donde lo dejó:

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.

Bifurcar

Ramifique una conversación para explorar alternativas sin perder su 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 y probar 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.⁶⁴

Listado de hilos

Visualice y administre 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 diferencias.

Ciclo de vida de la sesión

Las sesiones se sincronizan entre CLI y la aplicación de escritorio — inicie en uno y continúe 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

De forma predeterminada, codex exec escribe el progreso y los eventos en stderr y el mensaje final del agente en stdout. El diseño lo hace componible con las 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

Imponga la estructura de 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 administra los entornos en la nube y usted no controla la infraestructura.

Codex Cloud ejecuta tareas de forma asíncrona en entornos administrados por OpenAI.⁴ Consulte también GitHub Action y CI/CD para integrar Codex en su pipeline de CI.

Cómo funciona

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

Acceso a internet en la nube

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

• Desactivado: Sin acceso a internet para el agente (predeterminado)
• 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 aún pueden usar internet para instalar dependencias, incluso cuando el acceso a internet del agente está desactivado.

Integración con Slack

Mencione @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 su espacio de trabajo

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

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 (solo macOS, Apple Silicon) proporciona una interfaz gráfica optimizada para la gestión de múltiples proyectos.[^17]

### Instalación

```bash
codex app                      # Auto-downloads and installs on first run

O descargue directamente: Codex.dmg

Funciones Principales

Modos de Hilo

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

Mecánica de aislamiento con Worktree:

Cuando inicia un hilo 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 su 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 finalizar — usted elige qué cambios integrar 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 aplicación, por lo que la aplicación debe estar en ejecución y el proyecto disponible en disco:

• En repositorios Git, las automatizaciones usan worktrees dedicados en segundo plano (aislados de su directorio de trabajo)
• En proyectos sin Git, las ejecuciones se realizan directamente en el directorio del proyecto
• Las automatizaciones usan su configuración de sandbox predeterminada

Configurar una automatización: 1. Abra un proyecto en la aplicación de escritorio 2. Haga clic en la pestaña Automatizaciones en la barra lateral 3. Defina un disparador (programado, webhook o manual) 4. Escriba el prompt y seleccione el modo de hilo 5. Las automatizaciones se ejecutan según lo programado y ponen los resultados en cola para revisión

Ejemplos de casos de uso: - Triaje de issues: Categorice y priorice automáticamente los nuevos issues - Monitoreo de CI: Observe fallos de compilación y sugiera correcciones - Respuesta a alertas: Reaccione a alertas de monitoreo con análisis de diagnóstico - Actualización de dependencias: Verifique y aplique parches de seguridad

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

Soporte para Windows

El soporte para Windows está planificado. Consulte la página de la Aplicación de Escritorio Codex o las versiones de GitHub para actualizaciones de disponibilidad.¹⁸

GitHub Action y CI/CD

La GitHub Action oficial integra Codex en su 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

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

Codex SDK

El TypeScript SDK incorpora las capacidades de agente de Codex en aplicaciones personalizadas.²⁰

Instalación

npm install @openai/codex-sdk

Uso Básico

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

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

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

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

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

Funciones Avanzadas del SDK

• runStreamed(...): Flujo de eventos asíncronos para actualizaciones intermedias
• outputSchema: Forzar salida final con formato JSON
• Entrada multimodal: Pase texto + imágenes locales ({ type: "local_image", path: "..." })

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.

Runtime: Node.js 18+.

Optimización de Rendimiento

Gestión del Contexto

Los modelos insignia tienen ventanas de entrada de 272K tokens (128K de salida, presupuesto total de 400K), pero aún así se llenan más rápido de lo que uno piensa. Gestione de forma proactiva:

1. Use /compact regularmente: Resume el historial de conversación para liberar tokens
2. Proporcione documentación local: Un AGENTS.md de alta calidad y documentación local reducen la sobrecarga de exploración (que consume contexto)
3. Use @ para adjuntar archivos específicos: Referencie archivos directamente en lugar de pedirle a Codex que los busque
4. Mantenga los prompts enfocados: Prompts 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 estructure los prompts para habilitarlo
4. Bucles orientados a resultados: Pida “implementar, probar, corregir, detener cuando esté verde” 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. Use los subcomandos de depuración y los diagnósticos del TUI mencionados anteriormente.

Reinstalación limpia

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

Modo de depuración

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

Reportar problemas

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

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

Implementación empresarial

Controles de administración (requirements.toml)

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

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

Configuración de macOS MDM

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

Precedencia (de mayor a menor):

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

Los requisitos de la nube solo completan campos de requisitos no establecidos, por lo que las capas administradas de mayor precedencia siempre prevalecen. Los requisitos de la nube se obtienen con el 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 traza de OpenTelemetry desde las variables de entorno estándar de OTel hasta las llamadas a la API de OpenAI. Establezca 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 recursos)
• El contexto de traza se propaga a través de Codex hacia las llamadas a la API, permitiendo observabilidad de extremo a extremo
• Use atributos de recursos para etiquetar trazas por equipo, entorno o proyecto
• Tenga 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 mediante SAML/OIDC a través de su 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: Incorpórelo en herramientas y flujos de trabajo internos
• Aplicación de políticas a escala: Use 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 con sede en EE. UU. de forma predeterminada; para requisitos de residencia de datos en la UE, consulte al equipo de ventas Enterprise de OpenAI - Las transcripciones de sesiones se almacenan localmente; solo las llamadas a la API salen de la máquina - ChatGPT Enterprise soporta marcos de cumplimiento que incluyen SOC 2, GDPR y CCPA

Estrategia de implementación

Implementación por fases recomendada para organizaciones:

1. Piloto (Semana 1-2): Despliegue a 3-5 ingenieros senior con requirements.toml imponiendo el modo de sandbox untrusted y búsqueda web cached. Recopile retroalimentación sobre patrones de AGENTS.md y necesidades de servidores MCP.
2. Expansión al equipo (Semana 3-4): Despliegue al equipo completo. Distribuya el config.toml estándar del equipo mediante MDM o repositorio. Habilite el sandbox workspace-write para repositorios de confianza.
3. Integración con CI (Semana 5-6): Agregue codex-action a los pipelines de CI/CD para revisión automatizada de PR y generación de pruebas. Use --ephemeral para mantener los costos predecibles.
4. Toda la organización (Mes 2+): Despliegue mediante MDM con requirements.toml imponiendo servidores MCP aprobados, políticas de sandbox y listas de modelos permitidos.

Patrones de auditoría

Rastree el uso de Codex y garantice el cumplimiento:

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

Mejores Prácticas y Anti-Patrones

Patrones de Prompts

1. Prompts orientados a restricciones: Comience con los límites. “Do NOT change the API contracts. Only refactor internal implementation.”
2. Pasos de reproducción estructurados: Los pasos numerados producen mejores correcciones de errores que las descripciones vagas
3. Solicitudes de verificación: Termine con “Run lint + the smallest relevant test suite. Report commands and results.”
4. Referencias a archivos: Use @filename para adjuntar archivos específicos al contexto
5. Bucles orientados a resultados: “Implement, run tests, fix failures, stop only when all tests pass.” Codex itera hasta completar la tarea

Filosofía de Testing

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

• Defina las pruebas por adelantado como señales de finalización
• Permita que Codex itere hasta que las pruebas pasen (rojo → verde → refactorizar)
• Adopte patrones de programación Tiger Style
• Proporcione el texto exacto del archivo al solicitar parches. Codex utiliza coincidencia estricta, no parcheo difuso basado en AST

Mejores Prácticas de Gestión de Contexto

• Proporcione documentación local de alta calidad en lugar de depender de búsquedas web
• Mantenga markdown estructurado con tablas de contenido y archivos de progreso (“divulgación progresiva”)
• Normalice los finales de línea (LF vs CRLF) en los archivos rastreados para evitar fallos en los parches
• Mantenga AGENTS.md conciso, ya que las instrucciones largas se desplazan fuera del contexto

Flujo de Trabajo con Git

• Siempre cree una nueva rama antes de ejecutar Codex en repositorios desconocidos
• Use flujos de trabajo basados en parches (git diff / git apply) en lugar de ediciones directas
• Revise las sugerencias de Codex como revisiones de código en PRs
• Use /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: Extraer 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: Delegar 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 sub-tareas - kiro-skill: Pipeline de requisitos → diseño → tareas → ejecución

Anti-Patrones

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

Anti-Patrones de Costos

Anti-Patrones de Contexto

Anti-Patrones de Flujo de Trabajo

Anti-Patrones de Prompts

Recetas de Flujo de Trabajo

Patrones de extremo a extremo para escenarios comunes de desarrollo.

Receta 1: Configuración de un Nuevo Proyecto

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

Revise el AGENTS.md generado, edítelo para que coincida con sus 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.

Revise con /diff y luego haga commit.

Receta 3: Refactorización Compleja con Modo Plan

codex

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

Revise el plan. Apruebe o dirija:

[Tab] Also add a migration script using Alembic

Después de que Codex ejecute, verifique:

> 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 Tareas en la Nube [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."

Verifique el progreso más tarde:

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

Aplique la corrección localmente cuando termine:

codex apply <TASK_ID>

Guía de Migración

Desde Claude Code

Diferencias clave a comprender:

• El sandbox opera a nivel de sistema operativo: Codex utiliza Seatbelt/Landlock, no contenedores. Las restricciones operan a nivel del kernel, por debajo de la capa de aplicación.
• Los hooks son incipientes: Codex añadió hooks en v0.99.0 (AfterAgent) y v0.100.0 (AfterToolUse), pero el sistema está en una etapa temprana comparado con los más de 12 eventos de ciclo de vida de Claude Code. Para patrones de automatización que aún no están cubiertos, utilice instrucciones en AGENTS.md o skills.
• Los sub-agents son internos pero ahora configurables: Codex cuenta con maquinaria de sub-agents (máximo 6 concurrentes, reducido de 12 en v0.91.0). A partir de v0.104.0, los roles multi-agente son personalizables mediante configuración, permitiendo roles de agentes con nombre y perfiles distintos.⁴⁹ La versión v0.105.0 añadió spawn_agents_on_csv para distribución en filas con seguimiento de progreso y tiempo estimado.⁶³ Codex aún carece de la experiencia de usuario explícita de la herramienta Task de Claude Code para delegación dirigida por el usuario — utilice tareas en la nube u orquestación con SDK para patrones de delegación.
• AGENTS.md es compatible entre herramientas: Su archivo 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 el cambio manual: En lugar de cambiar flags por ejecución, defina perfiles en config.toml.

Desde GitHub Copilot

Lo que obtiene: - Sandboxing a nivel de sistema operativo (Seatbelt/Landlock — aplicado a nivel de kernel vs 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       ║
║  /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               ║
║                                                               ║
║  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 (Feb 2026, v0.106.0)                                  ║
║  gpt-5.3-codex         Default flagship (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 las 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.