Технический справочник

Гигиена транскриптов

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

Санацию идентификаторов вызовов инструментов
Валидацию входных данных вызовов инструментов
Восстановление пар вызов/результат инструмента
Валидацию / упорядочивание ходов
Очистку сигнатур размышлений
Санацию полезной нагрузки изображений
Тегирование происхождения пользовательского ввода (для промптов, перенаправленных между сессиями)

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

/reference/session-management-compaction

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

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

Выбор политики: 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 (встроенный раннер)

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

Полезные нагрузки изображений всегда проходят санацию, чтобы предотвратить отклонение со стороны провайдера из-за ограничений размера (уменьшение масштаба/пережатие слишком больших изображений в base64). Это также помогает контролировать нагрузку на токены, вызванную изображениями, для моделей с поддержкой зрения. Меньшие максимальные размеры обычно снижают использование токенов; большие размеры сохраняют детализацию. Реализация:

sanitizeSessionMessagesImages в src/agents/pi-embedded-helpers/images.ts
sanitizeContentBlocksImages в src/agents/tool-images.ts
Максимальная сторона изображения настраивается через agents.defaults.imageMaxDimensionPx (по умолчанию: 1200).

Глобальное правило: некорректные вызовы инструментов

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

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

Глобальное правило: происхождение ввода между сессиями

Когда агент отправляет промпт в другую сессию через sessions_send (включая шаги ответа/объявления от агента к агенту), OpenClaw сохраняет созданный пользовательский ход с:

message.provenance.kind = "inter_session"

Эти метаданные записываются в момент добавления в транскрипт и не меняют роль (role: "user" остаётся для совместимости с провайдерами). Читатели транскриптов могут использовать это, чтобы не рассматривать перенаправленные внутренние промпты как инструкции от конечного пользователя. При перестроении контекста OpenClaw также добавляет в оперативную память короткий маркер [Сообщение между сессиями] к этим пользовательским ходам, чтобы модель могла отличать их от инструкций внешнего конечного пользователя.

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

OpenAI / OpenAI Codex

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

Google (Generative AI / Gemini CLI / Antigravity)

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

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

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

Mistral (включая обнаружение на основе model-id)

Санация идентификаторов вызовов инструментов: strict9 (буквенно-цифровые, длина 9).

OpenRouter Gemini

Очистка сигнатур размышлений: удаление значений thought_signature, не являющихся base64 (сохраняются base64).

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

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

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

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

Расширение transcript-sanitize запускалось при каждом построении контекста и могло:
- Восстанавливать пары использование/результат инструмента.
- Санировать идентификаторы вызовов инструментов (включая нестрогий режим, сохраняющий _/-).
Раннер также выполнял провайдер-специфичную санацию, что дублировало работу.
Дополнительные мутации происходили вне политики провайдера, включая:
- Удаление тегов <final> из текста ассистента перед сохранением.
- Удаление пустых ходов ассистента с ошибками.
- Обрезку контента ассистента после вызовов инструментов.

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

Использование API и стоимость Дата и время