Ensembles de trajectoires

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

Utilisez-la lorsque vous devez répondre à des questions comme :

• Quels prompt, prompt système et outils ont été envoyés au modèle ?
• Quels messages de transcript et appels d’outils ont mené à cette réponse ?
• L’exécution a-t-elle expiré, été abandonnée, compactée ou rencontré une erreur de fournisseur ?
• Quels modèle, plugins, Skills 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 déposez un rapport de support général pour un problème Gateway en direct, commencez par /diagnostics. Diagnostics collecte le bundle Gateway assaini et, pour les sessions de harnais OpenAI Codex, peut aussi envoyer des retours Codex aux serveurs OpenAI après approbation. Utilisez /export-trajectory lorsque vous avez spécifiquement besoin de la chronologie détaillée par session des prompts, outils et transcripts.

# Démarrage rapide

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 dans .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 passe donc par l’approbation exec à chaque fois. Approuvez l’export une seule fois lorsque vous avez l’intention de créer le bundle ; n’utilisez pas allow-all. Dans les discussions de groupe, OpenClaw envoie la demande d’approbation et le résultat d’export au propriétaire en privé au lieu de publier les détails de trajectoire dans le salon partagé.

Pour l’inspection locale ou les workflows de support, vous pouvez aussi exécuter directement le chemin de commande approuvé :

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

# Accès

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

# Ce qui est enregistré

La capture de trajectoire est activée par défaut pour les exécutions d’agents 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/le détail de l’échec, la position dans la chaîne et si le fallback a avancé, réussi ou épuisé la chaîne
• model.completed
• trace.artifacts
• session.ended

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

• messages utilisateur
• messages assistant
• appels d’outils
• résultats d’outils
• compactages
• changements de modèle
• libellés 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 du bundle

Un bundle exporté peut contenir :

Fichier	Contenu
manifest.json	Schéma du bundle, fichiers sources, nombres d’événements et liste des fichiers générés
events.jsonl	Chronologie ordonnée de l’exécution et du transcript
session-branch.json	Branche de transcript active expurgée et en-tête de session
metadata.json	Version d’OpenClaw, OS/exécution, modèle, instantané de config, plugins, Skills et métadonnées de prompt
artifacts.json	État final, erreurs, utilisation, cache de prompt, nombre de compactages, texte de l’assistant et métadonnées d’outils
prompts.json	Prompts soumis et détails sélectionnés de construction de prompt
system-prompt.txt	Dernier prompt système compilé, lorsqu’il est capturé
tools.json	Définitions d’outils envoyées au modèle, lorsqu’elles sont capturées

manifest.json liste les fichiers présents dans ce bundle. 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 aussi un fichier pointeur au mieux à côté de la session :

<session>.trajectory-path.json

Définissez OPENCLAW_TRAJECTORY_DIR pour stocker les sidecars 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 des sessions supprime les sidecars de trajectoire lorsque leur entrée de session propriétaire est élaguée, plafonnée ou évincée par le budget disque des sessions. Les fichiers d’exécution situés hors du répertoire des sessions ne sont supprimés que lorsque la cible du pointeur prouve encore 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 d’exécution. /export-trajectory peut toujours exporter la branche de transcript, mais les fichiers propres à l’exécution, tels que le contexte compilé, les artefacts du fournisseur et les métadonnées de prompt, peuvent manquer.

# Confidentialité et limites

Les bundles de trajectoire sont conçus pour le support et le débogage, pas pour une publication publique. OpenClaw expurge les valeurs sensibles avant d’écrire les fichiers d’export :

• identifiants et champs de charge utile connus comme ressemblant à des secrets
• données d’image
• chemins d’état locaux
• chemins d’espace de travail, remplacés par $WORKSPACE_DIR
• chemins du répertoire personnel, lorsqu’ils sont détectés

L’exporteur limite aussi la taille des entrées :

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

Relisez les bundles avant de les partager en dehors de votre équipe. L’expurgation est faite au mieux et ne peut pas connaître chaque secret propre à une application.

# Dépannage

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

• confirmez qu’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/... ni ~/...
• gardez l’export dans .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’export. Démarrez une nouvelle session ou exportez une reproduction plus petite.

# Associés

• Diffs
• Gestion des sessions
• Outil exec