Sortie structurée de Codex : des transferts JSON fiables sur VPS

Sortie structurée de Codex : des transferts JSON fiables sur VPS — Utilisez la sortie structurée de Codex avec exec, JSON Schema et des journaux séparés pour obtenir des résultats vérifiables sur VPS sans prendre le JSON pour une preuve.
15 nov. 20266 min de lecture
Share with

Un agent termine sa nuit de travail par un paragraphe enthousiaste. Le script suivant doit savoir s’il faut demander une revue, s’arrêter faute d’identifiants ou relancer un travail échoué. Repérer le mot « réussite » dans ce paragraphe ne constitue pas un contrat de transmission.

Nous utilisons la sortie structurée de Codex pour séparer conversation lisible et résultat exploitable par un programme. Ce guide concerne cette transmission, pas la persistance du processus : commencez par notre guide des tâches en arrière-plan pour ce dernier point.

Sortie structurée de Codex : les événements ne sont pas le résultat final

Le guide officiel du mode non interactif décrit trois mécanismes distincts :

MécanismeContenuNotre usage
--jsonFlux JSONL des événements d’exécutionDiagnostic et historique d’activité
--output-schemaContrat JSON Schema pour la réponse finaleChamps stables pour le traitement suivant
-oMessage final de l’agent écrit dans un fichierArtefact de transmission séparé

Un fichier JSONL contient plusieurs objets JSON, un par ligne. Ce n’est pas un document JSON final unique. Ne transmettez pas tout le journal d’événements à un programme qui attend un seul objet de résultat.

Séparer les événements, le résultat JSON final et la revue humaine

Le schéma contraint la forme de la réponse, pas sa véracité. Un agent peut produire du JSON valide tout en interprétant mal un échec de test. Gardez cette distinction dans toutes les décisions en aval.

Lancez votre premier agent en 3 minutes environ

Installez la CLI Office Claws, connectez votre compte Contabo et votre abonnement Codex : votre agent obtient son propre VPS et un bureau dans l'office.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

4,99 $/mois + votre propre VPS Contabo · les clés restent dans votre trousseau

Construire une petite transmission en lecture seule sur votre VPS

Utilisez une copie Git de confiance sur votre propre machine d’exécution, avec Codex déjà authentifié. Vérifiez codex exec --help pour votre version avant d’adopter l’exemple. Il s’agit d’une recette shell manuelle, pas d’un ordonnanceur intégré à Office Claws.

Créez le répertoire d’artefacts hors du dépôt afin que les journaux générés ne deviennent pas des entrées du projet. Le schéma garde un vocabulaire limité : résumé, constats et vérifications suggérées. Il ne demande pas à l’agent de certifier la sûreté de son propre travail.

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"

Le bac à sable en lecture seule limite les écritures ; il ne garantit pas la confidentialité. N’exécutez l’agent que sur du code accessible au compte authentifié, retirez les identifiants inutiles de l’environnement et examinez la configuration du projet et les outils connectés avant l’exécution. N’incluez jamais de fichiers d’authentification dans les artefacts.

Le fichier explicite de code de sortie permet au superviseur de distinguer un processus échoué d’un processus réussi contenant des constats. Si vous utilisez un délai maximal ou un gestionnaire de services, enregistrez également son état de terminaison. Un hébergement persistant ne garantit pas qu’un tour de Codex se soit achevé.

Valider l’artefact avant de demander une revue

Notre contrat en aval exige tous les points suivants, pas seulement un fichier analysable :

  1. Le code de sortie enregistré vaut zéro. Un code absent ou différent indique un échec ou une exécution incomplète.
  2. result.json existe, n’est pas vide et passe la validation contre le même schéma avec un validateur JSON Schema. Une simple vérification syntaxique du JSON ne suffit pas.
  3. Le commit de base enregistré correspond à la copie examinée. Le résultat du dépôt d’hier n’est pas une preuve pour la branche d’aujourd’hui.
  4. Une personne vérifie les chemins cités et exécute les tests pertinents indépendamment avant d’agir sur les constats.

Traitez les chaînes JSON comme du texte non fiable. N’interpolez jamais suggested_checks dans un shell et ne transformez pas un chemin fourni par le modèle en accès illimité aux fichiers. Si vous automatisez cette recette, utilisez une liste de commandes autorisées et des chemins bornés au dépôt.

ÉchecAction sûre suivante
Résultat absent ou schéma invalideConserver les journaux ; marquer la tentative comme incomplète
Erreur d’authentification ou limite d’usageAttendre une intervention ; éviter les relances en boucle rapide
JSON valide, constats faibles ou erronésDemander une revue ; le format ne garantit pas l’exactitude
Processus interrompu après des changements externesExaminer l’état réel avant toute relance

Cet exemple est en lecture seule, mais de futurs travaux avec écriture demandent davantage de prudence. Relancer un agent n’est pas idempotent : une tentative précédente peut déjà avoir modifié des fichiers ou invoqué un outil externe. Utilisez un nouveau répertoire par tentative, conservez les preuves précédentes et examinez la branche avant de reprendre. Notre guide de supervision couvre les autres signaux de santé.

Encadrer un agent toujours disponible par ce contrat

Office Claws héberge les agents Codex sur votre propre VPS Contabo et fournit une CLI ou une interface de bureau en pixel art. La validation du schéma et la gestion des artefacts ci-dessus sont vos scripts, pas l’affirmation qu’Office Claws embarque un moteur de workflows JSON. Conservation, contrôle d’accès, mises à jour et revue finale restent votre responsabilité.

Les coûts restent distincts : Office Claws commence à $4.99/mois pour le premier agent, le VPS est facturé séparément et votre forfait ChatGPT compatible fournit l’accès à Codex dans ses limites d’usage. Un serveur allumé en permanence n’offre pas une utilisation illimitée du modèle. Consultez le comparatif abonnement et API avant de dimensionner la file d’attente.

Notre recommandation : commencez par un rapport en lecture seule sur une machine. Gardez ensemble événements, JSON final, état de sortie et identité du commit. N’ajoutez des consommateurs parallèles qu’une fois ce contrat fiable ; le guide de plusieurs agents Codex explique comment séparer leurs espaces de travail.

Auteur

Office Claws Team

Nous construisons le futur de la gestion des agents IA chez Office Claws. Partage d'analyses sur l'infrastructure, la sécurité et l'expérience développeur.

Lancez votre premier agent en 3 minutes environ

Installez la CLI Office Claws, connectez votre compte Contabo et votre abonnement Codex : votre agent obtient son propre VPS et un bureau dans l'office.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

4,99 $/mois + votre propre VPS Contabo · les clés restent dans votre trousseau