Lots de trajectoires

La capture de trajectoire est l’enregistreur de vol par session de OpenClaw. Il enregistre une chronologie structurée pour chaque exécution d’agent, puis /export-trajectory empaquette la session actuelle dans un lot de support révisé.

Utilisez-le lorsque vous devez répondre à des questions telles que :

Quels prompt, système de prompt et outils ont été envoyés au modèle ?
Quels messages de transcription et quels appels d’outils ont conduit à cette réponse ?
L’exécution a-t-elle expiré, a-t-elle été abandonnée, compactée ou a-t-elle rencontré une erreur de fournisseur ?
Quel modèle, quels plugins, compétences et paramètres d’exécution étaient actifs ?
Quelles métadonnées d’utilisation et de cache de prompt le fournisseur a-t-il renvoyées ?

Si vous soumettez un rapport de support général pour un problème en direct sur la Gateway, commencez par /diagnostics. Diagnostics collecte le lot nettoyé de la Gateway et, pour les sessions du harnais OpenAI Codex, peut également envoyer des commentaires Codex aux serveurs OpenAI après approbation. Utilisez /export-trajectory lorsque vous avez spécifiquement besoin de la chronologique détaillée par session des invites, des outils et des transcriptions.

Quick start

Envoyez ceci dans la session active :

/export-trajectory

Alias :

/trajectory

OpenClaw écrit le bundle sous l’espace de travail :

.openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/

Vous pouvez choisir un nom de répertoire de sortie relatif :

/export-trajectory bug-1234

Le chemin personnalisé est résolu à l’intérieur de .openclaw/trajectory-exports/. Les chemins absolus et les chemins ~ sont rejetés.

Les bundles de trajectoire peuvent contenir des prompts, des messages de modèle, des schémas d’outils, des résultats d’outils, des événements d’exécution et des chemins locaux. La commande slash de chat s’exécute donc via l’approbation d’exécution à chaque fois. Approuvez l’exportation une fois lorsque vous avez l’intention de créer le bundle ; n’utilisez pas autoriser-tout (allow-all). Dans les chats de groupe, OpenClaw envoie la demande d’approbation et le résultat de l’exportation au propriétaire de manière privée au lieu de publier les détails de la trajectoire dans la salle partagée.

Pour une inspection locale ou des workflows de support, vous pouvez également exécuter directement le chemin de commande approuvé :

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .

Accès

L’exportation de trajectoire est une commande de propriétaire. L’expéditeur doit réussir les vérifications d’autorisation de commande normales et les vérifications de propriétaire pour le channel.

Ce qui est enregistré

La capture de trajectoire est activée par défaut pour les exécutions d’agent OpenClaw.

Les événements d’exécution incluent :

session.started
trace.metadata
context.compiled
prompt.submitted
model.fallback_step, y compris le modèle source, le modèle suivant, la raison/détail de l’échec, la position dans la chaîne, et si le basculement a avancé, réussi ou épuisé la chaîne
model.completed
trace.artifacts
session.ended

Les événements de transcription sont également reconstruits à partir de la branche de session active :

messages utilisateur
messages de l’assistant
appels de tool
résultats des tools
compactages
changements de model
étiquettes et entrées de session personnalisées

Les événements sont écrits en JSON Lines avec ce marqueur de schéma :

{
  "traceSchema": "openclaw-trajectory",
  "schemaVersion": 1
}

Fichiers de bundle

Un bundle exporté peut contenir :

Fichier	Contenu
`manifest.json`	Schéma du bundle, fichiers source, comptes d’événements et liste des fichiers générés
`events.jsonl`	Chronologie d’exécution et de transcription ordonnée
`session-branch.json`	Branche de transcription active révisée et en-tête de session
`metadata.json`	Version d’OpenClaw, système d’exploitation/exécution, model, instantané de configuration, plugins, compétences et métadonnées de prompt
`artifacts.json`	Statut final, erreurs, utilisation, cache de prompt, nombre de compactages, texte de l’assistant et métadonnées des tools
`prompts.json`	Prompts soumis et détails sélectionnés de la construction de prompt
`system-prompt.txt`	Dernier prompt système compilé, lors de la capture
`tools.json`	Définitions des tools envoyées au model, lors de la capture

manifest.json répertorie les fichiers présents dans ce lot. Certains fichiers sont omis lorsque la session n’a pas capturé les données d’exécution correspondantes.

Emplacement de capture

Par défaut, les événements de trajectoire d’exécution sont écrits à côté du fichier de session :

<session>.trajectory.jsonl

OpenClaw écrit également un fichier pointeur de meilleur effort à côté de la session :

<session>.trajectory-path.json

Définissez OPENCLAW_TRAJECTORY_DIR pour stocker les fichiers annexes de trajectoire d’exécution dans un répertoire dédié :

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

Lorsque cette variable est définie, OpenClaw écrit un fichier JSONL par identifiant de session dans ce répertoire.

La maintenance de session supprime les sidecars de trajectoire lorsque leur entrée de session propriétaire est élaguée, plafonnée ou évictée par le budget disque des sessions. Les fichiers d’exécution en dehors du répertoire des sessions ne sont supprimés que lorsque la cible du pointeur prouve toujours qu’elle appartient à cette session.

Désactiver la capture

Définissez OPENCLAW_TRAJECTORY=0 avant de démarrer OpenClaw :

export OPENCLAW_TRAJECTORY=0

Cela désactive la capture de trajectoire lors de l’exécution. /export-trajectory peut toujours exporter la branche de transcription, mais les fichiers d’exécution uniquement, tels que le contexte compilé, les artefacts du provider et les métadonnées de prompt, peuvent manquer.

Ajuster le délai de vidage (flush timeout)

OpenClaw vide les sidecars de trajectoire d’exécution lors du nettoyage de l’agent. Le délai d’attente dep nettoyage par défaut est de 10 000 ms. Sur des disques lents ou des magasins volumineux, définissez OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS avant de démarrer OpenClaw :

export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000

Cela contrôle le moment où OpenClaw consigne un délai d’attente pi-trajectory-flush et continue. Cela ne modifie pas les limites de taille de la trajectoire. Pour ajuster toutes les étapes de nettoyage de l’agent qui ne transmettent pas de délai d’attente explicite, définissez OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS.

Confidentialité et limites

Les bundles de trajectoires sont conçus pour le support et le débogage, et non pour la publication publique. OpenClaw rédige les valeurs sensibles avant d’écrire les fichiers d’exportation :

les identifiants et les champs de payload connus comme étant des secrets
les données d’image
les chemins d’état locaux
les chemins de l’espace de travail, remplacés par $WORKSPACE_DIR
les chemins du répertoire personnel, lorsqu’ils sont détectés

L’exportateur limite également la taille de l’entrée :

fichiers sidecar d’exécution : la capture en direct s’arrête à 10 MiB et enregistre un événement de troncature lorsque de l’espace reste ; l’exportation accepte les sidecars d’exécution existants jusqu’à 50 MiB
fichiers de session : 50 MiB
événements d’exécution : 200 000
total des événements exportés : 250 000
les lignes d’événements d’exécution individuelles sont tronquées au-delà de 256 KiB

Révisez les bundles avant de les partager en dehors de votre équipe. La rédaction est un meilleur effort et ne peut pas connaître chaque secret spécifique à l’application.

Dépannage

Si l’exportation ne contient aucun événement d’exécution :

confirmez que OpenClaw a été démarré sans OPENCLAW_TRAJECTORY=0
vérifiez si OPENCLAW_TRAJECTORY_DIR pointe vers un répertoire accessible en écriture
exécutez un autre message dans la session, puis exportez à nouveau
inspectez manifest.json pour runtimeEventCount

Si la commande rejette le chemin de sortie :

utilisez un nom relatif comme bug-1234
ne transmettez pas /tmp/... ou ~/...
gardez l’exportation à l’intérieur de .openclaw/trajectory-exports/

Si l’export échoue avec une erreur de taille, la session ou le sidecar a dépassé les limites de sécurité d’exportation. Commencez une nouvelle session ou exportez une reproduction plus petite.