--- read_when: - Ви хочете зменшити витрати токенів промпта завдяки збереженню кешу - Вам потрібна поведінка кешу для кожного агента в багатоагентних конфігураціях - Ви налаштовуєте heartbeat і відсікання cache-ttl разом summary: Параметри кешування промптів, порядок злиття, поведінка провайдера та шаблони налаштування title: Кешування промптів x-i18n: generated_at: "2026-07-01T20:36:23Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 3189cc734bbee14236e6303aca99aca512732989ffd01612ae635608a2471e60 source_path: reference/prompt-caching.md workflow: 16 --- Кешування промптів означає, що провайдер моделі може повторно використовувати незмінені префікси промпта (зазвичай системні/розробницькі інструкції та інший стабільний контекст) між ходами замість повторної обробки щоразу. OpenClaw нормалізує використання провайдера в `cacheRead` і `cacheWrite`, коли upstream 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) - Заголовки OpenAI API та ідентифікатори запитів: [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 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` (відповідний ідентифікатор агента; перевизначає за ключем) ### `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-ключ OpenClaw задає `cacheRetention: "short"` для посилань на моделі Anthropic, якщо значення не встановлено. - Відповіді нативних Messages Anthropic надають і `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"` лише тоді, коли цей запис сумісності також підтримує довге утримання кешу. Провайдери на кшталт Mistral можуть увімкнути ключі кешу, задавши `compat.supportsLongCacheRetention: false`, щоб приглушити поле довгого утримання. `cacheRetention: "none"` приглушує обидва поля. - Відповіді OpenAI надають кешовані токени промпта через `usage.prompt_tokens_details.cached_tokens` (або `input_tokens_details.cached_tokens` у подіях Responses API). OpenClaw відображає це в `cacheRead`. - Використання GPT-5.6 Responses також може надавати `input_tokens_details.cache_write_tokens`. OpenClaw відображає це в `cacheWrite` і оцінює за тарифом запису кешу моделі; Responses, які пропускають це поле, залишають `cacheWrite` на `0`. - 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 година на endpoint 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` на його типовому endpoint або будь-який провайдер/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"`) повідомляє про влучання в кеш через upstream `cachedContentTokenCount`; OpenClaw відображає це в `cacheRead`. - Коли `cacheRetention` задано для прямої моделі Gemini, OpenClaw автоматично створює, повторно використовує та оновлює ресурси `cachedContents` для системних промптів під час запусків Google AI Studio. Це означає, що більше не потрібно вручну попередньо створювати дескриптор кешованого вмісту. - Ви все ще можете передати наявний дескриптор кешованого вмісту 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 розділяє системний промпт на **стабільний префікс** і **мінливий суфікс**, відокремлені внутрішньою межею префікса кешу. Вміст над межею (визначення інструментів, метадані Skills, файли робочого простору та інший відносно статичний контекст) упорядковується так, щоб залишатися байт-ідентичним між ходами. Вміст під межею (наприклад `HEARTBEAT.md`, runtime timestamps та інші метадані окремого ходу) може змінюватися без інвалідації кешованого префікса. Ключові проєктні рішення: - Стабільні файли контексту проєкту робочого простору впорядковуються перед `HEARTBEAT.md`, щоб зміни Heartbeat не руйнували стабільний префікс. - Межа застосовується для формування транспорту Anthropic-family, OpenAI-family, Google і CLI, щоб усі підтримувані провайдери отримували користь від тієї самої стабільності префікса. - Запити Codex Responses і Anthropic Vertex маршрутизуються через формування кешу з урахуванням меж, щоб повторне використання кешу залишалося узгодженим із тим, що провайдери фактично отримують. - Відбитки системних промптів нормалізуються (пробіли, закінчення рядків, контекст, доданий hook, порядок runtime capability), щоб семантично незмінені промпти спільно використовували 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 надає спеціалізовану діагностику трасування кешу для вбудованих запусків агентів. Для звичайної користувацької діагностики `/status` та інші підсумки використання можуть використовувати найновіший запис використання з транскрипта як резервне джерело для `cacheRead` / `cacheWrite`, коли живий запис сеансу не має цих лічильників. ## Живі регресійні тести OpenClaw підтримує один об'єднаний живий регресійний шлюз кешу для повторюваних префіксів, ходів інструментів, ходів із зображеннями, MCP-подібних транскриптів інструментів і Anthropic-контролю без кешу. - `src/agents/live-cache-regression.live.test.ts` - `src/agents/live-cache-regression-baseline.ts` Запустіть вузький живий шлюз так: ```sh OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache ``` Файл базового рівня зберігає найновіші спостережені live-числа плюс специфічні для провайдера нижні межі регресії, які використовує тест. Runner також використовує свіжі для кожного запуску ідентифікатори сесій і простори назв промптів, щоб попередній стан кешу не забруднював поточну регресійну вибірку. Ці тести навмисно не використовують однакові критерії успіху для всіх провайдерів. ### Live-очікування Anthropic - Очікуйте явні warmup-записи через `cacheWrite`. - Очікуйте майже повного повторного використання історії на повторних ходах, бо cache control Anthropic просуває точку розриву кешу крізь розмову. - Поточні live-твердження все ще використовують високі пороги частки влучань для стабільних, інструментальних та зображувальних шляхів. ### Live-очікування OpenAI - Очікуйте лише `cacheRead`. `cacheWrite` залишається `0`. - Розглядайте повторне використання кешу на повторних ходах як специфічне для провайдера плато, а не як повторне використання повної рухомої історії в стилі Anthropic. - Поточні live-твердження використовують консервативні перевірки нижніх меж, виведені зі спостереженої live-поведінки на `gpt-5.4-mini`: - стабільний префікс: `cacheRead >= 4608`, частка влучань `>= 0.90` - транскрипт інструменту: `cacheRead >= 4096`, частка влучань `>= 0.85` - транскрипт зображення: `cacheRead >= 3840`, частка влучань `>= 0.82` - транскрипт у стилі MCP: `cacheRead >= 4096`, частка влучань `>= 0.85` Свіжа комбінована live-перевірка 2026-04-04 дала такі результати: - стабільний префікс: `cacheRead=4864`, частка влучань `0.966` - транскрипт інструменту: `cacheRead=4608`, частка влучань `0.896` - транскрипт зображення: `cacheRead=4864`, частка влучань `0.954` - транскрипт у стилі MCP: `cacheRead=4608`, частка влучань `0.891` Останній локальний wall-clock час для комбінованого gate становив приблизно `88s`. Чому твердження відрізняються: - Anthropic надає явні точки розриву кешу та рухоме повторне використання історії розмови. - Кешування промптів OpenAI усе ще чутливе до точного префікса, але ефективний повторно використовуваний префікс у live-трафіку 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 і містять staged snapshots на кшталт `session:loaded`, `prompt:before`, `stream:context` і `session:after`. - Вплив кеш-токенів для кожного ходу видно у звичайних поверхнях використання через `cacheRead` і `cacheWrite` (наприклад, `/usage tokens`, `/status`, зведення використання сесії та користувацькі макети `messages.usageTemplate`). - Для Anthropic очікуйте і `cacheRead`, і `cacheWrite`, коли кешування активне. - Для OpenAI очікуйте `cacheRead` під час влучань у кеш. GPT-5.6 Responses також може повідомляти `cacheWrite`, доки записуються сегменти промпта; інші payload Responses, які не містять лічильника запису, залишають його на `0`. - Якщо вам потрібне трасування запитів, логуйте ідентифікатори запитів і заголовки rate-limit окремо від метрик кешу. Поточний вивід cache-trace OpenClaw зосереджений на формі промпта/сесії та нормалізованому використанні токенів, а не на сирих заголовках відповідей провайдера. ## Швидке усунення несправностей - Високий `cacheWrite` на більшості ходів: перевірте волатильні вхідні дані системного промпта та переконайтеся, що модель/провайдер підтримує ваші налаштування кешу. - Високий `cacheWrite` на Anthropic: часто означає, що точка розриву кешу потрапляє на вміст, який змінюється в кожному запиті. - Низький `cacheRead` OpenAI: переконайтеся, що стабільний префікс стоїть на початку, повторюваний префікс має щонайменше 1024 токени, а той самий `prompt_cache_key` повторно використовується для ходів, які мають спільно використовувати кеш. - Немає ефекту від `cacheRetention`: підтвердьте, що ключ моделі відповідає `agents.defaults.models["provider/model"]`. - Запити Bedrock Nova/Mistral з налаштуваннями кешу: очікуване примусове runtime-значення `none`. Пов’язані документи: - [Anthropic](/uk/providers/anthropic) - [Використання токенів і витрати](/uk/reference/token-use) - [Обрізання сесії](/uk/concepts/session-pruning) - [Довідник конфігурації Gateway](/uk/gateway/configuration-reference) ## Пов’язане - [Використання токенів і витрати](/uk/reference/token-use) - [Використання API та витрати](/uk/reference/api-usage-costs)