Hygiène des transcriptions

OpenClaw applique des correctifs spécifiques au fournisseur aux transcriptions avant une exécution (création du contexte du modèle). La plupart de ces ajustements se font en mémoire pour satisfaire les exigences strictes du fournisseur. Une passe de réparation distincte du fichier de session peut également réécrire le JSONL stocké avant le chargement de la session, mais uniquement pour les lignes malformées ou les tours persistés qui sont des enregistrements durables invalides. Les réponses de l’assistant livrées sont conservées sur disque ; le nettoyage spécifique au fournisseur des préremplissages de l’assistant ne se produit que lors de la construction des charges utiles sortantes. Lorsqu’une réparation se produit, le fichier d’origine est écrit dans un fichier *.bak-<pid>-<ts> temporaire avant le remplacement atomique et supprimé une fois le remplacement réussi ; la sauvegarde n’est conservée que si le nettoyage lui-même échoue (auquel cas le chemin est signalé).

La portée inclut :

Le contexte de l’invite d’exécution uniquement reste en dehors des tours de transcription visibles par l’utilisateur
Nettoyage des identifiants d’appel d’outil
Validation des entrées d’appel d’outil
Réparation du couplage des résultats d’outil
Validation / ordonnancement des tours
Nettoyage des signatures de pensée
Nettoyage de la signature de réflexion
Assainissement de la charge utile de l’image
Nettoyage des blocs de texte vides avant la réexécution par le fournisseur
Étiquetage de la provenance des entrées utilisateur (pour les invites routées inter-session)
Réparation des tours d’erreur d’assistant vides pour la réexécution Bedrock Converse

Si vous avez besoin de détails sur le stockage des transcripts, consultez :

Session management deep dive

Règle globale : le contexte d’exécution n’est pas le transcript utilisateur

Le contexte d’exécution/système peut être ajouté au prompt du modèle pour un tour, mais ce n’est pas du contenu rédigé par l’utilisateur final. OpenClaw conserve un corps de prompt distinct orienté vers la transcription pour les réponses du Gateway, les suivis mis en file d’attente, l’ACP, le CLI et les exécutions OpenClaw incorporées. Les tours utilisateur visibles stockés utilisent ce corps de transcription à la place du prompt enrichi par l’exécution.

Pour les sessions héritées qui ont déjà persisté les wrappers d’exécution, les surfaces d’historique Gateway appliquent une projection d’affichage avant de renvoyer les messages aux clients WebChat, TUI, REST ou SSE.

Où cela s’exécute

Toute l’hygiène des transcripts est centralisée dans le runner intégré :

Sélection de la stratégie : src/agents/transcript-policy.ts
Application de la nettoyage/réparation : sanitizeSessionHistory dans src/agents/embedded-agent-runner/replay-history.ts

La stratégie utilise provider, modelApi et modelId pour décider quoi appliquer.

Indépendamment de l’hygiène des transcripts, les fichiers de session sont réparés (si nécessaire) avant le chargement :

repairSessionFileIfNeeded dans src/agents/session-file-repair.ts
Appelé depuis run/attempt.ts et compact.ts (runner intégré)

Règle globale : assainissement des images

Les charges utiles d’images sont toujours assainies pour éviter les rejets du côté du provider dus aux limites de taille (réduction de la taille/recompression des images base64 trop volumineuses).

Cela aide également à contrôler la pression de tokens liée aux images pour les modèles capables de vision. Des dimensions maximales plus faibles réduisent généralement l’utilisation de tokens ; des dimensions plus élevées préservent les détails.

Mise en œuvre :

sanitizeSessionMessagesImages dans src/agents/embedded-agent-helpers/images.ts
sanitizeContentBlocksImages dans src/agents/tool-images.ts
Le côté maximal de l’image est configurable via agents.defaults.imageMaxDimensionPx (par défaut : 1200).
Les blocs de texte vides sont supprimés pendant que cette passe parcourt le contenu de relecture. Les tours d’assistant qui deviennent vides sont supprimés de la copie de relecture ; les tours d’utilisateur et de résultats d’outil qui deviennent vides reçoivent un espace réservé non vide pour le contenu omis.

Règle globale : appels d’outil malformés

Les blocs d’appels d’outil de l’assistant qui manquent à la fois input et arguments sont supprimés avant la construction du contexte du modèle. Cela empêche les rejets du fournisseur dus à des appels d’outil partiellement persistés (par exemple, après un échec de limite de taux).

Mise en œuvre :

sanitizeToolCallInputs dans src/agents/session-transcript-repair.ts
Appliqué dans sanitizeSessionHistory dans src/agents/embedded-agent-runner/replay-history.ts

Règle globale : provenance des entrées inter-sessions

Lorsqu’un agent envoie une invite dans une autre session via sessions_send (y compris les étapes de réponse/annonce agent-à-agent), OpenClaw persiste le tour utilisateur créé avec :

message.provenance.kind = "inter_session"

OpenClaw précède également le texte d’invite routé d’une marqueur de même tour OpenClaw[Inter-session message ... isUser=false] afin que l’appel de modèle actif puisse distinguer la sortie de session étrangère des instructions externes de l’utilisateur final. Ce marqueur inclut la session source, le canal et l’outil lorsqu’ils sont disponibles. La transcription utilise toujours role: "user" pour la compatibilité du fournisseur, mais le texte visible et les métadonnées de provenance marquent tous deux le tour comme donnée intersession.

Pendant la reconstruction du contexte, OpenClaw applique le même marqueur aux anciens tours d’utilisateur inter-sessions persistés qui ne possèdent que des métadonnées de provenance.

Matrice des providers (comportement actuel)

OpenAI / OpenAI Codex

Nettoyage des images uniquement.
Supprimer les signatures de raisonnement orphelines (éléments de raisonnement autonomes sans bloc de contenu suivant) pour les transcriptions OpenAI Responses/Codex, et supprimer le raisonnement rejetable OpenAI après un changement de route de model.
Préserver les charges utiles des éléments de raisonnement des réponses OpenAI rejetables, y compris les éléments de résumé vide chiffrés, afin que la relecture manuelle/WebSocket maintienne l’état OpenAIrs_* requis associé aux éléments de sortie de l’assistant.
Les réponses natives Codex ChatGPT suivent la parité de liaison Codex en relayant les charges utiles de raisonnement/message/fonction de réponses antérieures sans identifiants d’élément antérieurs tout en préservant la session prompt_cache_key.
La relecture de la famille Responses de OpenAI préserve les paires de raisonnement call_*|fc_* canoniques du même modèle, mais normalise de manière déterministe les éléments d’ID d’appel de fonction call_id malformés ou trop longs avant la conversion de payload pi-ai.
La réparation des appariements de résultats d’outils peut déplacer les sorties correspondantes réelles et synthétiser des sorties aborted de style Codex pour les appels d’outils manquants.
Aucune validation ou réorganisation des tours.
Les sorties d’outils manquantes de la famille Responses de OpenAI sont synthétisées sous forme de aborted pour correspondre à la normalisation de la relecture Codex.
Aucun retrait de signature de pensée.

Chat Completions compatibles avec OpenAI

Les blocs historiques de pensée/raisonnement de l’assistant sont supprimés avant la relecture, afin que les serveurs compatibles OpenAI de type local et proxy ne reçoivent pas les champs de raisonnement des tours précédents tels que reasoning ou reasoning_content.
Les continuations d’appels de tool du même tour gardent le bloc de raisonnement de l’assistant attaché à l’appel de tool jusqu’à ce que le résultat du tool ait été relu.
Les entrées de model personnalisés/auto-hébergés avec reasoning: true préservent les métadonnées de raisonnement rejouées.
Les exceptions détenues par le provider peuvent choisir de s’abstenir lorsque leur protocole de liaison exige des métadonnées de raisonnement rejouées.

Google (Generative AI / Gemini CLI / Antigravity)

Assainissement de l’ID d’appel tool : alphanumérique strict.
Réparation de l’appariement des résultats tool et résultats tool synthétiques.
Validation des tours (alternance de tours style Gemini).
Correction de l’ordre des tours Google (ajouter un petit bootstrap utilisateur au début si l’historique commence par un assistant).
Antigravity Claude : normaliser les signatures de raisonnement ; supprimer les blocs de raisonnement non signés.

Anthropic / Minimax (compatible Anthropic)

Réparation de l’appariement des résultats tool et résultats tool synthétiques.
Validation des tours (fusionner les tours utilisateur consécutifs pour respecter l’alternance stricte).
Les tours de préremplissage d’assistant à la fin sont supprimés des payloads Messages Anthropic sortants lorsque la réflexion est activée, y compris sur les routes Cloudflare AI Gateway.
Les blocs de raisonnement avec des signatures de relecture manquantes, vides ou vides sont supprimés avant la conversion du provider. Si cela vide un tour d’assistant, OpenClaw conserve la forme du tour avec un texte de raisonnement omis non vide.
Les anciens tours d’assistant contenant uniquement de la réflexion qui doivent être supprimés sont remplacés par un texte de raisonnement omis non vide pour que les adaptateurs du provider ne suppriment pas le tour de relecture.

Amazon Bedrock (Converse API)

Les tours d’erreur de flux d’assistant vides sont réparés en un bloc de texte de repli non vide avant la relecture. Bedrock Converse rejette les messages d’assistant avec content: [], donc les tours d’assistant persistants avec stopReason: "error" et un contenu vide sont également réparés sur le disque avant le chargement.
Les tours d’erreur de flux d’assistant qui ne contiennent que des blocs de texte vides sont supprimés de la copie de relecture en mémoire au lieu de rejouer un bloc vide invalide.
Les blocs de raisonnement Claude avec des signatures de relecture manquantes, vides ou vides sont supprimés avant la relecture Converse. Si cela vide un tour d’assistant, OpenClaw conserve la forme du tour avec un texte de raisonnement omis non vide.
Les anciens tours d’assistant de réflexion uniquement qui doivent être supprimés sont remplacés par du texte de raison omise non vide afin que la relecture Converse maintienne une forme stricte des tours.
La relecture filtre les tours d’assistant injectés par la passerelle et le miroir de livraison OpenClaw.
La nettoyage des images s’applique via la règle globale.

Mistral (y compris la détection basée sur l’ID de modèle)

Nettoyage des ID d’appel d’outil : strict9 (longueur alphanumérique 9).

OpenRouter Gemini

Nettoyage de la signature de pensée : supprimer les valeurs thought_signature non base64 (garder le base64).

OpenRouter Anthropic

Les tours de préremplissage d’assistant à la fin sont supprimés des charges utiles de modèle OpenRouter compatibles OpenAI et vérifiées par Anthropic lorsque le raisonnement est activé, correspondant au comportement de relecture direct Anthropic et Cloudflare Anthropic.

Tout le reste

Nettoyage des images uniquement.

Comportement historique (avant le 2026.1.22)

Avant la version 2026.1.22, OpenClaw appliquait plusieurs couches d’hygiène de transcription :

Une extension transcript-sanitize s’exécutait à chaque construction de contexte et pouvait :
- Réparer le couplage utilisation/résultat d’outil.
- Nettoyer les ID d’appel d’outil (y compris un mode non strict qui préservait _/-).
Le moteur effectuait également une nettoyage spécifique au fournisseur, ce qui dupliquait le travail.
Des mutations supplémentaires se produisaient en dehors de la politique du fournisseur, notamment :
- Suppression des balises <final> du texte de l’assistant avant la persistance.
- Suppression des tours d’erreur d’assistant vides.
- Coupe du contenu de l’assistant après les appels d’outil.

Cette complexité a provoqué des régressions inter-fournisseurs (notamment le couplage openai-responses call_id|fc_id). Le nettoyage de 2026.1.22 a supprimé l’extension, centralisé la logique dans le moteur, et rendu OpenAI sans-toucher au-delà du nettoyage des images.