Codex Exec: Automatiza las comprobaciones de despliegue

codex exec ejecuta Codex sin la interfaz de terminal interactiva. Pásale un prompt o canaliza datos, y luego guarda la respuesta para el siguiente paso de tu script. Esta guía crea un informe de despliegue con eventos JSONL, un resultado restringido por esquema y un código de salida basado en comprobaciones HTTP reales.

Probarás dos versiones de una pequeña API de cotizaciones: una funciona y la otra devuelve HTTP 200 en su endpoint de estado mientras que la ruta de cotización falla. El ejemplo completo incluye el recolector, el esquema del informe y el script de validación.

Ejecuta Codex sin la interfaz interactiva

Desde un repositorio Git de confianza, ejecuta:

codex exec --sandbox read-only \
  "Summarize this repository in three sentences. Do not change files."

Codex escribe el progreso en stderr y su respuesta final en stdout. Puedes redirigir esa respuesta a un archivo. La guía oficial no interactiva cubre este comportamiento y los patrones de automatización compatibles.

Para un informe de despliegue, proporcionaremos las observaciones en stdin. Un pequeño recolector en Python realiza las peticiones de red. Codex explica los resultados de las comprobaciones y una función separada comprueba el informe frente a esas observaciones.

Entiende los tres archivos de salida

Estos archivos tienen roles diferentes:

--json convierte stdout en un flujo de eventos. No convierte todo el flujo en un único objeto de informe. --output-schema describe la respuesta final y -o guarda esa respuesta por separado. Esta distinción evita un error común de automatización: intentar analizar todo el registro de eventos con una sola lectura JSON.

Prepara el ejemplo

Usa Python 3.10 o posterior y una CLI de Codex autenticada. Los archivos de Python no necesitan paquetes de terceros. Los comandos de shell a continuación están pensados para Bash o Zsh en macOS o Linux.

codex --version
codex login status
mkdir codex-deployment-check
cd codex-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done

Lee los archivos descargados antes de ejecutarlos. Inicia la demo y mantenla en ejecución:

python3 demo.py --port 8787

La aplicación tiene dos rutas GET. /healthz devuelve status: ok. /api/quote?quantity=3 calcula una cotización para tres artículos a 1.200 centavos cada uno. El resultado esperado es de $36,00 (3.600 centavos). El ejemplo usa centavos enteros para evitar redondeos en la aserción.

Abre otra terminal en la misma carpeta para los comandos restantes.

Recopila e inspecciona los resultados de las comprobaciones HTTP

python3 collect.py http://127.0.0.1:8787 > evidence.json

El recolector registra la URL, la hora de comprobación, el estado HTTP y si cada respuesta coincide con sus campos esperados. Realiza dos peticiones limitadas, rechaza redirecciones y limita cada respuesta a 64 KiB. Envía valores esperados y booleanos al modelo, sin copiar texto de respuesta arbitrario.

Para tu aplicación, reemplaza las rutas de la demo y los valores esperados tanto en collect.py como en gate.py. Elige una ruta que ejercite un comportamiento útil: calcular un precio, leer un registro inicial de la base de datos o recuperar un documento existente. Comprueba tanto el contenido de la respuesta como el código de estado.

El código de salida del recolector indica si recopiló datos. Una comprobación de aplicación fallida sigue produciendo un archivo con los resultados de las comprobaciones, por lo que Codex puede explicar el fallo. El script de validación final determina el resultado del trabajo.

Solicita un informe estructurado

Desde un repositorio Git de confianza que contenga los archivos, ejecuta:

codex exec --ignore-user-config --ephemeral \
  --sandbox read-only \
  --json \
  --output-schema report.schema.json \
  -o report.json \
  "Explain the evidence on stdin. Use no tools. Copy its verdict, list failed check names in failed_checks, and give a summary and next_step. Do not infer a root cause from HTTP status alone." \
  < evidence.json > events.jsonl 2> stderr.log

Si usas solo la nueva carpeta de descarga, añade --skip-git-repo-check. El wrapper completo lo hace en un directorio temporal creado para el informe. Usa esa bandera deliberadamente cuando no se necesite un repositorio.

--ignore-user-config omite el archivo de configuración principal de Codex del usuario mientras mantiene la autenticación normal. --ephemeral evita guardar el despliegue de la sesión. El shell sigue guardando los tres archivos de salida explícitos anteriores. --sandbox read-only limita los comandos generados por el modelo; las redirecciones del shell escriben los artefactos.

El esquema requiere verdict, failed_checks, summary y next_step, y no permite campos adicionales. El informe debe explicar qué establecen las comprobaciones suministradas. Una respuesta puede sugerir inspeccionar los registros de la aplicación después de un 503, pero el código de estado por sí solo no prueba un fallo en la base de datos.

Analiza el flujo y la respuesta final por separado

En nuestra prueba en vivo, Codex emitió estos tipos de eventos en orden:

thread.started
turn.started
item.completed
turn.completed

El elemento completado fue un mensaje del agente. Estas ejecuciones en particular no realizaron llamadas a herramientas. Otras tareas pueden producir más eventos, incluyendo ejecuciones de comandos, llamadas a herramientas y errores; no exijas que cada ejecución exitosa tenga exactamente cuatro líneas.

El wrapper lee cada evento y rechaza turn.failed o error. También requiere turn.completed, una salida de proceso exitosa y un informe final que se pueda analizar. Luego compara el veredicto del informe y los nombres de las comprobaciones fallidas con los resultados de las comprobaciones HTTP.

Un flujo que termina antes de tiempo es un trabajo incompleto. Un archivo de informe sobrante de una ejecución anterior también es inseguro de reutilizar. El wrapper crea un nuevo directorio de salida y se niega a sobrescribir una ejecución existente.

Ejecuta el flujo de trabajo completo

python3 run.py codex http://127.0.0.1:8787 runs/healthy

Este comando recopila nuevos datos, lanza Codex con un tiempo de espera de proceso de 180 segundos, guarda su salida y valida el informe. El wrapper sale con 0 solo cuando ambas comprobaciones de la aplicación pasan y el informe concuerda.

Para reproducir el fallo, inicia una segunda demo en otra terminal:

python3 demo.py --port 8788 --broken

Luego ejecuta el mismo flujo de trabajo contra esa instancia:

python3 run.py codex http://127.0.0.1:8788 runs/broken

La ruta de estado devuelve 200 y la ruta de cotización devuelve 503. Codex recibe esas observaciones y devuelve un informe de fallo. El wrapper sale con 1. El proceso de generación de informes puede completarse con éxito mientras que la comprobación de la aplicación falla; tu automatización debe usar el código de salida del wrapper para la decisión sobre la aplicación.

Resultados del ejemplo funcional

Ejecutamos ambos escenarios con la CLI de Codex 0.156.1 y Python 3.12.10 el 28 de septiembre de 2026. También comprobamos los comandos de Lizard CLI con la versión 4.0.8.

Ambas llamadas al modelo se completaron y produjeron un informe que coincidía con los resultados recopilados. El informe de la ejecución rota sugirió revisar los registros en la hora registrada. No afirmó que el endpoint de estado estableciera el estado completo de la aplicación.

Las pruebas de validación locales también rechazan un informe de éxito falso y datos incompletos. Ejecútalas sin una llamada al modelo:

python3 verify.py

Esta es una prueba HTTP sintética en una máquina local. No cubre tráfico de producción, DNS público, TLS, migraciones de bases de datos ni todas las rutas. Añade comprobaciones para las partes de tu propio despliegue que importen.

Añade el estado del servicio y los registros de Lizard

Para una aplicación en Lizard, confirma el objetivo antes de interpretar los fallos:

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

El comando de estado de Lizard muestra la vinculación de la carpeta local a un proyecto, proporcionando información del servicio legible por máquina y una instantánea limitada de los registros. La guía principal coincide con la versión instalada de la CLI. Úsala cuando necesites más comandos o banderas, y usa selectores explícitos de proyecto y servicio en la automatización.

Ejecuta el recolector HTTP adaptado contra la URL pública del servicio. Un contenedor marcado como en ejecución no prueba que una búsqueda de precios o una lectura de base de datos funcione. Compara la hora del fallo HTTP con los registros del servicio para acotar la siguiente investigación. Revisa y oculta secretos y datos personales en el contenido de los registros antes de enviarlo a un modelo.

Si necesitas desplegar primero, comienza con la guía de despliegue del agente de codificación. Para aplicaciones con dependencias de datos, el tutorial de Postgres MCP y el tutorial de Redis MCP explican el acceso con alcance para inspeccionar datos de prueba.

Usa el resultado en la automatización

Mantén tres resultados explícitos: la aplicación pasó, la aplicación falló y el trabajo de informe falló. Este wrapper usa 0, 1 y 2 respectivamente. Un tiempo de espera, un problema de autenticación de la CLI, un informe no válido o una contradicción en la salida produce el código 2.

Almacena los resultados de las comprobaciones junto al informe. Eso permite a un compañero de equipo verificar el resultado sin confiar en un resumen en prosa. Asigna rutas de salida distintas a las ejecuciones programadas, establece un período de retención y evita almacenar credenciales en los artefactos.

En tu propia máquina de confianza, codex exec puede reutilizar el inicio de sesión guardado de la CLI. Para GitHub Actions, sigue la guía oficial de la acción de Codex para la configuración de autenticación y permisos. Mantén las credenciales de la API fuera de los archivos del repositorio y evita exponerlas a pasos de compilación no confiables. Revisa esos requisitos específicos del runner antes de transferir un comando local a CI.

Usa nuevos datos para cada comprobación independiente. codex exec resume puede continuar una conversación, pero no es necesario para este informe de un solo uso. El modo efímero del ejemplo hace que cada ejecución sea independiente.

Resolución de problemas

Siguientes pasos

Usa este patrón para una comprobación de despliegue enfocada, luego añade aserciones para las dependencias reales de tu aplicación. Mantén las comprobaciones lo suficientemente pequeñas como para que un resultado fallido apunte a un siguiente paso útil.

Si tu equipo usa Claude Code, la guía headless de Claude Code muestra las mismas comprobaciones HTTP con su envoltura de resultados. Para ejecutar la aplicación en sí, usa Lizard CLI y añade el informe después de tu paso de despliegue.