---
read_when:
    - Ви хочете зменшити витрати на токени промптів завдяки збереженню кешу
    - Вам потрібна поведінка кешу для кожного агента окремо в багатoагентних конфігураціях
    - Ви налаштовуєте heartbeat і обрізання cache-ttl разом
summary: Параметри кешування промптів, порядок злиття, поведінка провайдерів і шаблони налаштування
title: Кешування промптів
x-i18n:
    generated_at: "2026-04-05T18:17:37Z"
    model: gpt-5.4
    provider: openai
    source_hash: 13d5f3153b6593ae22cd04a6c2540e074cf15df9f1990fc5b7184fe803f4a1bd
    source_path: reference/prompt-caching.md
    workflow: 15
---

# Кешування промптів

Кешування промптів означає, що провайдер моделі може повторно використовувати незмінні префікси промпта (зазвичай системні/розробницькі інструкції та інший стабільний контекст) між ходами замість повторної обробки щоразу. 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 та ID запитів: [https://developers.openai.com/api/reference/overview](https://developers.openai.com/api/reference/overview)
- ID запитів і помилки Anthropic: [https://platform.claude.com/docs/en/api/errors](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"
```

Порядок злиття конфігурації:

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

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

Обрізає старий контекст результатів інструментів після вікон TTL кешу, щоб запити після простою не кешували заново надто велику історію.

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

Повну поведінку див. у [Обрізання сесій](/uk/concepts/session-pruning).

### Підігрів через heartbeat

Heartbeat може підтримувати вікна кешу теплими та зменшувати повторні записи в кеш після періодів бездіяльності.

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

Heartbeat для окремого агента підтримується в `agents.list[].heartbeat`.

## Поведінка провайдерів

### Anthropic (прямий API)

- `cacheRetention` підтримується.
- Для профілів автентифікації Anthropic API-key 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`, щоб маршрутизація кешу залишалася стабільною між ходами, і використовує `prompt_cache_retention: "24h"` лише коли `cacheRetention: "long"` вибрано на прямих хостах OpenAI.
- Відповіді 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-*`, але облік попадань у кеш слід брати з payload використання, а не із заголовків.
- На практиці OpenAI часто поводиться як кеш початкового префікса, а не як повторне використання всієї рухомої історії в стилі Anthropic. Ходи зі стабільним довгим префіксом можуть виходити на плато близько `4864` кешованих токенів у поточних живих пробах, тоді як транскрипти з інтенсивним використанням інструментів або в стилі MCP часто виходять на плато близько `4608` кешованих токенів навіть за точного повторення.

### Anthropic Vertex

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

### Amazon Bedrock

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

### Моделі Anthropic через OpenRouter

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

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

### Інші провайдери

Якщо провайдер не підтримує цей режим кешу, `cacheRetention` не матиме ефекту.

### Прямий API Google Gemini

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

### Використання JSON Gemini CLI

- JSON-вивід Gemini CLI також може показувати попадання в кеш через `stats.cached`;
  OpenClaw відображає це в `cacheRead`.
- Якщо CLI не містить прямого значення `stats.input`, OpenClaw обчислює вхідні токени
  як `stats.input_tokens - stats.cached`.
- Це лише нормалізація використання. Це не означає, що OpenClaw створює
  маркери кешу промптів у стилі Anthropic/OpenAI для Gemini CLI.

## Межа кешу системного промпта

OpenClaw розділяє системний промпт на **стабільний префікс** і **мінливий
суфікс**, розділені внутрішньою межею префікса кешу. Вміст над
межею (визначення інструментів, метадані Skills, файли робочого простору та інший
відносно статичний контекст) упорядковується так, щоб залишатися побайтно однаковим між ходами.
Вміст під межею (наприклад, `HEARTBEAT.md`, часові позначки середовища виконання та
інші метадані кожного ходу) може змінюватися без інвалідизації кешованого
префікса.

Ключові проєктні рішення:

- Стабільні файли контексту проєкту робочого простору впорядковуються перед `HEARTBEAT.md`, щоб
  зміни heartbeat не ламали стабільний префікс.
- Межа застосовується в формуванні кешу для сімейства Anthropic, сімейства OpenAI, Google і CLI-транспорту, щоб усі підтримувані провайдери отримували вигоду від однакової стабільності префікса.
- Запити Codex Responses і Anthropic Vertex маршрутизуються через
  формування кешу з урахуванням меж, щоб повторне використання кешу залишалося узгодженим із тим, що провайдери фактично отримують.
- Відбитки системного промпта нормалізуються (пробіли, завершення рядків,
  контекст, доданий хуками, порядок можливостей середовища виконання), щоб
  семантично незмінні промпти спільно використовували KV/кеш між ходами.

Якщо ви бачите неочікувані сплески `cacheWrite` після зміни конфігурації чи робочого простору,
перевірте, чи ця зміна потрапляє вище чи нижче межі кешу. Переміщення
мінливого вмісту нижче межі (або його стабілізація) часто вирішує
проблему.

## Захист стабільності кешу в OpenClaw

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

- Каталоги інструментів bundle MCP сортуються детерміновано перед
  реєстрацією інструментів, щоб зміни порядку `listTools()` не спричиняли змін у блоці інструментів і
  не ламали префікси кешу промптів.
- У застарілих сесіях зі збереженими блоками зображень **3 найновіші
  завершені ходи** зберігаються без змін; старіші вже оброблені блоки зображень можуть бути
  замінені маркером, щоб подальші запити з великою кількістю зображень не продовжували повторно надсилати великі
  застарілі payload.

## Шаблони налаштування

### Змішаний трафік (рекомендоване значення за замовчуванням)

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

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

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

Запустіть вузький живий gate так:

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

Базовий файл зберігає останні спостережувані живі значення та специфічні для провайдерів регресійні нижні межі, які використовує тест.
Runner також використовує нові ID сесій і простори імен промптів для кожного запуску, щоб попередній стан кешу не забруднював поточну регресійну вибірку.

Ці тести навмисно не використовують однакові критерії успішності для всіх провайдерів.

### Живі очікування 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`

Нещодавній локальний час виконання для комбінованого gate становив близько `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`

### Перемикачі env (разове налагодження)

- `OPENCLAW_CACHE_TRACE=1` вмикає трасування кешу.
- `OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl` перевизначає шлях виводу.
- `OPENCLAW_CACHE_TRACE_MESSAGES=0|1` перемикає захоплення повного payload повідомлень.
- `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 не публікує окремого поля токенів запису в кеш.
- Якщо вам потрібне трасування запитів, журналюйте ID запитів і заголовки обмеження швидкості окремо від метрик кешу. Поточний вивід cache-trace в OpenClaw зосереджений на формі промпта/сесії та нормалізованому використанні токенів, а не на сирих заголовках відповіді провайдера.

## Швидке усунення проблем

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

Пов’язані документи:

- [Anthropic](/uk/providers/anthropic)
- [Використання токенів і витрати](/reference/token-use)
- [Обрізання сесій](/uk/concepts/session-pruning)
- [Довідник із конфігурації шлюзу](/uk/gateway/configuration-reference)
