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

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

Поверхні статусу також можуть відновлювати лічильники кешу з найновішого журналу використання транскрипта, коли вони відсутні в живому знімку сеансу, тож /status може й далі показувати рядок кешу після часткової втрати метаданих сеансу. Наявні ненульові живі значення кешу все ще мають пріоритет над резервними значеннями з транскрипта.

Чому це важливо: нижча вартість токенів, швидші відповіді та передбачуваніша продуктивність для довготривалих сеансів. Без кешування повторювані промпти сплачують повну вартість промпта на кожному ході, навіть коли більшість вхідних даних не змінилася.

Розділи нижче охоплюють кожен пов'язаний із кешем параметр, який впливає на повторне використання промптів і вартість токенів.

Посилання на провайдерів:

• Кешування промптів Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Кешування промптів OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Заголовки OpenAI API та ідентифікатори запитів: https://developers.openai.com/api/reference/overview
• Ідентифікатори запитів Anthropic та помилки: https://platform.claude.com/docs/en/api/errors

Основні параметри

cacheRetention (глобальне значення за замовчуванням, модель і окремий агент)

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

agents:  defaults:    params:      cacheRetention: "long" # none | short | long

Перевизначення для окремої моделі:

agents:  defaults:    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "short" # none | short | long

Перевизначення для окремого агента:

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 кешу, щоб запити після простою не кешували повторно надмірно велику історію.

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

Повну поведінку див. у Обрізання сеансу.

Heartbeat для підтримання тепла

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

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.

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

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

Тримайте довготривалу базову лінію на основному агенті, вимкніть кешування на імпульсних агентах-сповіщувачах:

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

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

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

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
• Використання токенів і витрати
• Обрізання сесії
• Довідник конфігурації Gateway

Пов’язане

• Використання токенів і витрати
• Використання API та витрати