> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

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

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

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

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

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
```

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long
```

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"
```

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

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

### `contextPruning.mode: "cache-ttl"`

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"
```

Полное поведение см. в [Прореживание сессий](/ru/concepts/session-pruning).

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

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

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`

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

```sh theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`.

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

* [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)