Compaction

Chaque modèle dispose d’une fenêtre de contexte : le nombre maximal de tokens qu’il peut traiter. Lorsqu’une conversation approche de cette limite, OpenClaw compacte les messages les plus anciens dans un résumé afin que la discussion puisse continuer.

Fonctionnement

1. Les tours de conversation les plus anciens sont résumés dans une entrée compacte.
2. Le résumé est enregistré dans la transcription de la session.
3. Les messages récents sont conservés intacts.

OpenClaw conserve les appels d’outils de l’assistant avec leurs entrées toolResult correspondantes lorsqu’il choisit un point de séparation pour la Compaction. Si ce point se situe dans un bloc d’outil, OpenClaw déplace la limite afin de conserver la paire ensemble et de préserver la fin actuelle non résumée.

L’historique complet de la conversation reste sur le disque. La Compaction modifie uniquement ce que le modèle voit au tour suivant.

Compaction automatique

La Compaction automatique est activée par défaut. Elle s’exécute lorsque la session approche de la limite de contexte ou lorsque le modèle renvoie une erreur de dépassement du contexte (auquel cas OpenClaw compacte puis réessaie).

Vous verrez :

• embedded run auto-compaction start / complete dans les journaux normaux du Gateway.
• 🧹 Auto-compaction complete en mode détaillé.
• /status affichant 🧹 Compactions: <count>.

Compaction manuelle

Saisissez /compact dans n’importe quelle discussion pour forcer une Compaction. Ajoutez des instructions pour orienter le résumé :

/compact Concentrez-vous sur les décisions de conception de l’API

Lorsque agents.defaults.compaction.keepRecentTokens est défini (valeur par défaut : 20,000), la Compaction manuelle respecte ce point de coupure et conserve la fin récente dans le contexte reconstruit. Sans budget de conservation explicite, la Compaction manuelle se comporte comme un point de contrôle strict et se poursuit uniquement à partir du nouveau résumé.

Configuration

Configurez la Compaction sous agents.defaults.compaction dans votre fichier openclaw.json. Les paramètres les plus courants sont répertoriés ci-dessous ; pour consulter la référence complète, reportez-vous à l’étude approfondie de la gestion des sessions.

Utilisation d’un autre modèle

Par défaut, la Compaction utilise le modèle principal de l’agent. Définissez agents.defaults.compaction.model pour déléguer la génération du résumé à un modèle plus performant ou spécialisé. La valeur de remplacement accepte une chaîne provider/model-id ou un alias simple configuré sous agents.defaults.models :

{  "agents": {    "defaults": {      "compaction": {        "model": "openrouter/anthropic/claude-sonnet-4-6"      }    }  }}

Les alias simples configurés sont résolus vers leur fournisseur et leur modèle canoniques avant le début de la Compaction. Si une valeur simple correspond à la fois à un alias et à un ID de modèle littéral configuré, l’ID de modèle littéral est prioritaire. Une valeur simple sans correspondance reste un ID de modèle sur le fournisseur actif.

Cela fonctionne également avec les modèles locaux, par exemple un second modèle Ollama dédié à la génération de résumés :

{  "agents": {    "defaults": {      "compaction": {        "model": "ollama/llama3.1:8b"      }    }  }}

Lorsque ce paramètre n’est pas défini, la Compaction commence avec le modèle actif de la session. Si la génération du résumé échoue avec une erreur de fournisseur autorisant le recours à un modèle de repli, OpenClaw réessaie cette tentative de Compaction à l’aide de la chaîne de modèles de repli existante de la session. Le choix du modèle de repli est temporaire et n’est pas réenregistré dans l’état de la session. Une valeur de remplacement explicite pour agents.defaults.compaction.model reste exacte et n’hérite pas de la chaîne de repli de la session.

Conservation des identifiants

La génération du résumé de Compaction conserve les identifiants opaques par défaut (identifierPolicy: "strict"). Utilisez identifierPolicy: "off" pour désactiver ce comportement, ou identifierPolicy: "custom" avec identifierInstructions pour fournir des instructions personnalisées.

Limite en octets de la transcription active

Lorsque agents.defaults.compaction.maxActiveTranscriptBytes est défini, OpenClaw déclenche une Compaction locale normale avant une exécution si l’historique de la transcription atteint cette taille. Cela est utile pour les sessions de longue durée dans lesquelles la gestion du contexte côté fournisseur peut maintenir le contexte du modèle en bon état alors que l’historique persistant de la transcription continue de croître. Cette limite ne divise pas les octets bruts ; elle demande au pipeline normal de Compaction de créer un résumé sémantique.

Transcriptions successeures

Lorsque agents.defaults.compaction.truncateAfterCompaction est activé, OpenClaw ne réécrit pas la transcription existante sur place. Il crée une nouvelle transcription successeure active à partir du résumé de la Compaction, de l’état conservé et de la fin non résumée, puis enregistre les métadonnées du point de contrôle qui orientent les flux de branchement et de restauration vers cette version successeure compactée. Les transcriptions successeures suppriment également les tours utilisateur longs qui sont des doublons exacts et arrivent dans une courte fenêtre de nouvelle tentative, afin que les vagues de nouvelles tentatives des canaux ne soient pas reportées dans la prochaine transcription active après la Compaction.

OpenClaw n’écrit plus de copies .checkpoint.*.jsonl distinctes pour les nouvelles Compactions. Les fichiers de point de contrôle existants hérités peuvent encore être utilisés tant qu’ils sont référencés et sont supprimés par le nettoyage normal des sessions.

Notifications de Compaction

Par défaut, la Compaction s’exécute silencieusement. Définissez notifyUser pour afficher de brefs messages d’état au début et à la fin de la Compaction, et pour signaler un état dégradé lorsque les tentatives de vidage de la mémoire avant la Compaction sont épuisées, mais que la réponse se poursuit malgré tout :

{  agents: {    defaults: {      compaction: {        notifyUser: true,      },    },  },}

Vidage de la mémoire

Avant la Compaction, OpenClaw peut exécuter un tour de vidage silencieux de la mémoire afin d’enregistrer des notes persistantes sur le disque. Définissez agents.defaults.compaction.memoryFlush.model lorsque ce tour de maintenance doit utiliser un modèle local plutôt que le modèle actif de la conversation :

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

La valeur de remplacement du modèle de vidage de la mémoire est exacte et n’hérite pas de la chaîne de repli de la session active. Consultez Mémoire pour plus de détails et d’informations sur la configuration.

Fournisseurs de Compaction modulaires

Les Plugins peuvent enregistrer un fournisseur de Compaction personnalisé via registerCompactionProvider() dans l’API du Plugin. Lorsqu’un fournisseur est enregistré et configuré, OpenClaw lui délègue la génération du résumé au lieu d’utiliser le pipeline LLM intégré.

Pour utiliser un fournisseur enregistré, définissez son identifiant dans votre configuration :

{  "agents": {    "defaults": {      "compaction": {        "provider": "my-provider"      }    }  }}

La définition d’un provider force automatiquement mode: "safeguard". Les fournisseurs reçoivent les mêmes instructions de Compaction et la même politique de conservation des identifiants que le chemin intégré, et OpenClaw conserve toujours le contexte suffixe des tours récents et des tours séparés après la sortie du fournisseur.

Compaction et élagage

L’élagage de session est un complément plus léger qui réduit les sorties des outils sans les résumer.

Résolution des problèmes

Compactions trop fréquentes ? La fenêtre de contexte du modèle est peut-être petite, ou les sorties des outils sont peut-être volumineuses. Essayez d’activer l’élagage de session.

Le contexte semble obsolète après la Compaction ? Utilisez /compact Focus on <topic> pour orienter le résumé, ou activez le vidage de la mémoire afin que les notes soient conservées.

Besoin de repartir de zéro ? /new démarre une nouvelle session sans effectuer de Compaction.

Pour la configuration avancée (tokens réservés, conservation des identifiants, moteurs de contexte personnalisés, Compaction côté serveur OpenAI), consultez l’étude approfondie de la gestion des sessions.

Voir aussi

• Session : gestion et cycle de vie des sessions.
• Élagage de session : réduction des résultats d’outils.
• Contexte : création du contexte pour les tours de l’agent.
• Hooks : hooks du cycle de vie de la Compaction (before_compaction, after_compaction).