​

Gestion des sessions et compaction (analyse détaillée)

• Routage des sessions (comment les messages entrants sont mappés à une sessionKey)
• Magasin de sessions (sessions.json) et ce qu’il suit
• Persistance des transcriptions (*.jsonl) et leur structure
• Hygiène des transcriptions (corrections spécifiques aux providers avant les exécutions)
• Limites de contexte (fenêtre de contexte vs tokens suivis)
• Compaction (compaction manuelle + automatique) et où raccorder le travail pré-compaction
• Maintenance silencieuse (par ex. écritures mémoire qui ne doivent pas produire de sortie visible par l’utilisateur)

• /concepts/session
• /concepts/compaction
• /concepts/memory
• /concepts/memory-search
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Source de vérité : la Gateway

• Les interfaces utilisateur (application macOS, interface web Control UI, TUI) doivent interroger la Gateway pour les listes de sessions et les nombres de tokens.
• En mode distant, les fichiers de session se trouvent sur l’hôte distant ; « vérifier vos fichiers locaux sur votre Mac » ne reflète pas ce que la Gateway utilise.

​

Deux couches de persistance

1. Magasin de sessions (sessions.json)
   • Map clé/valeur : sessionKey -> SessionEntry
   • Petite, mutable, sûre à modifier (ou à supprimer des entrées)
   • Suit les métadonnées de session (ID de session courant, dernière activité, bascules, compteurs de tokens, etc.)
2. Transcription (<sessionId>.jsonl)
   • Transcription en ajout seul avec structure en arbre (les entrées ont id + parentId)
   • Stocke la conversation réelle + les appels d’outils + les résumés de compaction
   • Utilisée pour reconstruire le contexte du modèle pour les tours futurs

​

Emplacements sur disque

• Magasin : ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcriptions : ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Sessions de sujets Telegram : .../<sessionId>-topic-<threadId>.jsonl

​

Maintenance du magasin et contrôles disque

• mode : warn (par défaut) ou enforce
• pruneAfter : seuil d’âge des entrées obsolètes (par défaut 30d)
• maxEntries : limite du nombre d’entrées dans sessions.json (par défaut 500)
• rotateBytes : effectue une rotation de sessions.json lorsqu’il est surdimensionné (par défaut 10mb)
• resetArchiveRetention : rétention des archives de transcription *.reset.<timestamp> (par défaut : identique à pruneAfter ; false désactive le nettoyage)
• maxDiskBytes : budget facultatif du répertoire des sessions
• highWaterBytes : cible facultative après nettoyage (par défaut 80% de maxDiskBytes)

1. Supprimer d’abord les artefacts de transcription archivés ou orphelins les plus anciens.
2. Si l’usage reste supérieur à la cible, évincer les entrées de session les plus anciennes et leurs fichiers de transcription.
3. Continuer jusqu’à ce que l’usage soit inférieur ou égal à highWaterBytes.

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Sessions cron et journaux d’exécution

• cron.sessionRetention (par défaut 24h) élague les anciennes sessions d’exécution cron isolées du magasin de sessions (false désactive).
• cron.runLog.maxBytes + cron.runLog.keepLines élaguent les fichiers ~/.openclaw/cron/runs/<jobId>.jsonl (par défaut : 2_000_000 octets et 2000 lignes).

​

Clés de session (sessionKey)

• Chat principal/direct (par agent) : agent:<agentId>:<mainKey> (par défaut main)
• Groupe : agent:<agentId>:<channel>:group:<id>
• Salon/canal (Discord/Slack) : agent:<agentId>:<channel>:channel:<id> ou ...:room:<id>
• Cron : cron:<job.id>
• Webhook : hook:<uuid> (sauf remplacement)

​

Identifiants de session (sessionId)

• Réinitialisation (/new, /reset) crée un nouveau sessionId pour cette sessionKey.
• Réinitialisation quotidienne (par défaut à 4h00 heure locale sur l’hôte gateway) crée un nouveau sessionId au prochain message après la frontière de réinitialisation.
• Expiration d’inactivité (session.reset.idleMinutes ou l’ancien session.idleMinutes) crée un nouveau sessionId lorsqu’un message arrive après la fenêtre d’inactivité. Lorsque quotidien + inactivité sont tous deux configurés, le premier qui expire l’emporte.
• Garde de fork parent de fil (session.parentForkMaxTokens, par défaut 100000) ignore le fork de la transcription parent lorsque la session parente est déjà trop volumineuse ; le nouveau fil démarre à neuf. Définissez 0 pour désactiver.

​

Schéma du magasin de sessions (sessions.json)

• sessionId : identifiant de transcription courant (le nom de fichier est dérivé de celui-ci sauf si sessionFile est défini)
• updatedAt : horodatage de la dernière activité
• sessionFile : remplacement facultatif explicite du chemin de transcription
• chatType : direct | group | room (aide les interfaces utilisateur et la politique d’envoi)
• provider, subject, room, space, displayName : métadonnées pour l’étiquetage des groupes/canaux
• Bascules :
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (remplacement par session)
• Sélection de modèle :
  • providerOverride, modelOverride, authProfileOverride
• Compteurs de tokens (au mieux / dépendants du provider) :
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount : nombre de fois où l’auto-compaction s’est terminée pour cette clé de session
• memoryFlushAt : horodatage du dernier vidage mémoire pré-compaction
• memoryFlushCompactionCount : nombre de compactions au moment du dernier vidage

​

Structure des transcriptions (*.jsonl)

• Première ligne : en-tête de session (type: "session", inclut id, cwd, timestamp, parentSession facultatif)
• Ensuite : entrées de session avec id + parentId (arbre)

• message : messages utilisateur/assistant/toolResult
• custom_message : messages injectés par extension qui entrent dans le contexte du modèle (peuvent être masqués dans l’UI)
• custom : état d’extension qui n’entre pas dans le contexte du modèle
• compaction : résumé de compaction conservé avec firstKeptEntryId et tokensBefore
• branch_summary : résumé conservé lors de la navigation dans une branche de l’arbre

​

Fenêtres de contexte vs tokens suivis

1. Fenêtre de contexte du modèle : limite stricte par modèle (tokens visibles par le modèle)
2. Compteurs du magasin de sessions : statistiques glissantes écrites dans sessions.json (utilisées pour /status et les tableaux de bord)

• La fenêtre de contexte provient du catalogue de modèles (et peut être remplacée via la configuration).
• contextTokens dans le magasin est une valeur d’estimation/de rapport à l’exécution ; ne la traitez pas comme une garantie stricte.

​

Compaction : ce que c’est

• Le résumé de compaction
• Les messages après firstKeptEntryId

​

Frontières de blocs de compaction et appariement des outils

• Si le découpage par part de tokens tombe entre un appel d’outil et son résultat, OpenClaw déplace la frontière jusqu’au message d’appel d’outil de l’assistant au lieu de séparer la paire.
• Si un bloc de résultat d’outil final ferait autrement dépasser le bloc de l’objectif, OpenClaw préserve ce bloc d’outil en attente et conserve intacte la queue non résumée.
• Les blocs d’appels d’outils abandonnés/en erreur ne maintiennent pas une séparation en attente ouverte.

​

Quand l’auto-compaction se produit (runtime Pi)

1. Récupération après dépassement : le modèle renvoie une erreur de dépassement de contexte (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded, et autres variantes similaires selon le provider) → compacter → réessayer.
2. Maintenance par seuil : après un tour réussi, lorsque :

• contextWindow est la fenêtre de contexte du modèle
• reserveTokens est la marge réservée pour les prompts + la prochaine sortie du modèle

​

Paramètres de compaction (reserveTokens, keepRecentTokens)

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

• Si compaction.reserveTokens < reserveTokensFloor, OpenClaw l’augmente.
• Le plancher par défaut est de 20000 tokens.
• Définissez agents.defaults.compaction.reserveTokensFloor: 0 pour désactiver ce plancher.
• Si la valeur est déjà plus élevée, OpenClaw n’y touche pas.

​

Surfaces visibles par l’utilisateur

• /status (dans n’importe quelle session de chat)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Mode verbeux : 🧹 Auto-compaction complete + nombre de compactions

​

Maintenance silencieuse (NO_REPLY)

• L’assistant commence sa sortie avec le jeton silencieux exact NO_REPLY / no_reply pour indiquer « ne pas livrer de réponse à l’utilisateur ».
• OpenClaw le retire/le supprime dans la couche de livraison.
• La suppression du jeton silencieux exact est insensible à la casse, donc NO_REPLY et no_reply comptent tous deux lorsque la charge utile entière n’est constituée que du jeton silencieux.
• Cela est réservé aux véritables tours en arrière-plan/sans livraison ; ce n’est pas un raccourci pour les requêtes utilisateur ordinaires demandant une action.

​

« Vidage mémoire » pré-compaction (implémenté)

1. Surveiller l’utilisation du contexte de la session.
2. Lorsqu’elle franchit un « seuil doux » (en dessous du seuil de compaction de Pi), exécuter une directive silencieuse « écrire la mémoire maintenant » vers l’agent.
3. Utiliser le jeton silencieux exact NO_REPLY / no_reply afin que l’utilisateur ne voie rien.

• enabled (par défaut : true)
• softThresholdTokens (par défaut : 4000)
• prompt (message utilisateur pour le tour de vidage)
• systemPrompt (prompt système supplémentaire ajouté pour le tour de vidage)

• Le prompt / systemPrompt par défaut inclut un indice NO_REPLY pour supprimer la livraison.
• Le vidage s’exécute une fois par cycle de compaction (suivi dans sessions.json).
• Le vidage ne s’exécute que pour les sessions Pi intégrées (les backends CLI l’ignorent).
• Le vidage est ignoré lorsque l’espace de travail de la session est en lecture seule (workspaceAccess: "ro" ou "none").
• Voir Memory pour la disposition des fichiers de l’espace de travail et les modèles d’écriture.

​

Liste de vérification de dépannage

• Mauvaise clé de session ? Commencez par /concepts/session et confirmez la sessionKey dans /status.
• Incohérence entre magasin et transcription ? Confirmez l’hôte Gateway et le chemin du magasin via openclaw status.
• Compaction excessive ? Vérifiez :
  • fenêtre de contexte du modèle (trop petite)
  • paramètres de compaction (reserveTokens trop élevé pour la fenêtre du modèle peut provoquer une compaction plus précoce)
  • surcharge de résultats d’outils : activez/réglez l’élagage de session
• Fuite de tours silencieux ? Confirmez que la réponse commence par NO_REPLY (jeton exact insensible à la casse) et que vous utilisez une build qui inclut le correctif de suppression du streaming.