Обрезка сеанса

Прореживание сеанса удаляет старые результаты инструментов из контекста перед каждым вызовом LLM. Оно уменьшает разрастание контекста из-за накопленных результатов инструментов (результатов выполнения команд, чтения файлов, поиска), не переписывая обычный текст беседы.

Почему это важно

В длительных сеансах накапливаются результаты инструментов, увеличивающие контекстное окно. Это повышает стоимость и может привести к необходимости Compaction раньше, чем требуется.

Прореживание особенно полезно для кэширования промптов Anthropic. После истечения TTL кэша следующий запрос повторно кэширует весь промпт. Прореживание уменьшает объём записи в кэш, напрямую снижая стоимость.

Как это работает

Прореживание выполняется в режиме cache-ttl при одновременном выполнении проверки времени и проверки размера контекста:

1. Дождаться истечения TTL кэша (по умолчанию 5 минут при ручной настройке; автоматическое значение по умолчанию для Anthropic см. в разделе Интеллектуальные значения по умолчанию). До истечения TTL прореживание полностью пропускается, чтобы сохранить повторное использование кэша промптов для близких по времени ходов.
2. После истечения TTL оценить общий размер контекста относительно контекстного окна модели. Если отношение ниже softTrimRatio (по умолчанию 0.3), пропустить прореживание и не сбрасывать отсчёт TTL.
3. Выполнить мягкое сокращение слишком больших результатов инструментов, превышающих порог отношения: сохранить начало и конец (по умолчанию по 1500 символов, но не более 4000 символов суммарно), вставив между ними ....
4. Если отношение по-прежнему не ниже hardClearRatio (по умолчанию 0.5) и остаётся не менее minPrunableToolChars (по умолчанию 50,000) содержимого инструментов, которое можно проредить, выполнить полную очистку этих результатов: заменить их содержимое заполнителем (по умолчанию [Old tool result content cleared]).
5. Сбрасывать отсчёт TTL только тогда, когда прореживание действительно изменило контекст, чтобы последующие запросы повторно использовали свежий кэш.

Независимо от пороговых значений действуют два правила безопасности: последние keepLastAssistants ходов ассистента (по умолчанию 3) никогда не прореживаются, а всё, что находится до первого сообщения пользователя в сеансе, также никогда не прореживается (это защищает начальные операции чтения, такие как SOUL.md/USER.md).

Прореживать можно только сообщения toolResult; обычный текст беседы остаётся без изменений. Используйте agents.defaults.contextPruning.tools.{allow,deny}, чтобы указать, результаты каких инструментов можно прореживать.

Очистка устаревших изображений

OpenClaw также создаёт отдельное идемпотентное представление для повторного воспроизведения сеансов, в истории которых сохраняются необработанные блоки изображений или маркеры мультимедиа для заполнения промпта.

• Оно сохраняет 3 последних завершённых хода побайтово без изменений, чтобы префиксы кэша промптов оставались стабильными для недавних последующих запросов. Учитываются все завершённые ходы, а не только содержащие изображения, поэтому ходы, содержащие только текст, также занимают это окно.
• В представлении для повторного воспроизведения старые уже обработанные блоки изображений из истории user или toolResult заменяются на [image data removed - already processed by model].
• Старые текстовые ссылки на мультимедиа, такие как [media attached: ...], [Image: source: ...] и media://inbound/..., заменяются на [media reference removed - already processed by model]. Маркеры вложений текущего хода остаются без изменений, чтобы модели с поддержкой зрения по-прежнему могли загружать новые изображения.
• Исходная стенограмма сеанса не переписывается, поэтому средства просмотра истории по-прежнему могут отображать исходные записи сообщений и содержащиеся в них изображения.
• Этот механизм не связан с обычным прореживанием по TTL кэша, описанным выше. Он предотвращает нарушение кэшей промптов в последующих ходах из-за повторяющихся данных изображений или устаревших ссылок на мультимедиа.

Интеллектуальные значения по умолчанию

Встроенный плагин Anthropic автоматически настраивает прореживание и периодичность Heartbeat при первом разрешении профиля аутентификации Anthropic (или Claude CLI), но только для полей, которые ещё не были явно заданы:

Если вы самостоятельно зададите agents.defaults.contextPruning.mode или agents.defaults.heartbeat.every, OpenClaw не будет их переопределять. Это автоматическое значение по умолчанию применяется только к аутентификации семейства Anthropic; для других провайдеров прореживание получает значение off, если вы не настроите его самостоятельно.

Включение и отключение

Для провайдеров, отличных от Anthropic, прореживание по умолчанию отключено. Чтобы включить его:

{  agents: {    defaults: {      contextPruning: { mode: "cache-ttl", ttl: "5m" },    },  },}

Чтобы отключить: задайте mode: "off".

Прореживание и Compaction

Они дополняют друг друга: прореживание сокращает результаты инструментов между циклами Compaction.

Дополнительные материалы

• Compaction: сокращение контекста на основе резюмирования
• Конфигурация Gateway: все параметры конфигурации прореживания (contextPruning.*)

Связанные материалы

• Управление сеансами
• Инструменты сеанса
• Механизм контекста