--- read_when: - Вы хотите снизить расход токенов промпта за счёт сохранения кеша - В конфигурациях с несколькими агентами требуется отдельное поведение кэша для каждого агента - Вы одновременно настраиваете Heartbeat и очистку по сроку жизни кэша. summary: Параметры кэширования промптов, порядок объединения, поведение провайдера и способы настройки title: Кэширование промптов x-i18n: generated_at: "2026-07-13T18:34:39Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 68f3e6ba31517a598f22cfdbe04da746a756feadc7c4c376efaa4779cbf05b31 source_path: reference/prompt-caching.md workflow: 16 --- Кэширование промптов позволяет провайдеру моделей повторно использовать неизменившийся префикс промпта (системные инструкции и инструкции разработчика, определения инструментов, другой стабильный контекст) между ходами вместо его повторной обработки при каждом запросе. Это снижает расход токенов и задержку в длительных сеансах с повторяющимся контекстом. 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) ## Основные параметры ### `cacheRetention` Значения: `"none" | "short" | "long"`. Можно настроить как глобальное значение по умолчанию, отдельно для модели и отдельно для агента. ```yaml 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 кэша, чтобы запрос после периода бездействия не кэшировал повторно чрезмерно большую историю. ```yaml agents: defaults: contextPruning: mode: "cache-ttl" ttl: "1h" ``` Полное описание поведения см. в разделе [Очистка сеансов](/ru/concepts/session-pruning). ### Поддержание кэша в прогретом состоянии с помощью Heartbeat Heartbeat может поддерживать окна кэша в прогретом состоянии и сокращать количество повторных записей в кэш после периодов бездействия. Настраивается глобально (`agents.defaults.heartbeat`) или отдельно для агента (`agents.list[].heartbeat`). ```yaml 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 при реальном использовании](#openai-live-expectations). ### 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 последних завершённых хода** остаются без изменений (учитываются все завершённые ходы, а не только содержащие изображения). Старые, уже обработанные блоки изображений заменяются текстовым маркером, чтобы последующие запросы в сеансах с большим количеством изображений не отправляли повторно крупные устаревшие полезные нагрузки. ## Варианты настройки ### Смешанный трафик (рекомендуемое значение по умолчанию) Сохраните долгоживущую базовую конфигурацию для основного агента и отключите кэширование для агентов уведомлений с неравномерной нагрузкой: ```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 выполняет одну объединённую проверку регрессий кэша в реальной среде, охватывающую повторяющиеся префиксы, ходы с инструментами, ходы с изображениями, транскрипты инструментов в стиле MCP и контрольный сценарий Anthropic без кэша. - `src/agents/live-cache-regression.live.test.ts` - `src/agents/live-cache-regression-runner.ts` - `src/agents/live-cache-regression-baseline.ts` Запуск: ```sh 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`: | Сценарий | Минимум `cacheRead` | Минимальная доля попаданий | | -------------------- | --------------------------: | -------------------------: | | Стабильный префикс | 4,608 | 0.90 | | Транскрипт инструмента | 4,096 | 0.85 | | Транскрипт с изображением | 3,840 | 0.82 | | Транскрипт в стиле MCP | 4,096 | 0.85 | Последние наблюдаемые базовые показатели (из `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` ```yaml diagnostics: cacheTrace: enabled: true filePath: "~/.openclaw/logs/cache-trace.jsonl" # необязательно includeMessages: false # по умолчанию true includePrompt: false # по умолчанию true includeSystem: false # по умолчанию true ``` Значения по умолчанию: | Ключ | Значение по умолчанию | | ----------------- | -------------------------------------------- | | `filePath` | `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl` | | `includeMessages` | `true` | | `includePrompt` | `true` | | `includeSystem` | `true` | ### Переключатели среды (для разовой отладки) | Переменная | Эффект | | ------------------------------------ | -------------------------------------------- | | `OPENCLAW_CACHE_TRACE=1` | Включает трассировку кеша | | `OPENCLAW_CACHE_TRACE_FILE=path` | Переопределяет путь вывода | | `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 tokens`, `/status`, сводках использования сеанса и пользовательских макетах `messages.usageTemplate`. - Для Anthropic при активном кешировании ожидайте как `cacheRead`, так и `cacheWrite`. - Для OpenAI при попаданиях в кеш ожидайте `cacheRead`; значение `cacheWrite` заполняется только в полезных нагрузках Responses API, которые его содержат (см. раздел [OpenAI](#openai-direct-api) выше). - 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](/ru/providers/anthropic) - [Использование токенов и расходы](/ru/reference/token-use) - [Очистка сеанса](/ru/concepts/session-pruning) - [Справочник по конфигурации Gateway](/ru/gateway/configuration-reference) ## См. также - [Использование токенов и расходы](/ru/reference/token-use) - [Использование API и расходы](/ru/reference/api-usage-costs)