Technical reference

Кэширование промптов

Кэширование промптов означает, что провайдер модели может повторно использовать неизмененные префиксы промпта (обычно системные/разработческие инструкции и другой стабильный контекст) между ходами вместо их повторной обработки каждый раз. OpenClaw нормализует использование провайдера в cacheRead и cacheWrite, когда вышестоящий API напрямую предоставляет эти счетчики.

Поверхности состояния также могут восстанавливать счетчики кэша из самого свежего журнала использования транскрипта, когда в живом снимке сессии они отсутствуют, поэтому /status может продолжать показывать строку кэша после частичной потери метаданных сессии. Существующие ненулевые живые значения кэша по-прежнему имеют приоритет над резервными значениями из транскрипта.

Почему это важно: ниже стоимость токенов, быстрее ответы и более предсказуемая производительность для долгоживущих сессий. Без кэширования повторяющиеся промпты оплачивают полную стоимость промпта на каждом ходе, даже когда большая часть ввода не изменилась.

Разделы ниже охватывают все связанные с кэшем параметры, которые влияют на повторное использование промптов и стоимость токенов.

Ссылки провайдеров:

Кэширование промптов Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
Кэширование промптов OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
Заголовки API OpenAI и идентификаторы запросов: https://developers.openai.com/api/reference/overview
Идентификаторы запросов и ошибки Anthropic: https://platform.claude.com/docs/en/api/errors

Основные параметры

`cacheRetention` (глобальное значение по умолчанию, модель и отдельный агент)

Задайте удержание кэша как глобальное значение по умолчанию для всех моделей:

yaml

agents:  defaults:    params:      cacheRetention: "long" # none | short | long

Переопределение для модели:

yaml

agents:  defaults:    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # none | short | long

Переопределение для агента:

yaml

agents:  list:    - id: "alerts"      params:        cacheRetention: "none"

Порядок слияния конфигурации:

agents.defaults.params (глобальное значение по умолчанию — применяется ко всем моделям)
agents.defaults.models["provider/model"].params (переопределение для модели)
agents.list[].params (соответствующий id агента; переопределяет по ключу)

`contextPruning.mode: "cache-ttl"`

Удаляет старый контекст результатов инструментов после окон TTL кэша, чтобы запросы после простоя не кэшировали повторно чрезмерно большую историю.

yaml

agents:  defaults:    contextPruning:      mode: "cache-ttl"      ttl: "1h"

Полное поведение см. в Прореживание сессий.

Поддержание прогрева Heartbeat

Heartbeat может поддерживать окна кэша прогретыми и уменьшать повторные записи кэша после простоев.

yaml

agents:  defaults:    heartbeat:      every: "55m"

Heartbeat для отдельного агента поддерживается в agents.list[].heartbeat.

Поведение провайдеров

Anthropic (прямой API)

cacheRetention поддерживается.
Для auth-профилей Anthropic с API-ключом OpenClaw задает cacheRetention: "short" для ссылок на модели Anthropic, если значение не задано.
Нативные ответы Anthropic Messages предоставляют и cache_read_input_tokens, и cache_creation_input_tokens, поэтому OpenClaw может показывать и cacheRead, и cacheWrite.
Для нативных запросов Anthropic cacheRetention: "short" соответствует стандартному 5-минутному эфемерному кэшу, а cacheRetention: "long" повышает TTL до 1 часа только на прямых хостах api.anthropic.com.

OpenAI (прямой API)

Кэширование промптов выполняется автоматически на поддерживаемых новых моделях. OpenClaw не нужно внедрять маркеры кэша на уровне блоков.
OpenClaw использует prompt_cache_key, чтобы маршрутизация кэша оставалась стабильной между ходами. Прямые хосты OpenAI используют prompt_cache_retention: "24h", когда выбран cacheRetention: "long".
OpenAI-совместимые провайдеры Completions получают prompt_cache_key только когда их конфигурация модели явно задает compat.supportsPromptCacheKey: true. Передача долгого удержания — отдельная возможность: явное cacheRetention: "long" отправляет prompt_cache_retention: "24h" только когда эта compat-запись также поддерживает долгое удержание кэша. Провайдеры, такие как Mistral, могут включить ключи кэша, задав compat.supportsLongCacheRetention: false, чтобы подавить поле долгого удержания. cacheRetention: "none" подавляет оба поля.
Ответы OpenAI предоставляют кэшированные токены промпта через usage.prompt_tokens_details.cached_tokens (или input_tokens_details.cached_tokens в событиях Responses API). OpenClaw сопоставляет это с cacheRead.
OpenAI не предоставляет отдельный счетчик токенов записи кэша, поэтому cacheWrite остается 0 на путях OpenAI, даже когда провайдер прогревает кэш.
OpenAI возвращает полезные заголовки трассировки и ограничений скорости, такие как x-request-id, openai-processing-ms и x-ratelimit-*, но учет попаданий в кэш должен идти из полезной нагрузки использования, а не из заголовков.
На практике OpenAI часто ведет себя как кэш начального префикса, а не как Anthropic-стиль повторного использования всей перемещающейся истории. Стабильные текстовые ходы с длинным префиксом могут выходить примерно на плато 4864 кэшированных токенов в текущих живых пробах, тогда как насыщенные инструментами или MCP-стиля транскрипты часто выходят примерно на 4608 кэшированных токенов даже при точных повторах.

Anthropic Vertex

Модели Anthropic на Vertex AI (anthropic-vertex/*) поддерживают cacheRetention так же, как прямой Anthropic.
cacheRetention: "long" соответствует реальному 1-часовому TTL кэша промптов на конечных точках Vertex AI.
Удержание кэша по умолчанию для anthropic-vertex совпадает с прямыми значениями Anthropic по умолчанию.
Запросы Vertex маршрутизируются через формирование кэша с учетом границ, чтобы повторное использование кэша оставалось согласованным с тем, что провайдеры фактически получают.

Amazon Bedrock

Ссылки на модели Anthropic Claude (amazon-bedrock/*anthropic.claude*) поддерживают явную сквозную передачу cacheRetention.
Для моделей Bedrock не Anthropic во время выполнения принудительно задается cacheRetention: "none".

Модели OpenRouter

Для ссылок на модели openrouter/anthropic/* OpenClaw внедряет Anthropic cache_control в блоки системных/разработческих промптов, чтобы улучшить повторное использование кэша промптов, только когда запрос все еще нацелен на проверенный маршрут OpenRouter (openrouter на его конечной точке по умолчанию или любой provider/base URL, который разрешается в openrouter.ai).

Для ссылок на модели openrouter/deepseek/*, openrouter/moonshot*/* и openrouter/zai/* разрешен contextPruning.mode: "cache-ttl", потому что OpenRouter автоматически обрабатывает кэширование промптов на стороне провайдера. OpenClaw не внедряет маркеры Anthropic cache_control в эти запросы.

Построение кэша DeepSeek выполняется по принципу best-effort и может занять несколько секунд. Немедленный следующий запрос все еще может показывать cached_tokens: 0; проверяйте повторным запросом с тем же префиксом после короткой задержки и используйте usage.prompt_tokens_details.cached_tokens как сигнал попадания в кэш.

Если перенаправить модель на произвольный OpenAI-совместимый proxy URL, OpenClaw прекращает внедрять эти специфичные для OpenRouter маркеры кэша Anthropic.

Другие провайдеры

Если провайдер не поддерживает этот режим кэша, cacheRetention не имеет эффекта.

Прямой API Google Gemini

Прямой транспорт Gemini (api: "google-generative-ai") сообщает о попаданиях в кэш через вышестоящий cachedContentTokenCount; OpenClaw сопоставляет это с cacheRead.
Когда cacheRetention задан для прямой модели Gemini, OpenClaw автоматически создает, повторно использует и обновляет ресурсы cachedContents для системных промптов в запусках Google AI Studio. Это означает, что больше не нужно вручную предварительно создавать cached-content handle.
Вы по-прежнему можете передать уже существующий cached-content handle Gemini как params.cachedContent (или устаревший params.cached_content) в настроенной модели.
Это отдельно от кэширования префиксов промптов Anthropic/OpenAI. Для Gemini OpenClaw управляет нативным для провайдера ресурсом cachedContents, а не внедряет маркеры кэша в запрос.

Использование Gemini CLI

Вывод Gemini CLI stream-json может показывать попадания в кэш через stats.cached; OpenClaw сопоставляет это с cacheRead. Устаревшие переопределения --output-format json используют ту же нормализацию использования.
Если CLI опускает прямое значение stats.input, OpenClaw выводит входные токены из stats.input_tokens - stats.cached.
Это только нормализация использования. Это не означает, что OpenClaw создает маркеры кэша промптов в стиле Anthropic/OpenAI для Gemini CLI.

Граница кэша системного промпта

OpenClaw разделяет системный промпт на стабильный префикс и изменчивый суффикс, разделенные внутренней границей cache-prefix. Содержимое выше границы (определения инструментов, метаданные Skills, файлы рабочей области и другой относительно статичный контекст) упорядочивается так, чтобы оставаться побайтно идентичным между ходами. Содержимое ниже границы (например, HEARTBEAT.md, временные метки времени выполнения и другие метаданные для отдельного хода) может изменяться без инвалидации кэшированного префикса.

Ключевые проектные решения:

Стабильные файлы project-context рабочей области упорядочиваются перед HEARTBEAT.md, чтобы изменения Heartbeat не сбивали стабильный префикс.
Граница применяется при формировании транспорта семейств Anthropic, OpenAI, Google и CLI, чтобы все поддерживаемые провайдеры получали пользу от одинаковой стабильности префикса.
Запросы Codex Responses и Anthropic Vertex маршрутизируются через формирование кэша с учетом границ, чтобы повторное использование кэша оставалось согласованным с тем, что провайдеры фактически получают.
Отпечатки системных промптов нормализуются (пробелы, окончания строк, добавленный hooks контекст, порядок возможностей времени выполнения), чтобы семантически неизмененные промпты использовали общий KV/кэш между ходами.

Если после изменения конфигурации или рабочей области вы видите неожиданные всплески cacheWrite, проверьте, попадает ли изменение выше или ниже границы кэша. Перемещение изменчивого содержимого ниже границы (или его стабилизация) часто решает проблему.

Защитные механизмы стабильности кэша OpenClaw

OpenClaw также сохраняет несколько чувствительных к кэшу форм полезной нагрузки детерминированными до того, как запрос дойдет до провайдера:

Каталоги инструментов Bundle MCP детерминированно сортируются перед регистрацией инструментов, поэтому изменения порядка listTools() не меняют блок инструментов и не сбивают префиксы кэша промптов.
Устаревшие сессии с сохраненными блоками изображений оставляют 3 последних завершенных хода без изменений; более старые уже обработанные блоки изображений могут заменяться маркером, чтобы последующие запросы с большим количеством изображений не пересылали крупные устаревшие полезные нагрузки.

Шаблоны настройки

Смешанный трафик (рекомендуемое значение по умолчанию)

Сохраняйте долгоживущую базовую линию на основном агенте, отключайте кэширование на всплесковых агентах-уведомителях:

yaml

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long"  list:    - id: "research"      default: true      heartbeat:        every: "55m"    - id: "alerts"      params:        cacheRetention: "none"

Базовая линия с приоритетом стоимости

Задайте базовое cacheRetention: "short".
Включите contextPruning.mode: "cache-ttl".
Держите Heartbeat ниже вашего TTL только для агентов, которым полезен прогретый кэш.

Диагностика кэша

OpenClaw предоставляет специализированную диагностику cache-trace для встроенных запусков агентов.

Для обычной пользовательской диагностики /status и другие сводки использования могут использовать последнюю запись использования транскрипта как резервный источник для cacheRead / cacheWrite, когда живая запись сессии не содержит этих счетчиков.

Живые регрессионные тесты

OpenClaw поддерживает один объединенный живой регрессионный шлюз кэша для повторяющихся префиксов, ходов с инструментами, ходов с изображениями, транскриптов инструментов в стиле MCP и Anthropic-контроля без кэша.

src/agents/live-cache-regression.live.test.ts
src/agents/live-cache-regression-baseline.ts

Запустите узкий живой шлюз с:

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

Файл базовой линии хранит самые свежие наблюдаемые живые числа, а также специфичные для провайдера регрессионные нижние пороги, используемые тестом. Runner также использует свежие для каждого запуска идентификаторы сессий и пространства имен промптов, чтобы предыдущее состояние кэша не загрязняло текущую регрессионную выборку.

Эти тесты намеренно не используют одинаковые критерии успешности для разных провайдеров.

Ожидания для проверок Anthropic с реальными сервисами

Ожидайте явные записи прогрева через cacheWrite.
Ожидайте почти полное повторное использование истории при повторных ходах, потому что управление кешем Anthropic продвигает точку разрыва кеша по разговору.
Текущие проверки с реальными сервисами по-прежнему используют высокие пороги доли попаданий для стабильных, инструментальных и графических путей.

Ожидания для проверок OpenAI с реальными сервисами

Ожидайте только cacheRead. cacheWrite остается 0.
Рассматривайте повторное использование кеша на повторных ходах как плато, специфичное для провайдера, а не как подвижное повторное использование полной истории в стиле Anthropic.
Текущие проверки с реальными сервисами используют консервативные нижние пороги, полученные из наблюдаемого поведения с реальным сервисом на gpt-5.4-mini:
- стабильный префикс: cacheRead >= 4608, доля попаданий >= 0.90
- транскрипт инструмента: cacheRead >= 4096, доля попаданий >= 0.85
- транскрипт изображения: cacheRead >= 3840, доля попаданий >= 0.82
- транскрипт в стиле MCP: cacheRead >= 4096, доля попаданий >= 0.85

Свежая объединенная проверка с реальными сервисами от 2026-04-04 дала:

стабильный префикс: cacheRead=4864, доля попаданий 0.966
транскрипт инструмента: cacheRead=4608, доля попаданий 0.896
транскрипт изображения: cacheRead=4864, доля попаданий 0.954
транскрипт в стиле MCP: cacheRead=4608, доля попаданий 0.891

Недавнее локальное время выполнения объединенной проверки по настенным часам составляло около 88s.

Почему проверки различаются:

Anthropic предоставляет явные точки разрыва кеша и подвижное повторное использование истории разговора.
Кеширование промптов OpenAI по-прежнему чувствительно к точному префиксу, но эффективный повторно используемый префикс в реальном трафике Responses может выходить на плато раньше полного промпта.
Поэтому сравнение Anthropic и OpenAI по единому процентному порогу для разных провайдеров создает ложные регрессии.

Конфигурация `diagnostics.cacheTrace`

yaml

diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional    includeMessages: false # default true    includePrompt: false # default true    includeSystem: false # default true

Значения по умолчанию:

filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
includeMessages: true
includePrompt: true
includeSystem: true

Переключатели окружения для разовой отладки

OPENCLAW_CACHE_TRACE=1 включает трассировку кеша.
OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl переопределяет путь вывода.
OPENCLAW_CACHE_TRACE_MESSAGES=0|1 переключает захват полной полезной нагрузки сообщений.
OPENCLAW_CACHE_TRACE_PROMPT=0|1 переключает захват текста промпта.
OPENCLAW_CACHE_TRACE_SYSTEM=0|1 переключает захват системного промпта.

Что проверять

События трассировки кеша имеют формат JSONL и включают промежуточные снимки, такие как session:loaded, prompt:before, stream:context и session:after.
Влияние токенов кеша для каждого хода видно в обычных поверхностях использования через cacheRead и cacheWrite (например, /usage full и сводки использования сессии).
Для Anthropic ожидайте и cacheRead, и cacheWrite, когда кеширование активно.
Для OpenAI ожидайте cacheRead при попаданиях в кеш, а cacheWrite должен оставаться 0; OpenAI не публикует отдельное поле токенов записи в кеш.
Если вам нужна трассировка запросов, логируйте идентификаторы запросов и заголовки ограничения скорости отдельно от метрик кеша. Текущий вывод трассировки кеша OpenClaw сосредоточен на форме промпта/сессии и нормализованном использовании токенов, а не на сырых заголовках ответов провайдера.

Быстрое устранение неполадок

Высокий cacheWrite на большинстве ходов: проверьте изменчивые входные данные системного промпта и убедитесь, что модель/провайдер поддерживает ваши настройки кеша.
Высокий cacheWrite на Anthropic: часто означает, что точка разрыва кеша попадает на содержимое, которое меняется при каждом запросе.
Низкий cacheRead у OpenAI: убедитесь, что стабильный префикс находится в начале, повторяемый префикс содержит не менее 1024 токенов, а один и тот же prompt_cache_key повторно используется для ходов, которые должны разделять кеш.
Нет эффекта от cacheRetention: подтвердите, что ключ модели совпадает с agents.defaults.models["provider/model"].
Запросы Bedrock Nova/Mistral с настройками кеша: ожидается принудительная установка runtime в none.

Связанные документы:

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

Was this useful?

Кэширование промптов

Основные параметры

`cacheRetention` (глобальное значение по умолчанию, модель и отдельный агент)

`contextPruning.mode: "cache-ttl"`

Поддержание прогрева Heartbeat

Поведение провайдеров

Anthropic (прямой API)

OpenAI (прямой API)

Anthropic Vertex

Amazon Bedrock

Модели OpenRouter

Другие провайдеры

Прямой API Google Gemini

Использование Gemini CLI

Граница кэша системного промпта

Защитные механизмы стабильности кэша OpenClaw

Шаблоны настройки

Смешанный трафик (рекомендуемое значение по умолчанию)

Базовая линия с приоритетом стоимости

Диагностика кэша

Живые регрессионные тесты

Ожидания для проверок Anthropic с реальными сервисами

Ожидания для проверок OpenAI с реальными сервисами

Конфигурация `diagnostics.cacheTrace`

Переключатели окружения для разовой отладки

Что проверять

Быстрое устранение неполадок

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

On this page

Molty

Основные параметры

cacheRetention (глобальное значение по умолчанию, модель и отдельный агент)

contextPruning.mode: "cache-ttl"

Поддержание прогрева Heartbeat

Поведение провайдеров

Anthropic (прямой API)

OpenAI (прямой API)

Anthropic Vertex

Amazon Bedrock

Модели OpenRouter

Другие провайдеры

Прямой API Google Gemini

Использование Gemini CLI

Граница кэша системного промпта

Защитные механизмы стабильности кэша OpenClaw

Шаблоны настройки

Смешанный трафик (рекомендуемое значение по умолчанию)

Базовая линия с приоритетом стоимости

Диагностика кэша

Живые регрессионные тесты

Ожидания для проверок Anthropic с реальными сервисами

Ожидания для проверок OpenAI с реальными сервисами

Конфигурация diagnostics.cacheTrace

Переключатели окружения для разовой отладки

Что проверять

Быстрое устранение неполадок

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

On this page

`cacheRetention` (глобальное значение по умолчанию, модель и отдельный агент)

`contextPruning.mode: "cache-ttl"`

Конфигурация `diagnostics.cacheTrace`