El Agent Loop

En cada turno, Codex ejecuta el mismo ciclo. Entenderlo es lo de mayor apalancamiento que puedes hacer:

El ciclo leer → razonar → proponer → aprobar → aplicar → verificar

1. READ       — load relevant files, git status, prior turns
2. REASON     — decide the next action (run cmd? edit file? ask user?)
3. PROPOSE    — surface the action; if high-risk, pause for approval
4. APPLY      — execute the approved action
5. VERIFY     — re-read, run tests, check the result
       ↺ repeat until the goal is met or it asks for help

Por qué importa: un chatbot emite texto. Un agente actúa, observa el resultado y corrige el rumbo. El ciclo es donde Codex justifica su valor — y donde el arnés (AGENTS.md, config, approval policy) moldea el contexto efectivo y la calidad de la iteración.

Hilos

Un hilo es la unidad de conversación y contexto en Codex. Cada hilo lleva su propio historial de mensajes y estado acumulado. Implicaciones prácticas:

• Una tarea por hilo — no acumules trabajo no relacionado en un solo hilo; el contexto se pudre.
• Reanudación — Codex puede reanudar un hilo previo, recuperando su contexto acumulado.
• Paralelo — la app de escritorio y los worktrees permiten que varios hilos corran a la vez sin interferencias (ver pestaña 5).

La regla de oro

Codex es un compañero capaz con correa, no un pozo de los deseos. Tu trabajo es dar dirección, trazar el límite de lo que puede tocar y corregir el rumbo cuando se desvía.

Esta sola frase predice si obtendrás buenos resultados. Codex no es magia — es un ejecutor fuerte que necesita dirección. Dale un objetivo (no una receta paso a paso), restringe lo que se le permite hacer (sandbox + aprobación) y redirígelo cuando haga una suposición errónea.

Ventana de contexto

Lo que cabe en la memoria de trabajo del modelo por turno

La memoria de trabajo efectiva de Codex por turno es finita. A medida que un hilo crece, los turnos previos, las salidas de herramientas y las lecturas de archivos se acumulan. Dos consecuencias prácticas:

• Compacta de forma proactiva — /compact resume el hilo para recuperar espacio; hazlo antes de que la calidad decaiga, no después.
• “1M de contexto” no es 1M utilizable — los system prompts, las definiciones de herramientas y los archivos recuperados consumen una porción grande; el presupuesto efectivo para tu tarea es mucho menor que el número del titular.

Modos de aprobación y sandbox

Codex expone dos perillas independientes, no una. Esta es la confusión más común entre principiantes:

Tres modos sandbox:

Tres políticas de aprobación: untrusted (pregunta mucho), on-request (el predeterminado diario), never (solo headless/CI).

💡 Combinación dorada para el desarrollo diario: workspace-write + on-request. El agente edita libremente dentro de tu proyecto y se pausa antes de cualquier cosa que salga de él.

⚠️ --yolo = danger-full-access + never. Existe para contenedores desechables. Nunca lo ejecutes en tu máquina real — hay casos documentados de borrado de archivos del usuario.

Modelos y nivel de razonamiento

Dos diales gobiernan “qué tan duro piensa Codex”:

• Modelo (/model o model = "..." en config) — elige según capacidad vs costo. No por defecto al más fuerte para ediciones triviales; no escatimes en un refactor difícil.
• Nivel de razonamiento (/effort o el dial de effort) — low/medium/high/xhigh. Esto tiene más impacto que cambiar de modelo y es más barato de ajustar. Un renombrado de 30 segundos necesita low effort; un refactor de módulo necesita high.

Ajusta el dial a la tarea, no a tu estado de ánimo. Consulta la sección de selección de modelo en la pestaña 6 para una tabla tarea→modelo+effort.

Slash commands

Los slash commands controlan al propio Codex (cambiar de modelo, limpiar contexto, ver estado), no al modelo. Solo cuentan cuando / es el primer carácter de tu mensaje. Escribe / para ver lo disponible en tu punto de entrada actual.

Comandos diarios de la CLI, agrupados según lo que estés haciendo:

⚠️ La CLI expone 40+ slash commands; la app de escritorio expone ~6, el IDE ~8. No esperes la lista completa de la CLI en las superficies GUI.

Modo plan y prompting

Primero planea, luego ejecuta. Para cualquier cosa no trivial, describe el objetivo y deja que Codex produzca un plan; revisa el plan y luego deja que ejecute. Da objetivos y restricciones, no recetas paso a paso — el agent loop es mejor que tú para secuenciar.

Principios de prompting:

• Da contexto, no más palabras. Apunta a los archivos, expresa el objetivo, lista restricciones. La verbosidad no ayuda; la especificidad sí.
• Expresa lo que NO hay que hacer — las instrucciones negativas (“no toques legacy/”, “usa pnpm no npm”) son más nítidas que las positivas.
• Una tarea por mensaje — el agent loop premia el enfoque; los prompts multitarea lo diluyen.

Flujos de trabajo comunes

Los cuatro flujos diarios:

AGENTS.md

AGENTS.md es el archivo de instrucciones por proyecto de Codex — leído al inicio de cada ejecución, antes de actuar. Es el equivalente en Codex del CLAUDE.md de Claude Code (mismo concepto, distinto nombre y reglas de descubrimiento).

Por qué existe: cada ejecución empieza desde una pizarra en blanco. Sin AGENTS.md, vuelves a explicar “usa pnpm, no toques legacy/, corre las pruebas así” cada vez.

Cadena de descubrimiento (3 capas, gana la más cercana):

1. Global — ~/.codex/AGENTS.md (o AGENTS.override.md, que gana). Tus valores predeterminados entre proyectos.
2. Raíz del proyecto — AGENTS.md en la raíz de Git. Reglas compartidas del equipo.
3. Subdirectorios — bajando desde la raíz hasta tu directorio actual, cada directorio puede aportar un AGENTS.md. El más cercano a tu directorio de trabajo gana en conflictos.

~/.codex/AGENTS.md          ← global defaults (your preferences)
project-root/AGENTS.md      ← team rules (overrides global on conflict)
project-root/src/AGENTS.md  ← subdirectory rules (closest wins)

💡 Los conflictos se resuelven por “gana el más cercano” — las reglas del proyecto sobreescriben las preferencias personales, las de subdirectorio sobreescriben las del proyecto. Es exactamente el comportamiento de colaboración en equipo que quieres.

Cómo escribir un AGENTS.md eficaz

Uso de mayor apalancamiento: trátalo como un ciclo de retroalimentación. Cuando Codex hace una suposición errónea sobre tu codebase, no solo la corrijas en el chat (eso es de un solo uso) — haz que escriba la corrección en AGENTS.md. En unas semanas el archivo se llena con los obstáculos que ya se le han atrapado, y las sesiones nuevas dejan de repetir esos errores.

config.toml: conceptos básicos

config.toml es el archivo de perillas de comportamiento — ajustes de máquina que el agente ejecuta literalmente, distintos de AGENTS.md (guía en lenguaje natural). Misma idea que un auto: AGENTS.md es el manual del propietario, config.toml son las perillas del tablero.

Dos ubicaciones:

⚠️ Compuerta de confianza: el .codex/config.toml a nivel de proyecto se ignora para proyectos no confiables. Esto evita que un repo malicioso clonado se conceda permisos en silencio. Si la config de tu proyecto “no surte efecto”, verifica si confiaste en el proyecto al abrirlo por primera vez.

Config mínima:

# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

config.toml: avanzado

Sobrescribe por ejecución sin editar el archivo:

codex -c model="gpt-5.5" -c approval_policy="never"

Cambia entre configuraciones predefinidas con perfiles:

codex --profile ci        # loads the [profiles.ci] block

Habilita la red dentro de workspace-write (está desactivada por defecto — un gotcha común):

[sandbox_workspace_write]
network_access = true

Referencia de configuración

Las claves de alta frecuencia:

ℹ️ Referencia completa: developers.openai.com/codex/config-reference.

Permisos y política de aprobación

Se configuran mediante las dos perillas de arriba. Para el desarrollo diario, rara vez tocas esto tras la configuración inicial — workspace-write + on-request cubre la mayoría del trabajo. Ábrelo a never solo para automatización confiable y en contenedor; ciérralo a read-only al entregar el repo a Codex solo para análisis.

Sandbox y aprobaciones

El sandbox aísla las escrituras del sistema de archivos al workspace y regula la salida de red. Comportamientos clave:

• .git está protegido como solo lectura en workspace-write — Codex no corromperá los metadatos del repo.
• La red está desactivada por defecto aun cuando se permiten escrituras — hay que activarla explícitamente.
• danger-full-access elimina todos los límites — solo contenedor/VM.

⚠️ Advertencia de Windows (verificada, obligatoria): hay múltiples reportes del modo Full Access en Windows borrando archivos del usuario (se reportan 240–700 GB perdidos). Nunca habilites Full Access en Windows; usa WSL2 y quédate en workspace-write.

Hooks (ciclo de vida)

Los administradores pueden bloquear los hooks mediante requirements.toml:

allow_managed_hooks_only = true

Esto ignora las configuraciones de hook de usuario/proyecto/sesión mientras sigue permitiendo los hooks gestionados. Solo es efectivo en requirements.toml — ponerlo en config.toml no hace nada. Úsalo para gobernanza empresarial (ver pestaña 6).

MCP — Herramientas externas

MCP (Model Context Protocol) permite a Codex llamar a herramientas externas — obtener documentación en vivo, consultar una base de datos, manejar un navegador. Codex admite exactamente dos tipos de transporte:

Agrega un servidor de dos formas:

# CLI (lo más rápido) — context7 = servidor gratuito de dev-docs
codex mcp add context7 -- npx -y @upstash/context7-mcp

O escríbelo a mano en config.toml:

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

Cómo el modelo decide llamar a una herramienta externa

💡 Toda la config de MCP vive en config.toml — no hay --scope. El alcance lo decide qué archivo editas (~/.codex/ = global, <repo>/.codex/ = proyecto, requiere confianza). La CLI y el IDE comparten esta única config.

Subagentes

Un subagente es un agente especialista con su propio hilo, modelo, instrucciones y permisos. Codex ejecuta varios en paralelo y cada uno devuelve solo un resumen al hilo principal — manteniendo el ruido de la salida intermedia fuera de tu contexto principal.

El agente principal despacha trabajo; los subagentes devuelven resúmenes, no salida cruda

Dos problemas que los subagentes resuelven:

• Contaminación de contexto — los logs de una tarea grande inundan el hilo principal; los subagentes mantienen el desorden aislado.
• Putrefacción del contexto — los hilos largos se degradan; dividir mantiene cada contexto corto y enfocado.

⚠️ Contraintuitivo: Codex no genera subagentes automáticamente. Solo los despacha cuando tú se lo pides explícitamente. No esperes paralelismo salvo que lo solicites — esto evita costos descontrolados.

Define un agente personalizado como un archivo TOML en ~/.codex/agents/ o <repo>/.codex/agents/:

# ~/.codex/agents/reviewer.toml
name = "reviewer"
model = "gpt-5.5"
instructions = "Review diffs for correctness bugs and security issues."

Skills del agente

Una Skill es un flujo de trabajo reutilizable empaquetado como un directorio con un archivo SKILL.md (más scripts/recursos opcionales). Escribe el flujo una vez; Codex lo invoca cuando hace falta.

Una skill: un directorio con SKILL.md más scripts y referencias opcionales

SKILL.md mínimo:

---
name: summarize-diff
description: Summarize uncommitted changes and flag risks. Use when the user asks for a change summary.
---

Summarize the diff, group changes by file, and call out anything risky
(uncommitted secrets, large deletions, test coverage gaps).

⚠️ Pitfall común (de tutoriales desactualizados): el frontmatter requiere name + description — no hay campo trigger. La activación se hace por coincidencia semántica en description, no por palabras clave. Y el directorio está bajo .agents/skills, no ~/.codex/skills. Sigue la documentación oficial, no blogs antiguos.

Carga progresiva: al iniciar, Codex carga solo el name, description y path de cada skill. El SKILL.md completo se carga solo cuando se usa la skill — manteniendo el contexto ligero.

Plugins

Un plugin es un paquete de capacidades de una sola instalación — skills + agents + hooks + servidores MCP — empaquetado para que instales una configuración entera de golpe en vez de configurar cada pieza a mano. Usa plugins cuando una comunidad o equipo ya ha ensamblado un kit coherente; usa skills/MCP individuales cuando necesitas solo una cosa.

Reglas y hooks

Las reglas y los hooks añaden puntos de control y disparadores de ejecución:

• Reglas — instrucciones condicionales cargadas según el contexto (p. ej. reglas específicas de un framework).
• Hooks — comandos de shell disparados por eventos del ciclo de vida (pre-tool-use, post-turn, etc.) para automatización determinista (formatear al guardar, bloquear un comando, notificar).

Los hooks pueden definirse en config.toml o por agente; la empresa puede bloquearlos a solo gestionados (ver la nota de allow_managed_hooks_only arriba).

El modelo Command → Agent → Skill

La orquestación de Codex refleja el modelo de tres capas de Claude Code:

Cómo elegir un tipo de extensión

Por qué importa el arnés

Calidad de salida = f(contexto_efectivo, capacidad_del_modelo, ciclos_de_iteración)

El arnés — AGENTS.md, config, approval policy, skills, hooks — moldea el contexto efectivo y la calidad de la iteración. Los prompts por sí solos no pueden replicarlo: los prompts son consultivos, pero el arnés impone restricciones de herramientas, carga reglas de forma perezosa por ruta, programa subagentes en paralelo y persiste estado entre sesiones.

Las capas que los prompts no alcanzan — lo que el arnés hace por ti

Modo no interactivo (codex exec)

codex exec ejecuta Codex sin la TUI — le das un prompt, trabaja, imprime el resultado y sale. Diseñado para escenarios “sin humano en el ciclo”: scripts, cron jobs, pipelines de CI.

codex exec "Summarize this repo's structure and list 5 areas to watch"

Diseño clave — progreso a stderr, resultado a stdout. Esta separación te permite encauzar el resultado limpio al siguiente programa y aun así ver el progreso en pantalla:

# machine-readable event stream
codex exec --json "find flaky tests" | jq ...

# save just the final message to a file
codex exec -o result.txt "write release notes for last 10 commits"

⚠️ El modo no interactivo por defecto usa sandbox read-only. Para dejarlo editar archivos, sube el sandbox explícitamente (-s workspace-write) y las aprobaciones (-a never para totalmente desatendido).

Política de ejecución

codex exec puede gobernarse mediante una política de ejecución — control basado en reglas sobre lo que se le permite hacer desatendido. Define reglas para restringir qué comandos pueden ejecutarse, qué rutas pueden escribirse, etc. Esencial para un uso seguro en CI.

Integración con Git y GitHub

Codex se integra con Git/GitHub en dos vías:

La revisión en la nube requiere un plan de pago + el repo autorizado a Codex cloud; el /review local no requiere nada de eso.

Personaliza las reglas de revisión mediante la sección Review guidelines de AGENTS.md — p. ej. “toda ruta debe tener middleware de auth”, “sin PII en logs”. Codex entonces marca violaciones según tus estándares, no según los genéricos.

GitHub Actions / CI

La acción openai/codex-action ejecuta Codex en runners hospedados por GitHub, disparada por eventos del repo (PR abierto, CI fallido). Es la vía de CI/CD — distinta de las Automations locales de la app de escritorio.

Workflow mínimo:

# .github/workflows/codex-review.yml
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          prompt-file: .codex/prompts/review.md
          sandbox: workspace-write

💡 Dos vías de automatización, no las mezcles: GitHub Action (runner en la nube, eventos del repo, colaboración en equipo) vs Automation de la app de escritorio (tu máquina, calendarización por cron, tareas privadas). Empareja la vía con el lugar donde vive el trabajo.

Worktrees — aislamiento en paralelo

Un worktree da a cada hilo de Codex una copia aislada de los archivos del repo (compartiendo los metadatos de .git). Esto permite que varias tareas corran en paralelo sin sobreescribirse entre sí.

git worktree add ../feature-x -b feature-x
cd ../feature-x && codex    # isolated work on feature-x

• La misma rama no puede estar checked out en dos worktrees simultáneamente.
• Los worktrees + Handoff (app de escritorio) mueven trabajo entre primer plano/segundo plano — p. ej. lanzar un refactor largo en un worktree en segundo plano mientras sigues codeando al frente.
• Limpia los worktrees obsoletos periódicamente — cada uno mantiene una copia completa de archivos.

Automations

Las Automations de la app de escritorio ejecutan tareas programadas en segundo plano en tu máquina — “cada mañana, resume los commits de ayer”. Distintas de CI (runners de GitHub) — estas corren solo mientras tu máquina esté encendida. Combínalas con worktrees para mantener cada tarea programada aislada.

Computer Use

Computer Use le da a Codex “manos” — puede ver la pantalla, hacer clic en la UI, manejar un navegador. Alcance: automatización de GUI, pruebas de navegador, operación de apps de escritorio. El riesgo es alto — puede actuar sobre cualquier cosa visible; confínalo a workspace-write o a un contenedor, y vigila de cerca las primeras ejecuciones.

Integraciones (Slack / Linear / SDK)

Más allá de la CLI, Codex puede invocarse desde Slack y Linear, e integrarse en tu propio producto mediante el SDK. Úsalas para hacer de Codex un nodo en un flujo de trabajo existente y no un destino separado — p. ej. un mensaje de Slack dispara una tarea de Codex y el resultado se publica de vuelta en el canal.

Sistema de memoria

La memoria de Codex son dos sistemas, no uno:

⚠️ Dos errores comunes: (1) asumir que la memoria es en tiempo real — escribe después de que una sesión se inactiva, así que probarla de inmediato falla; (2) asumir que la memoria reemplaza a AGENTS.md — no lo hace. Las reglas “deben aplicarse siempre” van en AGENTS.md; nunca las apuestes a la memoria.

Chronicle es una memoria experimental, específica de Codex, alimentada por contenido de pantalla (solo Pro + macOS, excluye UE/Reino Unido/Suiza). Revisa sus implicaciones de privacidad antes de activarla.

Seguridad y límites de riesgo

El marco de decisión para “¿debería dejar que Codex toque esto?”:

⚠️ Innegociables: nunca --yolo en tu máquina real; nunca Full Access en Windows; trata el .codex/ de los repos clonados no confiables como no confiable (Codex lo hace por defecto — no lo sobreescribas).

Empresa y gobernanza

Operar Codex en toda una empresa (frente a una sola persona) requiere gobernanza:

• Ajustes gestionados — config de la organización desplegada por TI que los usuarios no pueden relajar.
• requirements.toml — allow_managed_hooks_only = true bloquea los hooks a solo gestionados.
• Políticas de confianza — controlan qué capas .codex/ de los proyectos se cargan.
• Listas de permitidos — restringen servidores MCP, herramientas y modelos a conjuntos aprobados.

Precios y modelos de terceros

La facturación es por suscripción de ChatGPT (Pro/Plus/Team/Enterprise — uso incluido) o por créditos de API (pago por token). Verifica el precio actual en el sitio de OpenAI — los números cambian; cítales con una fecha “a partir de”.

Modelos de terceros: enruta Codex a otros proveedores (p. ej. DeepSeek, modelos locales) mediante model_provider en config.toml. Útil para control de costos, residencia de datos o uso sin conexión.

Notas de Windows y solución de problemas

Windows: ejecútalo dentro de WSL2 (el nativo no es compatible). Los reportes de pérdida de datos de Full Access son específicos de Windows — quédate en workspace-write.

Fallos comunes:

Migración desde Claude Code

Tu modelo mental de Claude Code se transfiere en ~90%. Mapa de conceptos:

El agent loop, el hábito de “leer antes de actuar” y el de “da objetivos, no pasos” se transfieren literalmente.

Hoja de referencia de comandos y configuración

# install / auth
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login                      # ChatGPT OAuth
printenv OPENAI_API_KEY | codex login --with-api-key
codex doctor                     # self-check

# daily CLI
codex                            # interactive
codex exec "..."                 # non-interactive
codex -s workspace-write -a on-request

# slash commands (in-session)
/init  /model  /effort  /status  /clear  /compact  /diff  /review  /mcp  /skills  /agents  /memories

# config.toml essentials
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true

Mejores prácticas y preguntas frecuentes

Más allá de las frases hechas, lo que de verdad funciona:

• AGENTS.md como ciclo de retroalimentación — cada suposición errónea de Codex se convierte en una línea de él.
• Ajusta el effort a la tarea, no el modelo a la tarea — /effort es más barato y de mayor impacto.
• Una tarea por hilo — la putrefacción del contexto es real; no acumules trabajo.
• Compacta antes de que la calidad caiga, no después.
• Conteneriza --yolo — nunca en máquinas reales.

Preguntas frecuentes (breve):

• ¿Codex recuerda entre sesiones? Solo lo que está en AGENTS.md (fiable) y Memories (mejor esfuerzo).
• ¿Puedo usar un modelo que no sea de OpenAI? Sí, mediante model_provider en config.
• ¿Es seguro dejarlo editar archivos? En workspace-write + on-request, sí — se pausa antes de salir del proyecto.
• ¿CLI o app de escritorio? La CLI es el superconjunto; apréndela primero.

Glosario