Transcript Hygiene (Provider Fixups)

Dieses Dokument beschreibt provider-spezifische Korrekturen, die auf Transcripts angewendet werden, bevor ein Run startet (beim Aufbau des Model Context). Diese Anpassungen erfolgen im Arbeitsspeicher und dienen dazu, strenge Provider-Anforderungen zu erfüllen. Sie schreiben das gespeicherte JSONL-Transcript auf der Festplatte nicht um.

Der Umfang umfasst:

  • Tool-Call-ID-Bereinigung
  • Reparatur der Tool-Result-Zuordnung
  • Turn-Validierung / Sortierung
  • Thought-Signature-Bereinigung
  • Image-Payload-Bereinigung

Wenn du Details zur Transcript-Speicherung brauchst, schau hier:

Wo das läuft

Die gesamte Transcript Hygiene ist im Embedded Runner zentralisiert:

  • Policy-Auswahl: src/agents/transcript-policy.ts
  • Bereinigung/Reparatur-Anwendung: sanitizeSessionHistory in src/agents/pi-embedded-runner/google.ts

Die Policy nutzt provider, modelApi und modelId, um zu entscheiden, was angewendet wird.

Globale Regel: Image-Bereinigung

Image-Payloads werden immer bereinigt, um eine provider-seitige Ablehnung wegen Größenlimits zu verhindern (Herunterskalierung/Neukomprimierung übergroßer Base64-Bilder).

Implementierung:

  • sanitizeSessionMessagesImages in src/agents/pi-embedded-helpers/images.ts
  • sanitizeContentBlocksImages in src/agents/tool-images.ts

Provider-Matrix (aktuelles Verhalten)

OpenAI / OpenAI Codex

  • Nur Image-Bereinigung.
  • Bei Modellwechsel zu OpenAI Responses/Codex werden verwaiste Reasoning-Signaturen entfernt (eigenständige Reasoning-Items ohne nachfolgenden Content-Block).
  • Keine Tool-Call-ID-Bereinigung.
  • Keine Tool-Result-Pairing-Reparatur.
  • Keine Turn-Validierung oder Neuordnung.
  • Keine synthetischen Tool-Results.
  • Keine Thought-Signature-Entfernung.

Google (Generative AI / Gemini CLI / Antigravity)

  • Tool-Call-ID-Bereinigung: strikt alphanumerisch.
  • Tool-Result-Pairing-Reparatur und synthetische Tool-Results.
  • Turn-Validierung (Gemini-Style Turn-Alternierung).
  • Google Turn-Ordering-Fixup (fügt einen kleinen User-Bootstrap vorne an, wenn die History mit Assistant beginnt).
  • Antigravity Claude: Normalisierung von Thinking-Signaturen; Entfernung unsignierter Thinking-Blöcke.

Anthropic / Minimax (Anthropic-kompatibel)

  • Tool-Result-Pairing-Reparatur und synthetische Tool-Results.
  • Turn-Validierung (zusammenführen aufeinanderfolgender User-Turns für strikte Alternierung).

Mistral (einschließlich modell-ID-basierter Erkennung)

  • Tool-Call-ID-Bereinigung: strict9 (alphanumerisch, Länge 9).

OpenRouter Gemini

  • Thought-Signature-Bereinigung: Entfernung von Nicht-Base64-thought_signature-Werten (Base64 bleibt erhalten).

Alles andere

  • Nur Image-Bereinigung.

Historisches Verhalten (vor 2026.1.22)

Vor dem Release 2026.1.22 wendete OpenClaw mehrere Ebenen von Transcript Hygiene an:

  • Eine transcript-sanitize Extension lief bei jedem Context-Build und konnte:
    • Tool-Use/Result-Pairing reparieren.
    • Tool-Call-IDs bereinigen (einschließlich eines nicht-strikten Modus, der _/- beibehielt).
  • Der Runner führte ebenfalls provider-spezifische Bereinigung durch, was zu doppelter Arbeit führte.
  • Zusätzliche Mutationen erfolgten außerhalb der Provider-Policy, darunter:
    • Entfernung von <final>-Tags aus Assistant-Text vor der Persistierung.
    • Entfernung leerer Assistant-Error-Turns.
    • Trimmen von Assistant-Content nach Tool-Calls.

Diese Komplexität verursachte Cross-Provider-Regressionen (insbesondere openai-responses call_id|fc_id-Pairing). Das Cleanup vom 2026.1.22 entfernte die Extension, zentralisierte die Logik im Runner und machte OpenAI no-touch außer bei der Image-Bereinigung.