Гигиена транскрипта (исправления провайдеров)

Этот документ описывает провайдер-специфичные исправления, применяемые к транскриптам перед запуском (построением контекста модели). Это настройки в памяти, используемые для удовлетворения строгих требований провайдеров. Эти шаги гигиены не переписывают хранимый на диске JSONL транскрипт; однако отдельный проход восстановления файла сессии может переписать неправильно оформленные JSONL файлы, удалив недействительные строки до загрузки сессии. Когда происходит восстановление, исходный файл резервируется рядом с файлом сессии.

Область включает:

  • Санитизация tool call id
  • Валидация входных данных tool call
  • Восстановление связывания результатов tool
  • Валидация/упорядочивание ходов
  • Очистка сигнатур мыслей
  • Санитизация payload изображений

Если вам нужны детали хранения транскрипта, см.:

Где это выполняется

Вся гигиена транскрипта централизована во встроенном раннере:

  • Выбор политики: src/agents/transcript-policy.ts
  • Применение санитизации/восстановления: sanitizeSessionHistory в src/agents/pi-embedded-runner/google.ts

Политика использует provider, modelApi и modelId для определения того, что применять.

Отдельно от гигиены транскрипта файлы сессий восстанавливаются (при необходимости) перед загрузкой:

  • repairSessionFileIfNeeded в src/agents/session-file-repair.ts
  • Вызывается из run/attempt.ts и compact.ts (встроенный раннер)

Глобальное правило: санитизация изображений

Payload изображений всегда санитизируются для предотвращения отказа со стороны провайдера из-за ограничений размера (уменьшение масштаба/повторное сжатие слишком больших base64 изображений).

Реализация:

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

Глобальное правило: неправильно оформленные tool call

Блоки tool-call ассистента, в которых отсутствуют и input, и arguments, удаляются перед построением контекста модели. Это предотвращает отказы провайдеров от частично сохраненных tool call (например, после сбоя из-за ограничения скорости).

Реализация:

  • sanitizeToolCallInputs в src/agents/session-transcript-repair.ts
  • Применяется в sanitizeSessionHistory в src/agents/pi-embedded-runner/google.ts

Матрица провайдеров (текущее поведение)

OpenAI / OpenAI Codex

  • Только санитизация изображений
  • При переключении модели на OpenAI Responses/Codex удаление осиротевших сигнатур рассуждений (отдельные элементы рассуждений без последующего блока контента)
  • Нет санитизации tool call id
  • Нет восстановления связывания результатов tool
  • Нет валидации или переупорядочивания ходов
  • Нет синтетических результатов tool
  • Нет удаления сигнатур мыслей

Google (Generative AI / Gemini CLI / Antigravity)

  • Санитизация tool call id: строгие буквенно-цифровые
  • Восстановление связывания результатов tool и синтетические результаты tool
  • Валидация ходов (чередование ходов в стиле Gemini)
  • Исправление порядка ходов Google (добавление небольшого пользовательского начального хода, если история начинается с ассистента)
  • Antigravity Claude: нормализация сигнатур мыслей; удаление неподписанных блоков мыслей

Anthropic / Minimax (совместимый с Anthropic)

  • Восстановление связывания результатов tool и синтетические результаты tool
  • Валидация ходов (объединение последовательных пользовательских ходов для удовлетворения строгого чередования)

Mistral (включая определение на основе model-id)

  • Санитизация tool call id: strict9 (буквенно-цифровая длина 9)

OpenRouter Gemini

  • Очистка сигнатур мыслей: удаление не-base64 значений thought_signature (сохранение base64)

Все остальное

  • Только санитизация изображений

Историческое поведение (до 2026.1.22)

До релиза 2026.1.22 OpenClaw применял несколько уровней гигиены транскрипта:

  • Расширение transcript-sanitize выполнялось при каждом построении контекста и могло:

    • Восстанавливать связывание tool use/result
    • Санитизировать tool call id (включая нестрогий режим, сохраняющий _/-)

  • Раннер также выполнял провайдер-специфичную санитизацию, что дублировало работу

  • Дополнительные изменения происходили вне политики провайдера, включая:

    • Удаление тегов из текста ассистента перед сохранением
    • Удаление пустых ошибочных ходов ассистента
    • Обрезка контента ассистента после tool call

Эта сложность вызвала регрессии между провайдерами (особенно связывание call_id|fc_id openai-responses). Очистка 2026.1.22 удалила расширение, централизовала логику в раннере и сделала OpenAI нетронутым, кроме санитизации изображений.

← Назад к документации