English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

Гігієна транскрипту

OpenClaw застосовує виправлення, специфічні для провайдера, до транскриптів перед запуском (під час побудови контексту моделі). Більшість із них — це коригування в пам’яті, потрібні для виконання суворих вимог провайдера. Окремий прохід виправлення файлу сесії також може переписати збережений JSONL перед завантаженням сесії, але лише для некоректних рядків або збережених ходів, які є недійсними довготривалими записами. Доставлені відповіді асистента зберігаються на диску; видалення передзаповнення асистента, специфічне для провайдера, відбувається лише під час побудови вихідних payload. Коли відбувається виправлення, резервна копія початкового файлу створюється поруч із файлом сесії.

Область охоплює:

  • Контекст промпта лише для runtime, який не потрапляє до видимих для користувача ходів транскрипту
  • Очищення id викликів інструментів
  • Валідацію вводу викликів інструментів
  • Виправлення парування результатів інструментів
  • Валідацію / впорядкування ходів
  • Очищення thought signature
  • Очищення thinking signature
  • Очищення payload зображень
  • Очищення порожніх текстових блоків перед provider replay
  • Позначення походження користувацького вводу (для промптів, маршрутизованих між сесіями)
  • Виправлення порожнього error-turn асистента для Bedrock Converse replay

Якщо потрібні подробиці зберігання транскриптів, див.:

Глобальне правило: runtime-контекст не є користувацьким транскриптом

Runtime/system context може додаватися до промпта моделі для ходу, але це не вміст, створений кінцевим користувачем. OpenClaw зберігає окреме тіло промпта, призначене для транскрипту, для відповідей Gateway, подальших запитів у черзі, ACP, CLI та вбудованих запусків Pi. Збережені видимі користувацькі ходи використовують це тіло транскрипту замість промпта, збагаченого runtime-контекстом.

Для застарілих сесій, у яких уже були збережені runtime-обгортки, поверхні історії Gateway застосовують проєкцію відображення перед поверненням повідомлень до WebChat, TUI, REST або SSE клієнтів.

Де це виконується

Уся гігієна транскриптів централізована у вбудованому runner:

  • Вибір політики: src/agents/transcript-policy.ts
  • Застосування очищення/виправлення: sanitizeSessionHistory у src/agents/pi-embedded-runner/replay-history.ts

Політика використовує provider, modelApi і modelId, щоб вирішити, що застосовувати.

Окремо від гігієни транскриптів, файли сесій виправляються (за потреби) перед завантаженням:

  • repairSessionFileIfNeeded у src/agents/session-file-repair.ts
  • Викликається з run/attempt.ts і compact.ts (вбудований runner)

Глобальне правило: очищення зображень

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

Це також допомагає контролювати токенне навантаження від зображень для моделей із підтримкою vision. Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталізацію.

Реалізація:

  • sanitizeSessionMessagesImages у src/agents/pi-embedded-helpers/images.ts
  • sanitizeContentBlocksImages у src/agents/tool-images.ts
  • Максимальний бік зображення налаштовується через agents.defaults.imageMaxDimensionPx (типово: 1200).
  • Порожні текстові блоки видаляються, коли цей прохід обходить replay-вміст. Ходи асистента, які стають порожніми, вилучаються з replay-копії; користувацькі ходи та ходи результатів інструментів, які стають порожніми, отримують непорожній placeholder пропущеного вмісту.

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

Блоки викликів інструментів асистента, у яких відсутні і input, і arguments, відкидаються до побудови контексту моделі. Це запобігає відхиленням провайдерами через частково збережені виклики інструментів (наприклад, після помилки обмеження частоти).

Реалізація:

  • sanitizeToolCallInputs у src/agents/session-transcript-repair.ts
  • Застосовується в sanitizeSessionHistory у src/agents/pi-embedded-runner/replay-history.ts

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

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

  • message.provenance.kind = "inter_session"

OpenClaw також додає перед маршрутизованим текстом промпта маркер того самого ходу [Inter-session message ... isUser=false], щоб активний виклик моделі міг відрізнити вивід сторонньої сесії від зовнішніх інструкцій кінцевого користувача. Цей маркер містить джерельну сесію, канал та інструмент, коли вони доступні. Транскрипт усе ще використовує role: "user" для сумісності з провайдерами, але і видимий текст, і метадані provenance позначають хід як міжсесійні дані.

Під час перебудови контексту OpenClaw застосовує той самий маркер до старіших збережених міжсесійних користувацьких ходів, які мають лише метадані provenance.

Матриця провайдерів (поточна поведінка)

OpenAI / OpenAI Codex

  • Лише очищення зображень.
  • Відкидати orphaned reasoning signatures (окремі reasoning items без наступного content block) для транскриптів OpenAI Responses/Codex, а також відкидати replayable OpenAI reasoning після перемикання маршруту моделі.
  • Зберігати payload replayable OpenAI Responses reasoning item, включно із зашифрованими елементами з порожнім summary, щоб manual/WebSocket replay зберігав потрібний стан rs_* у парі з output items асистента.
  • Native ChatGPT Codex Responses дотримується wire parity Codex, відтворюючи попередні Responses reasoning/message/function payloads без попередніх item IDs, водночас зберігаючи prompt_cache_key сесії.
  • Без очищення id викликів інструментів.
  • Виправлення парування результатів інструментів може переміщувати реальні зіставлені outputs і синтезувати Codex-style aborted outputs для відсутніх викликів інструментів.
  • Без валідації чи перевпорядкування ходів.
  • Відсутні tool outputs сімейства OpenAI Responses синтезуються як aborted, щоб відповідати нормалізації Codex replay.
  • Без видалення thought signature.

OpenAI-compatible Gemma 4

  • Історичні thinking/reasoning blocks асистента видаляються перед replay, щоб локальні OpenAI-compatible сервери Gemma 4 не отримували reasoning content попередніх ходів.
  • Поточні same-turn tool-call continuations зберігають reasoning block асистента, прикріплений до виклику інструмента, доки результат інструмента не буде replayed.

Google (Generative AI / Gemini CLI / Antigravity)

  • Очищення id викликів інструментів: суворо буквено-цифрові.
  • Виправлення парування результатів інструментів і synthetic tool results.
  • Валідація ходів (Gemini-style чергування ходів).
  • Google turn ordering fixup (додавання крихітного user bootstrap на початок, якщо історія починається з assistant).
  • Antigravity Claude: нормалізувати thinking signatures; відкидати unsigned thinking blocks.

Anthropic / Minimax (Anthropic-compatible)

  • Виправлення парування результатів інструментів і synthetic tool results.
  • Валідація ходів (об’єднання послідовних користувацьких ходів для дотримання суворого чергування).
  • Кінцеві ходи assistant prefill видаляються з вихідних Anthropic Messages payloads, коли thinking увімкнено, включно з маршрутами Cloudflare AI Gateway.
  • Thinking blocks з відсутніми, порожніми або blank replay signatures видаляються перед provider conversion. Якщо це спустошує хід асистента, OpenClaw зберігає форму ходу з непорожнім omitted-reasoning text.
  • Старіші thinking-only ходи асистента, які потрібно видалити, замінюються непорожнім omitted-reasoning text, щоб provider adapters не відкидали replay turn.

Amazon Bedrock (Converse API)

  • Порожні assistant stream-error turns виправляються до непорожнього fallback text block перед replay. Bedrock Converse відхиляє повідомлення асистента з content: [], тому збережені ходи асистента з stopReason: "error" і порожнім content також виправляються на диску перед завантаженням.
  • Assistant stream-error turns, що містять лише blank text blocks, відкидаються з in-memory replay copy замість replay недійсного blank block.
  • Claude thinking blocks з відсутніми, порожніми або blank replay signatures видаляються перед Converse replay. Якщо це спустошує хід асистента, OpenClaw зберігає форму ходу з непорожнім omitted-reasoning text.
  • Старіші thinking-only ходи асистента, які потрібно видалити, замінюються непорожнім omitted-reasoning text, щоб Converse replay зберігав сувору форму ходу.
  • Replay фільтрує OpenClaw delivery-mirror і gateway-injected assistant turns.
  • Очищення зображень застосовується через глобальне правило.

Mistral (including model-id based detection)

  • Очищення id викликів інструментів: strict9 (буквено-цифрові довжиною 9).

OpenRouter Gemini

  • Очищення thought signature: видаляти не-base64 значення thought_signature (зберігати base64).

OpenRouter Anthropic

  • Кінцеві ходи assistant prefill видаляються з verified OpenRouter OpenAI-compatible Anthropic model payloads, коли reasoning увімкнено, відповідно до direct Anthropic і Cloudflare Anthropic replay behavior.

Усе інше

  • Лише очищення зображень.

Історична поведінка (до 2026.1.22)

До випуску 2026.1.22 OpenClaw застосовував кілька шарів гігієни транскриптів:

  • transcript-sanitize extension запускалося під час кожної побудови контексту й могло:
    • Виправляти парування tool use/result.
    • Очищати ids викликів інструментів (включно з non-strict mode, який зберігав _/-).
  • Runner також виконував provider-specific sanitization, що дублювало роботу.
  • Додаткові мутації відбувалися поза provider policy, включно з:
    • Видаленням тегів <final> із тексту асистента перед persistence.
    • Відкиданням порожніх assistant error turns.
    • Обрізанням content асистента після викликів інструментів.

Ця складність спричиняла крос-провайдерні регресії (зокрема парування openai-responses call_id|fc_id). Очищення 2026.1.22 видалило extension, централізувало логіку в runner і зробило OpenAI no-touch за межами очищення зображень.

Пов’язане