Élagage des sessions

L’élagage de session retire les anciens résultats d’outils du contexte avant chaque appel au LLM. Il réduit l’encombrement du contexte dû à l’accumulation des sorties d’outils (résultats d’exécution, lectures de fichiers, résultats de recherche) sans réécrire le texte normal de la conversation.

Pourquoi est-ce important ?

Les sessions longues accumulent des sorties d’outils qui gonflent la fenêtre de contexte. Cela augmente le coût et peut imposer une Compaction plus tôt que nécessaire.

L’élagage est particulièrement utile pour la mise en cache des prompts d’Anthropic. Après l’expiration de la durée de vie du cache, la requête suivante remet en cache l’intégralité du prompt. L’élagage réduit la taille des écritures dans le cache, ce qui diminue directement le coût.

Fonctionnement

L’élagage s’exécute en mode cache-ttl et dépend à la fois d’une vérification temporelle et d’une vérification de la taille du contexte :

1. Attendre l’expiration de la durée de vie du cache (5 minutes par défaut lorsqu’elle est définie manuellement ; consultez Valeurs par défaut intelligentes pour la valeur automatique par défaut d’Anthropic). Avant cette expiration, l’élagage est entièrement ignoré afin de préserver la réutilisation du cache de prompts pour les tours rapprochés.
2. Une fois la durée de vie expirée, estimer la taille totale du contexte par rapport à la fenêtre de contexte du modèle. Si le rapport est inférieur à softTrimRatio (0,3 par défaut), ignorer l’élagage et laisser le compteur de durée de vie continuer à s’écouler.
3. Raccourcir progressivement les résultats d’outils surdimensionnés au-delà du rapport : conserver le début et la fin (1 500 caractères chacun par défaut, avec une limite totale de 4 000 caractères) et insérer ... entre les deux.
4. Si le rapport reste supérieur ou égal à hardClearRatio (0,5 par défaut) et qu’il reste au moins minPrunableToolChars (50 000 par défaut) de contenu d’outils pouvant être élagué, effacer intégralement ces résultats : remplacer leur contenu par un texte de substitution (par défaut [Ancien contenu du résultat d’outil effacé]).
5. Réinitialiser le compteur de durée de vie uniquement lorsque l’élagage a réellement modifié le contexte, afin que les requêtes suivantes réutilisent le nouveau cache.

Deux règles de sécurité s’appliquent quels que soient les seuils : les keepLastAssistants tours d’assistant les plus récents (3 par défaut) ne sont jamais élagués, et rien de ce qui précède le premier message utilisateur de la session n’est jamais élagué (ce qui protège les lectures d’initialisation telles que SOUL.md/USER.md).

Seuls les messages toolResult sont concernés ; le texte normal de la conversation reste intact. Utilisez agents.defaults.contextPruning.tools.{allow,deny} pour définir les noms d’outils pouvant être élagués.

Nettoyage des anciennes images

OpenClaw construit également une vue de relecture idempotente distincte pour les sessions dont l’historique conserve des blocs d’images bruts ou des marqueurs de médias d’hydratation des prompts.

• Elle conserve les 3 derniers tours terminés à l’identique, octet par octet, afin que les préfixes du cache de prompts restent stables pour les échanges de suivi récents. Ce nombre inclut tous les tours terminés, et pas seulement ceux contenant des images ; les tours composés uniquement de texte sont donc également comptabilisés dans cette fenêtre.
• Dans la vue de relecture, les anciens blocs d’images déjà traités issus de l’historique user ou toolResult sont remplacés par [données d’image supprimées - déjà traitées par le modèle].
• Les anciennes références textuelles à des médias, telles que [média joint : ...], [Image : source : ...] et media://inbound/..., sont remplacées par [référence au média supprimée - déjà traitée par le modèle]. Les marqueurs de pièces jointes du tour en cours restent intacts afin que les modèles de vision puissent toujours hydrater les nouvelles images.
• La transcription brute de la session n’est pas réécrite ; les visionneuses d’historique peuvent donc toujours afficher les entrées de messages d’origine et leurs images.
• Ce mécanisme est distinct de l’élagage normal selon la durée de vie du cache décrit ci-dessus. Il empêche les charges utiles d’images répétées ou les références obsolètes à des médias d’invalider les caches de prompts lors des tours ultérieurs.

Valeurs par défaut intelligentes

Le Plugin Anthropic intégré configure automatiquement l’élagage et la cadence du Heartbeat la première fois qu’il résout un profil d’authentification Anthropic (ou Claude CLI), mais uniquement pour les champs que vous n’avez pas déjà définis explicitement :

Si vous définissez vous-même agents.defaults.contextPruning.mode ou agents.defaults.heartbeat.every, OpenClaw ne les remplace pas. Cette valeur automatique par défaut s’applique uniquement à l’authentification de la famille Anthropic ; pour les autres fournisseurs, l’élagage est défini sur off, sauf si vous le configurez.

Activation ou désactivation

L’élagage est désactivé par défaut pour les fournisseurs autres qu’Anthropic. Pour l’activer :

{  agents: {    defaults: {      contextPruning: { mode: "cache-ttl", ttl: "5m" },    },  },}

Pour le désactiver : définissez mode: "off".

Élagage et Compaction

Ces mécanismes sont complémentaires : l’élagage limite le volume des sorties d’outils entre les cycles de Compaction.

Pour aller plus loin

• Compaction : réduction du contexte fondée sur la synthèse
• Configuration du Gateway : tous les paramètres de configuration de l’élagage (contextPruning.*)

Pages connexes

• Gestion des sessions
• Outils de session
• Moteur de contexte