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

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

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

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

Умные значения по умолчанию (Anthropic)

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

Что это улучшает (стоимость + поведение кэша)

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

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

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

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

Обрезка использует оценочное окно контекста (символы ≈ токены × 4). Размер окна разрешается в этом порядке:

  1. Определение модели contextWindow (из реестра моделей).
  2. Переопределение models.providers.*.models[].contextWindow.
  3. agents.defaults.contextTokens.
  4. По умолчанию 200000 токенов.

Режим

cache-ttl

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

Soft vs hard обрезка

  • Soft-trim: только для больших результатов инструментов.
    • Сохраняет голову + хвост, вставляет ... и добавляет примечание с исходным размером.
    • Пропускает результаты с блоками изображений.
  • Hard-clear: заменяет весь результат инструмента на hardClear.placeholder.

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

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

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

  • Встроенные инструменты уже усекают свой собственный вывод; обрезка сессии - это дополнительный слой, который предотвращает накопление слишком большого вывода инструмента в контексте модели для долгих чатов.
  • Уплотнение отдельно: уплотнение суммирует и сохраняет, обрезка временная для каждого запроса. См. /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]" \}

Примеры

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

{
  agent: {
    contextPruning: { mode: "off" }
  }
}

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

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

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

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

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

← Назад к документации