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

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

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

Ссылки на документацию поставщиков:

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

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

cacheRetention

Значения: "none" | "short" | "long". Можно настроить как глобальное значение по умолчанию, отдельно для каждой модели и для каждого агента. "standard" не является псевдонимом; используйте "short" для стандартного окна кэширования поставщика. Недопустимые значения игнорируются с предупреждением.

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 требуется явное значение).
• Собственные ответы 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: зачастую это означает, что точка разделения кэша приходится на содержимое, изменяющееся при каждом запросе.
• Низкое значение cacheRead в OpenAI: убедитесь, что стабильный префикс находится в начале, повторяющийся префикс содержит не менее 1024 токенов, а для ходов, которые должны использовать общий кэш, повторно используется один и тот же prompt_cache_key.
• cacheRetention не действует: убедитесь, что ключ модели соответствует agents.defaults.models["provider/model"].
• Запросы Bedrock Nova с параметрами кэша: ожидаемое поведение — во время выполнения они не обеспечивают сохранение кэша.

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

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

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

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