Technical reference

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

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

Коли виконується відновлення, перед атомарною заміною вихідний файл записується до тимчасового сусіднього файла *.bak-<pid>-<ts>, а після успішної заміни видаляється. Резервна копія зберігається лише в разі помилки самого очищення; у такому разі її шлях повертається у звіті.

Охоплено такі аспекти:

Контекст запиту лише для середовища виконання не потрапляє до видимих користувачеві реплік транскрипту
Очищення ідентифікаторів викликів інструментів
Перевірка вхідних даних викликів інструментів
Відновлення відповідності результатів інструментів
Перевірка та впорядкування реплік
Очищення підписів міркувань
Очищення підписів процесу мислення
Очищення корисного навантаження зображень
Видалення порожніх текстових блоків перед повторним відтворенням для провайдера
Видалення незавершених реплік, що містять лише міркування та завершилися через обмеження довжини, перед повторним відтворенням для провайдера
Позначення походження введення користувача (для запитів, переспрямованих між сеансами)
Відновлення порожніх помилкових реплік асистента для повторного відтворення Bedrock Converse

Докладніше про зберігання транскриптів див. у Поглибленому огляді керування сеансами.

Глобальне правило: контекст середовища виконання не є транскриптом користувача

Контекст середовища виконання або системний контекст можна додати до запиту моделі для певної репліки, але він не є вмістом, створеним кінцевим користувачем. OpenClaw зберігає окреме призначене для транскрипту тіло запиту для відповідей Gateway, подальших запитів у черзі, ACP, CLI та вбудованих запусків OpenClaw. У збережених видимих репліках користувача використовується це тіло транскрипту замість запиту, доповненого контекстом середовища виконання.

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

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

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

Вибір політики: src/agents/transcript-policy.ts (resolveTranscriptPolicy, з ключами provider, modelApi і modelId)
Застосування очищення та відновлення: sanitizeSessionHistory у src/agents/embedded-agent-runner/replay-history.ts

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

repairSessionFileIfNeeded у src/agents/session-file-repair.ts
Викликається з src/agents/embedded-agent-runner/run/attempt.ts і src/agents/embedded-agent-runner/compact.ts

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

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

Реалізація:

sanitizeSessionMessagesImages у src/agents/embedded-agent-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/embedded-agent-runner/replay-history.ts)

Глобальне правило: незавершені репліки лише з міркуваннями

Репліки асистента, які досягли обмеження вихідних даних провайдера та містять лише процес мислення або відредагований вміст процесу мислення, вилучаються з копії для повторного відтворення у пам’яті. Такі репліки містять незавершений стан провайдера та можуть містити частковий підпис процесу мислення.

Порожні репліки з причиною завершення через довжину залишаються без змін, як і репліки з видимим текстом, викликами інструментів або невідомими блоками вмісту. Збережені транскрипти не перезаписуються.

Реалізація: normalizeAssistantReplayContent у src/agents/embedded-agent-runner/replay-history.ts

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

Коли агент надсилає запит до іншого сеансу через sessions_send (зокрема під час кроків відповіді або оголошення між агентами), OpenClaw зберігає створену репліку користувача з message.provenance.kind = "inter_session".

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

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

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

OpenAI / OpenAI Codex

Лише очищення зображень.
Вилучення осиротілих підписів міркувань (окремих елементів міркувань без наступного блока вмісту) для транскриптів OpenAI Responses/Codex, а також вилучення придатних до повторного відтворення міркувань OpenAI після перемикання маршруту моделі.
Збереження корисних навантажень елементів міркувань OpenAI Responses, придатних до повторного відтворення, зокрема зашифрованих елементів із порожнім підсумком, щоб ручне повторне відтворення або повторне відтворення через WebSocket зберігало необхідний стан rs_* у парі з елементами вихідних даних асистента.
Власна реалізація ChatGPT Codex Responses дотримується сумісності з протоколом Codex, повторно відтворюючи попередні корисні навантаження міркувань, повідомлень і функцій Responses без попередніх ідентифікаторів елементів, водночас зберігаючи prompt_cache_key сеансу.
Повторне відтворення сімейства OpenAI Responses зберігає канонічні пари міркувань тієї самої моделі call_*|fc_*, але детерміновано нормалізує пошкоджені або надто довгі ідентифікатори call_id чи елементів виклику функції перед перетворенням корисного навантаження pi-ai.
Відновлення відповідності результатів інструментів може переміщувати справжні відповідні вихідні дані та синтезувати вихідні дані Codex у стилі aborted для відсутніх викликів інструментів.
Без перевірки або перевпорядкування реплік; без видалення підписів міркувань.

Сумісні з OpenAI Chat Completions

Історичні блоки процесу мислення або міркувань асистента вилучаються перед повторним відтворенням, щоб локальні та проксі-сервери, сумісні з OpenAI, не отримували поля міркувань попередніх реплік, як-от reasoning або reasoning_content.
Поточні продовження викликів інструментів у межах тієї самої репліки зберігають блок міркувань асистента, приєднаний до виклику інструмента, доки результат інструмента не буде повторно відтворено.
Власні або самостійно розміщені записи моделей із reasoning: true зберігають повторно відтворені метадані міркувань.
Винятки, визначені провайдером, можуть відмовитися від цієї поведінки, коли їхній протокол обміну потребує повторного відтворення метаданих міркувань.

Google (Generative AI / Gemini CLI / Antigravity)

Очищення ідентифікаторів викликів інструментів: суворо буквено-цифрові символи.
Відновлення відповідності результатів інструментів і синтетичні результати інструментів.
Перевірка реплік (чергування реплік у стилі Gemini).
Виправлення порядку реплік Google (додавання на початку короткої початкової репліки користувача, якщо історія починається з асистента).
Antigravity Claude: нормалізація підписів процесу мислення; вилучення непідписаних блоків процесу мислення.

Anthropic / Minimax (сумісний з Anthropic)

Відновлення відповідності результатів інструментів і синтетичні результати інструментів.
Перевірка реплік (об’єднання послідовних реплік користувача для дотримання суворого чергування).
Кінцеві репліки попереднього заповнення асистента вилучаються з вихідних корисних навантажень Anthropic Messages, коли ввімкнено процес мислення, зокрема для маршрутів Cloudflare AI Gateway.
Підписи процесу мислення асистента до Compaction вилучаються перед повторним відтворенням для провайдера, якщо сеанс було ущільнено. Підписи процесу мислення криптографічно прив’язані до префікса розмови на момент створення; після Compaction префікс змінюється (підсумований вміст замінює оригінальний), тому повторне відтворення оригінальних підписів змушує Anthropic відхилити запит із повідомленням "Недійсний підпис у блоці процесу мислення". Текст процесу мислення зберігається як непідписаний блок, а потім обробляється за наведеним нижче правилом.
Блоки процесу мислення з відсутніми, порожніми або пробільними підписами для повторного відтворення вилучаються перед перетворенням для провайдера. Якщо через це репліка асистента стає порожньою, OpenClaw зберігає структуру репліки за допомогою непорожнього тексту про пропущені міркування.
Старіші репліки асистента лише з процесом мислення, які потрібно вилучити, замінюються непорожнім текстом про пропущені міркування, щоб адаптери провайдера не вилучили репліку повторного відтворення.

Amazon Bedrock (Converse API)

Порожні репліки асистента з помилкою потоку відновлюються до непорожнього резервного текстового блока перед повторним відтворенням. Bedrock Converse відхиляє повідомлення асистента з content: [], тому збережені репліки асистента зі stopReason: "error" і порожнім вмістом також відновлюються на диску перед завантаженням.
Репліки асистента з помилкою потоку, які містять лише порожні текстові блоки, вилучаються з копії для повторного відтворення у пам’яті замість повторного відтворення некоректного порожнього блока.
Підписи процесу мислення асистента до Compaction вилучаються перед повторним відтворенням Converse, якщо сеанс було ущільнено, з тієї самої причини, що й для Anthropic вище.
Блоки процесу мислення Claude з відсутніми, порожніми або пробільними підписами для повторного відтворення вилучаються перед повторним відтворенням Converse. Якщо через це репліка асистента стає порожньою, OpenClaw зберігає структуру репліки за допомогою непорожнього тексту про пропущені міркування.
Старіші репліки асистента лише з процесом мислення, які потрібно вилучити, замінюються непорожнім текстом про пропущені міркування, щоб повторне відтворення Converse зберігало сувору структуру реплік.
Під час повторного відтворення відфільтровуються дзеркальні репліки доставки OpenClaw та репліки асистента, вставлені Gateway.
Очищення зображень застосовується згідно з глобальним правилом.

Mistral (зокрема виявлення на основі ідентифікатора моделі)

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

OpenRouter Gemini

Очищення підписів міркувань: вилучення значень thought_signature, що не є base64 (значення base64 зберігаються).

OpenRouter Anthropic

Кінцеві репліки попереднього заповнення асистента вилучаються з перевірених корисних навантажень моделей Anthropic, сумісних з OpenAI через OpenRouter, коли ввімкнено міркування, відповідно до поведінки повторного відтворення прямих маршрутів Anthropic і Cloudflare Anthropic.

Усе інше

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

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

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

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

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

Пов’язані матеріали

Was this useful?