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

Les tours de conversation les plus anciens sont résumés dans une entrée compacte.
Le résumé est enregistré dans la transcription de la session.
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.

Les nouvelles configurations définissent par défaut agents.defaults.compaction.mode sur "safeguard" (garde-fous plus stricts, audits de la qualité des résumés). Définissez explicitement mode: "default" pour désactiver ce comportement.

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>.

Avant la Compaction, OpenClaw rappelle automatiquement à l’agent d’enregistrer les notes importantes dans les fichiers de mémoire. Cela évite la perte de contexte.

Schémas d’erreur de dépassement reconnus par OpenClaw

OpenClaw reconnaît des dizaines de chaînes d’erreur de dépassement propres aux fournisseurs (Anthropic, OpenAI, Bedrock, Gemini, Ollama, OpenRouter, entre autres). Exemples courants :

request_too_large
context length exceeded
input exceeds the maximum number of tokens
input token count exceeds the maximum number of input tokens (Bedrock)
input is too long for the model
ollama error: context length exceeded

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.

La limite en octets s’applique à l’historique actif de la transcription SQLite. Les anciens artefacts de point de contrôle JSONL ne constituent pas la cible active de la Compaction.

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.

Si le fournisseur échoue ou renvoie un résultat vide, OpenClaw revient à la génération de résumé LLM intégrée.

Compaction et élagage

	Compaction	Élagage
Fonction	Résume les conversations les plus anciennes	Supprime les anciens résultats d’outils
Enregistré ?	Oui (dans la transcription de la session)	Non (uniquement en mémoire, par requête)
Portée	Conversation entière	Résultats d’outils uniquement

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).

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Fonctionnement

Compaction automatique

Compaction manuelle

Configuration

Utilisation d’un autre modèle

Conservation des identifiants

Limite en octets de la transcription active

Transcriptions successeures

Notifications de Compaction

Vidage de la mémoire

Fournisseurs de Compaction modulaires

Compaction et élagage

Résolution des problèmes

Voir aussi

​Fonctionnement

​Compaction automatique

​Compaction manuelle

​Configuration

​Utilisation d’un autre modèle

​Conservation des identifiants

​Limite en octets de la transcription active

​Transcriptions successeures

​Notifications de Compaction

​Vidage de la mémoire

​Fournisseurs de Compaction modulaires

​Compaction et élagage

​Résolution des problèmes

​Voir aussi

Fonctionnement

Compaction automatique

Compaction manuelle

Configuration

Utilisation d’un autre modèle

Conservation des identifiants

Limite en octets de la transcription active

Transcriptions successeures

Notifications de Compaction

Vidage de la mémoire

Fournisseurs de Compaction modulaires

Compaction et élagage

Résolution des problèmes

Voir aussi