openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0efbf6b5a5
docs/docs/uk/reference/transcript-hygiene.md
openclaw-docs-i18n[bot] 0efbf6b5a5 chore(i18n): refresh uk translations
2026-04-28 19:39:44 +00:00

17 KiB
Raw Blame History

read_when summary title x-i18n
Ви налагоджуєте відхилення запитів провайдером, пов’язані зі структурою транскрипту
Ви змінюєте логіку санітизації транскрипту або виправлення викликів інструментів
Ви досліджуєте невідповідності ідентифікаторів викликів інструментів між провайдерами
Довідка: правила очищення та відновлення транскриптів, специфічні для провайдера Гігієна транскрипту
generated_at model provider source_hash source_path workflow
2026-04-28T19:39:03Z gpt-5.5 openai 51459c719c6314b2980057d7e1e003e1598e8fe4a619c081aa25ce29200645a8 reference/transcript-hygiene.md 16

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

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

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

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

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

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

Для застарілих сеансів, які вже зберегли обгортки виконання, поверхні історії 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)

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

Корисне навантаження зображень завжди очищується, щоб запобігти відхиленню на боці провайдера через обмеження розміру (зменшення масштабу/повторне стиснення надмірно великих зображень 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/replay-history.ts

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

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

  • message.provenance.kind = "inter_session"

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

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

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

OpenAI / OpenAI Codex

  • Лише очищення зображень.
  • Відкидати осиротілі підписи reasoning (окремі елементи reasoning без наступного блока контенту) для транскриптів OpenAI Responses/Codex і відкидати повторно відтворюваний OpenAI reasoning після перемикання маршруту моделі.
  • Зберігати повторно відтворювані payload елементів reasoning OpenAI Responses, зокрема зашифровані елементи з порожнім підсумком, щоб ручне/WebSocket повторне відтворення зберігало потрібний стан rs_*, поєднаний з елементами виводу асистента.
  • Без очищення ідентифікаторів викликів інструментів.
  • Ремонт зіставлення результатів інструментів може переміщувати реальні зіставлені виводи та синтезувати Codex-стилю виводи aborted для відсутніх викликів інструментів.
  • Без перевірки чи переупорядкування реплік.
  • Відсутні виводи інструментів сімейства OpenAI Responses синтезуються як aborted, щоб відповідати нормалізації повторного відтворення Codex.
  • Без видалення підписів думок.

OpenAI-сумісна Gemma 4

  • Історичні блоки мислення/reasoning асистента видаляються перед повторним відтворенням, щоб локальні OpenAI-сумісні сервери Gemma 4 не отримували контент reasoning із попередніх реплік.
  • Поточні продовження викликів інструментів у межах тієї самої репліки зберігають блок reasoning асистента приєднаним до виклику інструмента, доки результат інструмента не буде повторно відтворено.

Google (Generative AI / Gemini CLI / Antigravity)

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

Anthropic / Minimax (Anthropic-сумісні)

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

Amazon Bedrock (Converse API)

  • Порожні репліки асистента з помилкою stream ремонтуються в непорожній fallback текстовий блок перед повторним відтворенням. Bedrock Converse відхиляє повідомлення асистента з content: [], тому збережені репліки асистента з stopReason: "error" і порожнім контентом також ремонтуються на диску перед завантаженням.
  • Блоки мислення Claude з відсутніми, порожніми або blank підписами повторного відтворення видаляються перед повторним відтворенням Converse. Якщо це спорожнює репліку асистента, OpenClaw зберігає форму репліки з непорожнім текстом про пропущене reasoning.
  • Старіші репліки асистента лише з мисленням, які потрібно видалити, замінюються непорожнім текстом про пропущене reasoning, щоб повторне відтворення Converse зберігало сувору форму реплік.
  • Повторне відтворення фільтрує delivery-mirror OpenClaw і вставлені gateway репліки асистента.
  • Очищення зображень застосовується через глобальне правило.

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

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

OpenRouter Gemini

  • Очищення підписів думок: видаляти не-base64 значення thought_signature (залишати base64).

Усе інше

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

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

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

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

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

Пов’язане