Перейти до основного вмісту

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

У цьому документі описано специфічні для провайдерів виправлення, які застосовуються до транскриптів перед запуском (побудовою контексту моделі). Це внутрішньопам’ятні коригування, що використовуються для дотримання суворих вимог провайдерів. Ці кроки гігієни не переписують збережений JSONL-транскрипт на диску; однак окремий прохід відновлення файлу сесії може переписати некоректні JSONL-файли, видаляючи невалідні рядки перед завантаженням сесії. Коли відновлення виконується, оригінальний файл резервно копіюється поруч із файлом сесії. Область охоплює:
  • Санітизацію id викликів інструментів
  • Валідацію вхідних даних викликів інструментів
  • Відновлення зіставлення результатів інструментів
  • Валідацію / упорядкування ходів
  • Очищення сигнатур думок
  • Санітизацію корисного навантаження зображень
  • Маркування походження введення користувача (для переспрямованих міжсесійних запитів)
Якщо вам потрібні подробиці про зберігання транскриптів, дивіться:

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

Уся гігієна транскриптів централізована у вбудованому ранері:
  • Вибір політики: 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 також додає на початку короткий маркер [Inter-session message] до таких ходів користувача в пам’яті, щоб модель могла відрізняти їх від зовнішніх інструкцій кінцевого користувача.

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

OpenAI / OpenAI Codex
  • Лише санітизація зображень.
  • Видалення осиротілих сигнатур міркувань (окремих елементів міркувань без наступного блоку контенту) для транскриптів OpenAI Responses/Codex.
  • Без санітизації id викликів інструментів.
  • Без відновлення зіставлення результатів інструментів.
  • Без валідації або перевпорядкування ходів.
  • Без синтетичних результатів інструментів.
  • Без видалення сигнатур думок.
Google (Generative AI / Gemini CLI / Antigravity)
  • Санітизація id викликів інструментів: суворо алфанумеричні.
  • Відновлення зіставлення результатів інструментів і синтетичні результати інструментів.
  • Валідація ходів (чергування ходів у стилі Gemini).
  • Виправлення порядку ходів Google (додавання на початок крихітного bootstrap-повідомлення користувача, якщо історія починається з помічника).
  • Antigravity Claude: нормалізація сигнатур thinking; видалення блоків thinking без сигнатури.
Anthropic / Minimax (сумісні з Anthropic)
  • Відновлення зіставлення результатів інструментів і синтетичні результати інструментів.
  • Валідація ходів (об’єднання послідовних ходів користувача для дотримання суворого чергування).
Mistral (включно з виявленням на основі model-id)
  • Санітизація id викликів інструментів: strict9 (алфанумерична довжина 9).
OpenRouter Gemini
  • Очищення сигнатур думок: видалення значень thought_signature, які не є base64 (base64 зберігаються).
Усе інше
  • Лише санітизація зображень.

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

До релізу 2026.1.22 OpenClaw застосовував кілька шарів гігієни транскриптів:
  • Розширення transcript-sanitize запускалося під час кожної побудови контексту і могло:
    • Відновлювати зіставлення use/result інструментів.
    • Санітизувати id викликів інструментів (зокрема в несуворому режимі, який зберігав _/-).
  • Ранер також виконував специфічну для провайдерів санітизацію, що дублювало роботу.
  • Додаткові мутації відбувалися поза політикою провайдера, зокрема:
    • Видалення тегів <final> з тексту помічника перед збереженням.
    • Відкидання порожніх ходів помічника з помилками.
    • Обрізання контенту помічника після викликів інструментів.
Ця складність спричинила регресії між провайдерами (зокрема для зіставлення openai-responses call_id|fc_id). Очищення 2026.1.22 видалило розширення, централізувало логіку в раннері та зробило OpenAI недоторканим за межами санітизації зображень.