Сессии и память

Обрезка сессий

Обрезка сессий удаляет старые результаты инструментов из контекста в памяти непосредственно перед каждым вызовом LLM. Она не перезаписывает историю сессии на диске (*.jsonl).

Когда выполняется

Когда включен режим mode: "cache-ttl" и последний вызов Anthropic для сессии старше значения ttl.
Влияет только на сообщения, отправляемые модели для этого запроса.
Активна только для вызовов Anthropic API (и моделей Anthropic через OpenRouter).
Для наилучших результатов сопоставьте ttl с политикой cacheRetention вашей модели (short = 5 мин, long = 1 час).
После обрезки окно TTL сбрасывается, поэтому последующие запросы сохраняют кэш до повторного истечения ttl.

Умные настройки по умолчанию (Anthropic)

Профили OAuth или setup-token: включите обрезку cache-ttl и установите heartbeat на 1h.
Профили с API-ключом: включите обрезку cache-ttl, установите heartbeat на 30m и значение по умолчанию cacheRetention: "short" для моделей Anthropic.
Если вы явно задаете любое из этих значений, OpenClaw не переопределяет их.

Что это улучшает (затраты + поведение кэша)

Зачем обрезать: Кэширование промптов Anthropic применяется только в пределах TTL. Если сессия простаивает дольше TTL, следующий запрос повторно кэширует весь промпт, если вы не обрежете его предварительно.
Что становится дешевле: обрезка уменьшает размер cacheWrite для первого запроса после истечения TTL.
Почему важен сброс TTL: после выполнения обрезки окно кэша сбрасывается, поэтому последующие запросы могут повторно использовать свежезакэшированный промпт вместо повторного кэширования всей истории.
Чего она не делает: обрезка не добавляет токены и не "удваивает" затраты; она только меняет то, что кэшируется при первом запросе после TTL.

Что может быть обрезано

Только сообщения типа toolResult.
Сообщения пользователя и ассистента никогда не изменяются.
Последние keepLastAssistants сообщений ассистента защищены; результаты инструментов после этой границы не обрезаются.
Если недостаточно сообщений ассистента для установки границы, обрезка пропускается.
Результаты инструментов, содержащие блоки изображений, пропускаются (никогда не обрезаются/не очищаются).

Оценка контекстного окна

Обрезка использует оценку контекстного окна (символы ≈ токены × 4). Базовое окно определяется в следующем порядке:

Переопределение models.providers.*.models[].contextWindow.
Параметр contextWindow в определении модели (из реестра моделей).
Значение по умолчанию 200000 токенов.

Если задан параметр agents.defaults.contextTokens, он рассматривается как ограничение (минимум) для определенного окна.

Режим

cache-ttl

Обрезка выполняется только если последний вызов Anthropic старше значения ttl (по умолчанию 5m).
Когда выполняется: то же поведение soft-trim + hard-clear, что и раньше.

Мягкая vs жесткая обрезка

Мягкая обрезка (soft-trim): только для слишком больших результатов инструментов.
- Сохраняет начало и конец, вставляет ... и добавляет примечание с исходным размером.
- Пропускает результаты с блоками изображений.
Жесткая очистка (hard-clear): заменяет весь результат инструмента на hardClear.placeholder.

Выбор инструментов

tools.allow / tools.deny поддерживают подстановочные знаки *.
Правило deny имеет приоритет.
Сопоставление без учета регистра.
Пустой список allow => разрешены все инструменты.

Взаимодействие с другими ограничениями

Встроенные инструменты уже усекают свой собственный вывод; обрезка сессий — это дополнительный слой, который предотвращает накопление слишком большого объема вывода инструментов в контексте модели в долгих чатах.
Компактизация — это отдельный процесс: компактизация суммирует и сохраняет, обрезка является временной для каждого запроса. См. /concepts/compaction.

Значения по умолчанию (при включении)

ttl: "5m"
keepLastAssistants: 3
softTrimRatio: 0.3
hardClearRatio: 0.5
minPrunableToolChars: 50000
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

Примеры

По умолчанию (выключено):

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

Включить обрезку с учетом TTL:

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

Ограничить обрезку определенными инструментами:

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

См. справочник по конфигурации: Конфигурация Gateway

Управление сессиями Инструменты сессии