Un agente termina su trabajo nocturno con un párrafo optimista. El siguiente script necesita saber si debe solicitar una revisión, detenerse por falta de credenciales o reintentar un trabajo fallido. Buscar la palabra «éxito» en ese párrafo no es un contrato de entrega.
Usamos la salida estructurada de Codex para separar una conversación legible de un resultado procesable. Esta guía trata esa entrega, no la persistencia del proceso: para eso, empieza por nuestra guía de tareas en segundo plano.
Salida estructurada de Codex: los eventos no son el resultado final
La guía oficial del modo no interactivo documenta tres mecanismos distintos:
| Mecanismo | Contenido | Nuestro uso |
|---|---|---|
--json | Flujo JSONL de eventos de ejecución | Diagnóstico e historial de actividad |
--output-schema | Contrato JSON Schema para la respuesta final | Campos estables para el siguiente consumidor |
-o | Mensaje final del agente guardado en un archivo | Artefacto de entrega independiente |
Un archivo JSONL contiene muchos objetos JSON, uno por línea. No equivale a un único documento JSON final. No envíes todo el registro de eventos a un consumidor que espera un solo objeto de resultado.
El esquema limita la forma de la respuesta, no la veracidad del contenido. Un agente puede devolver JSON válido y aun así interpretar mal un fallo de pruebas. Mantén esa distinción en todas las decisiones posteriores.
Pon en marcha tu primer agente en unos 3 minutos
Instala la CLI de Office Claws, conecta tu cuenta de Contabo y tu suscripción de Codex, y tu agente tendrá su propio VPS y un escritorio en la oficina.
curl -fsSL https://officeclaws.com/downloads/install.sh | sh$4.99/mes + tu propio VPS de Contabo · las claves se quedan en tu llavero
Crear una pequeña entrega de solo lectura en tu VPS
Usa una copia Git de confianza en tu propio ejecutor, con Codex ya autenticado. Comprueba codex exec --help para tu versión antes de adoptar el ejemplo. Es una receta manual de shell, no un planificador integrado en Office Claws.
Crea el directorio de artefactos fuera del repositorio para que los registros generados no se conviertan en entradas del agente. El esquema usa un vocabulario pequeño: resumen, hallazgos y comprobaciones sugeridas. No pide al agente que certifique la seguridad de su propio trabajo.
cd ~/work/product-api
umask 077
RUN_DIR=$(mktemp -d "$HOME/codex-report.XXXXXX")
cat > "$RUN_DIR/schema.json" <<'JSON'
{
"type": "object",
"properties": {
"summary": { "type": "string" },
"findings": {
"type": "array",
"items": { "type": "string" }
},
"suggested_checks": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["summary", "findings", "suggested_checks"],
"additionalProperties": false
}
JSON
git rev-parse HEAD > "$RUN_DIR/base-commit.txt"
codex --version > "$RUN_DIR/codex-version.txt"
if codex exec --sandbox read-only --json \
--output-schema "$RUN_DIR/schema.json" \
-o "$RUN_DIR/result.json" \
"Inspect the repository for risky retry logic. Do not edit files. Report findings with file paths; suggest checks without running them." \
> "$RUN_DIR/events.jsonl" 2> "$RUN_DIR/stderr.log"; then
printf '0\n' > "$RUN_DIR/exit-code.txt"
else
rc=$?
printf '%s\n' "$rc" > "$RUN_DIR/exit-code.txt"
fi
printf 'Artifacts: %s\n' "$RUN_DIR"El entorno aislado de solo lectura limita las escrituras; no es una barrera de confidencialidad. Ejecuta el trabajo solo sobre código al que la cuenta autenticada pueda acceder, elimina credenciales innecesarias del entorno y revisa la configuración del proyecto y las herramientas conectadas antes de empezar. Nunca incluyas archivos de autenticación entre los artefactos.
El archivo explícito con el código de salida importa porque un supervisor debe distinguir un proceso fallido de uno correcto con hallazgos. Si usas un límite de tiempo o un gestor de servicios, registra también su estado de terminación. El alojamiento persistente no garantiza que Codex termine un turno.
Validar el artefacto antes de solicitar revisión
Nuestro contrato posterior exige todo lo siguiente, no solo un archivo que pueda analizarse:
- El código de salida registrado es cero. Si falta o no es cero, la ejecución falló o quedó incompleta.
result.jsonexiste, no está vacío y supera la validación contra el mismo esquema con un validador JSON Schema. Comprobar solo la sintaxis JSON no basta.- El commit base guardado coincide con la copia que se revisa. Un resultado de ayer no demuestra nada sobre la rama de hoy.
- Una persona revisa las rutas citadas y ejecuta las pruebas relevantes de forma independiente antes de actuar sobre los hallazgos.
Trata las cadenas JSON como texto no fiable. Nunca interpoles suggested_checks en una shell ni conviertas una ruta propuesta por el modelo en una lectura de archivos sin restricciones. Si automatizas esta receta, usa una lista de comandos permitidos y rutas limitadas al repositorio.
| Fallo | Siguiente acción segura |
|---|---|
| Resultado ausente o esquema inválido | Conservar registros; marcar el intento como incompleto |
| Error de autenticación o límite de uso | Esperar intervención; evitar reintentos continuos |
| JSON válido, hallazgos débiles o incorrectos | Solicitar revisión; formato no significa corrección |
| Proceso interrumpido tras cambios externos | Inspeccionar el estado real antes de reintentar |
Aunque este ejemplo es de solo lectura, los futuros trabajos con escritura exigen más cuidado. Reintentar un agente no es una operación idempotente: el intento anterior podría haber modificado archivos o invocado una herramienta externa. Usa un directorio nuevo por intento, conserva las pruebas anteriores e inspecciona la rama antes de continuar. Nuestra guía de supervisión cubre otras señales de salud.
Aplicar el contrato a un agente siempre disponible
Office Claws aloja los agentes Codex en tu propio VPS de Contabo y ofrece una CLI o una interfaz de escritorio de arte pixelado. La validación y el manejo de artefactos anteriores son tus scripts, no una promesa de que Office Claws incluya un motor de flujos JSON. La retención, los controles de acceso, las actualizaciones y la revisión final siguen siendo tuyos.
Los costes siguen separados: Office Claws parte de $4.99/mes para el primer agente, el VPS se paga aparte y tu plan ChatGPT compatible proporciona acceso a Codex dentro de sus límites de uso. Un servidor siempre encendido no implica uso ilimitado del modelo. Consulta suscripción frente a API antes de dimensionar la cola.
Recomendamos empezar con un informe de solo lectura en un ejecutor. Mantén juntos los eventos, el JSON final, el estado de salida y la identidad del commit. Añade consumidores paralelos solo cuando el contrato de una ejecución sea fiable; la guía de varios agentes Codex explica cómo separar sus espacios de trabajo.