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

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

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

Справочные материалы по провайдерам:

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

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

cacheRetention

Значения: "none" | "short" | "long". Можно настроить как глобальное значение по умолчанию, отдельно для модели и отдельно для агента.

agents:  defaults:    params:      cacheRetention: "long" # none | short | long    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # переопределяет глобальное значение по умолчанию для этой модели  list:    - id: "alerts"      params:        cacheRetention: "none" # переопределяет оба значения по умолчанию для этого агента

Порядок объединения (более позднее значение имеет приоритет):

1. agents.defaults.params — глобальное значение по умолчанию для всех моделей
2. agents.defaults.models["provider/model"].params — переопределение для отдельной модели
3. agents.list[].params — переопределение для отдельного агента, сопоставляемое по идентификатору агента

Источник: src/agents/embedded-agent-runner/extra-params.ts (resolveExtraParams).

contextPruning.mode: "cache-ttl"

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

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

Полное описание поведения см. в разделе Очистка сеансов.

Поддержание кэша в прогретом состоянии с помощью Heartbeat

Heartbeat может поддерживать окна кэша в прогретом состоянии и сокращать количество повторных записей в кэш после периодов бездействия. Настраивается глобально (agents.defaults.heartbeat) или отдельно для агента (agents.list[].heartbeat).

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

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

Anthropic (прямой API и Vertex AI)

• cacheRetention поддерживается для провайдеров anthropic и anthropic-vertex, а также для моделей Claude в amazon-bedrock и пользовательских конечных точках, совместимых с anthropic-messages, если явно задано cacheRetention.
• Если значение не задано, OpenClaw устанавливает cacheRetention: "short" для прямого подключения к Anthropic (только для провайдеров anthropic и anthropic-vertex; другие маршруты семейства Anthropic требуют явного значения).
• Ответы нативного API Anthropic Messages предоставляют cache_read_input_tokens и cache_creation_input_tokens, которые сопоставляются с cacheRead и cacheWrite.
• cacheRetention: "short" соответствует эфемерному кэшу по умолчанию на 5 минут. При явной настройке cacheRetention: "long" запрашивает TTL длительностью 1 час (cache_control: { type: "ephemeral", ttl: "1h" }). Неявное или заданное через переменную окружения длительное хранение (OPENCLAW_CACHE_RETENTION=long без явного cacheRetention) увеличивает TTL до 1 часа только на узлах api.anthropic.com или Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); на остальных узлах сохраняется 5-минутный кэш.

Источник: src/agents/anthropic-payload-policy.ts (resolveAnthropicEphemeralCacheControl, isLongTtlEligibleEndpoint).

OpenAI (прямой API)

• Кэширование промптов выполняется автоматически для поддерживаемых современных моделей; OpenClaw не добавляет маркеры кэширования на уровне блоков.
• OpenClaw отправляет prompt_cache_key, чтобы маршрутизация кэша оставалась стабильной между ходами. Узлы прямого подключения api.openai.com получают это автоматически. Для прокси, совместимых с OpenAI (oMLX, llama.cpp, пользовательские конечные точки), требуется compat.supportsPromptCacheKey: true в конфигурации модели для явного включения — для прокси это никогда не определяется автоматически.
• prompt_cache_retention: "24h" добавляется только при выборе cacheRetention: "long" и если определённая конечная точка поддерживает как ключ кэша, так и длительное хранение (compat.supportsLongCacheRetention, по умолчанию — true; профили совместимости Together AI и Cloudflare отключают его). cacheRetention: "none" запрещает отправку обоих полей.
• Попадания в кэш отображаются через usage.prompt_tokens_details.cached_tokens (Chat Completions) или input_tokens_details.cached_tokens (Responses API) и сопоставляются с cacheRead.
• Полезная нагрузка Responses API также может предоставлять input_tokens_details.cache_write_tokens, который сопоставляется с cacheWrite и тарифицируется по ставке записи в кэш для модели; если полезная нагрузка Responses не содержит это поле, cacheWrite сохраняет значение 0. API Chat Completions OpenAI не документирует и не возвращает счётчик cache_write_tokens, однако OpenClaw всё равно считывает там prompt_tokens_details.cache_write_tokens для прокси, совместимых с OpenRouter, и прокси в стиле DeepSeek, которые сообщают отдельное количество записей.
• На практике OpenAI работает скорее как кэш начального префикса, чем как механизм повторного использования всей перемещающейся истории Anthropic — см. ниже раздел Ожидаемое поведение OpenAI при реальном использовании.

Amazon Bedrock

• Ссылки на модели Anthropic Claude (amazon-bedrock/*anthropic.claude*, а также префиксы системных профилей логического вывода AWS us./eu./global.anthropic.claude*) поддерживают явную сквозную передачу cacheRetention.
• Для моделей Bedrock не от Anthropic (например, amazon.nova-*) во время выполнения всегда отключается хранение кэша независимо от настроенного значения cacheRetention.
• Для непрозрачных ARN профилей логического вывода приложений Bedrock (идентификаторов профилей, не содержащих claude) хранение кэша также отключается, если явно не задано cacheRetention, поскольку семейство модели невозможно определить только по ARN.

OpenRouter

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

contextPruning.mode: "cache-ttl" разрешено для ссылок на модели openrouter/anthropic/*, openrouter/deepseek/*, openrouter/moonshot/*, openrouter/moonshotai/* и openrouter/zai/*, поскольку эти маршруты обрабатывают кэширование промптов на стороне провайдера без маркеров, добавляемых OpenClaw.

Источник: extensions/openrouter/index.ts (OPENROUTER_CACHE_TTL_MODEL_PREFIXES).

Создание кэша DeepSeek в OpenRouter выполняется по мере возможности и может занять несколько секунд; немедленный повторный запрос всё ещё может показывать cached_tokens: 0. Проверьте результат, повторив запрос с тем же префиксом после небольшой задержки и используя usage.prompt_tokens_details.cached_tokens как признак попадания в кэш.

Google Gemini (прямой API)

• Прямой транспорт Gemini (api: "google-generative-ai") сообщает о попаданиях в кэш через вышестоящее поле cachedContentTokenCount, сопоставляемое с cacheRead.
• Поддерживаемые семейства моделей: gemini-2.5* и gemini-3* (варианты Live и предварительные версии, не соответствующие этому префиксу, исключены, например gemini-live-2.5-flash-preview).
• Если для поддерживаемой модели задано cacheRetention, OpenClaw автоматически создаёт, повторно использует и обновляет ресурс cachedContents для системного промпта — вручную указывать дескриптор кэшированного содержимого не требуется. TTL составляет 300s для cacheRetention: "short" и 3600s для "long".
• Существующий дескриптор кэшированного содержимого Gemini по-прежнему можно передать как params.cachedContent (или устаревший params.cached_content); при явном указании дескриптора автоматическое управление кэшем полностью пропускается.
• Это отличается от кэширования префиксов промптов Anthropic и OpenAI: вместо добавления встроенных маркеров кэша OpenClaw управляет нативным ресурсом провайдера cachedContents для Gemini.

Источник: src/agents/embedded-agent-runner/google-prompt-cache.ts.

Провайдеры с CLI-обвязкой (Claude Code, Gemini CLI)

Серверные части CLI, которые создают события использования в формате JSONL (jsonlDialect: "claude-stream-json" или "gemini-stream-json"), обрабатываются общим анализатором использования. Он распознаёт несколько вариантов имён полей, включая обычный счётчик cached, сопоставляемый с cacheRead. Если полезная нагрузка JSON от CLI не содержит отдельного поля количества входных токенов, OpenClaw вычисляет его как input_tokens - cached. Это только нормализация данных об использовании — она не создаёт маркеры кэширования промптов в стиле Anthropic или OpenAI для моделей, запускаемых через CLI.

Источник: src/agents/cli-output.ts (toCliUsage).

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

Если провайдер не поддерживает ни один из описанных выше режимов кэширования, cacheRetention не действует.

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

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

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

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

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

Механизмы OpenClaw для обеспечения стабильности кэша

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

Варианты настройки

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

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

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 выполняет одну объединённую проверку регрессий кэша в реальной среде, охватывающую повторяющиеся префиксы, ходы с инструментами, ходы с изображениями, транскрипты инструментов в стиле MCP и контрольный сценарий Anthropic без кэша.

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

Запуск:

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

В базовом файле хранятся последние наблюдавшиеся реальные значения, а также зависящие от провайдера минимальные пороги регрессии, с которыми их сравнивает тест. Каждый запуск использует новые идентификаторы сеансов и пространства имён промптов, поэтому состояние кэша от предыдущих запусков не влияет на текущую выборку. Для Anthropic и OpenAI применяются разные правила: недостижение порога Anthropic считается критической регрессией (тест завершается с ошибкой), а недостижение порога OpenAI служит только для наблюдения (регистрируется как предупреждение и не приводит к сбою запуска). Единый межпровайдерный порог не используется.

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

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

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

• Ожидайте только cacheRead; в Chat Completions значение cacheWrite остаётся 0.
• Рассматривайте повторное использование кеша при повторных ходах как специфичное для провайдера плато, а не как характерное для Anthropic перемещающееся повторное использование полной истории.
• Минимальные пороги используются только для наблюдения (недостижение регистрируется как предупреждение, а не как ошибка теста) и получены из наблюдаемого поведения в реальной среде на gpt-5.4-mini:

Последние наблюдаемые базовые показатели (из live-cache-regression-baseline.ts) составили: стабильный префикс cacheRead=4864, доля попаданий 0.966; транскрипт инструмента cacheRead=4608, доля попаданий 0.896; транскрипт с изображением cacheRead=4864, доля попаданий 0.954; транскрипт в стиле MCP cacheRead=4608, доля попаданий 0.891.

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

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

diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # необязательно    includeMessages: false # по умолчанию true    includePrompt: false # по умолчанию true    includeSystem: false # по умолчанию true

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

Переключатели среды (для разовой отладки)

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

• События трассировки кеша записываются в формате JSONL с поэтапными снимками, такими как session:loaded, prompt:before, stream:context и session:after.
• Влияние кеша на количество токенов в каждом ходе видно в обычных представлениях использования: cacheRead и cacheWrite отображаются в /usage tokens, /status, сводках использования сеанса и пользовательских макетах messages.usageTemplate.
• Для Anthropic при активном кешировании ожидайте как cacheRead, так и cacheWrite.
• Для OpenAI при попаданиях в кеш ожидайте cacheRead; значение cacheWrite заполняется только в полезных нагрузках Responses API, которые его содержат (см. раздел OpenAI выше).
• OpenAI также возвращает заголовки трассировки и ограничения частоты запросов, такие как x-request-id, openai-processing-ms и x-ratelimit-*; используйте их для трассировки запросов, но данные о попаданиях в кеш следует по-прежнему получать из полезной нагрузки с информацией об использовании, а не из заголовков.

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

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

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

• Anthropic
• Использование токенов и расходы
• Очистка сеанса
• Справочник по конфигурации Gateway

См. также

• Использование токенов и расходы
• Использование API и расходы