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

Кешування промптів дає змогу постачальнику моделі повторно використовувати незмінений префікс промпту (системні інструкції та інструкції розробника, визначення інструментів, інший стабільний контекст) у різних ходах замість повторного опрацювання з кожним запитом. Це зменшує витрати токенів і затримку в тривалих сеансах із повторюваним контекстом.

OpenClaw нормалізує дані про використання постачальника в cacheRead і cacheWrite усюди, де API вищого рівня надає ці лічильники. Зведення використання (/status і подібні) повертаються до останнього запису про використання у транскрипті, коли у знімку активного сеансу немає лічильників кешу; ненульове активне значення завжди має перевагу над резервним.

Довідкові матеріали постачальників:

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

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

cacheRetention

Значення: "none" | "short" | "long". Можна налаштувати як глобальне типове значення, окремо для кожної моделі та кожного агента. "standard" не є псевдонімом; використовуйте "short" для типового вікна кешу постачальника. Недійсні значення ігноруються з попередженням.

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

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

Повний опис поведінки див. у розділі Очищення сеансу.

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

Heartbeat може підтримувати вікна кешу в активному стані та зменшувати кількість повторних записів до кешу після періодів бездіяльності. Налаштовується глобально (agents.defaults.heartbeat) або окремо для кожного агента (agents.list[].heartbeat).

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 потребують явного значення).
• Власні відповіді 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 у реальному середовищі.

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/preview, що не відповідають цьому префіксу, наприклад 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 останні завершені ходи залишаються без змін (ураховуються всі завершені ходи, а не лише ті, що містять зображення). Старіші вже оброблені блоки зображень замінюються текстовим маркером, щоб подальші запити після роботи із зображеннями не надсилали повторно великі застарілі корисні навантаження.

Схеми налаштування

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

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

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

Запустіть її так:

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

Файл базового рівня зберігає останні спостережені актуальні показники, а також специфічні для кожного провайдера мінімальні пороги регресії, з якими звіряється тест. Кожен запуск використовує нові ідентифікатори сеансів та простори назв запитів, окремі для цього запуску, щоб попередній стан кешу не впливав на поточну вибірку. Для Anthropic і OpenAI застосовуються різні правила: недосягнення порога Anthropic є критичною регресією (тест завершується невдало), тоді як недосягнення порога OpenAI використовується лише для спостереження (фіксується як попередження й не спричиняє невдалого завершення запуску). Вони не мають єдиного спільного для провайдерів порога.

Очікування для актуального середовища Anthropic

• Очікуються явні записи прогрівання через cacheWrite.
• Під час повторних ходів очікується майже повне повторне використання історії, оскільки керування кешем Anthropic пересуває точку розриву кешу впродовж розмови.
• Базові мінімальні пороги для стабільних сценаріїв, а також сценаріїв з інструментами, зображеннями та в стилі MCP є обов’язковими бар’єрами регресії.

Очікування для актуального середовища OpenAI

• Очікується лише cacheRead; cacheWrite залишається 0 у Chat Completions.
• Повторне використання кешу під час повторних ходів слід розглядати як специфічне для провайдера плато, а не як характерне для Anthropic рухоме повторне використання повної історії.
• Мінімальні пороги використовуються лише для спостереження (недосягнення реєструється як попередження, а не як невдале завершення тесту) і виведені зі спостереженої актуальної поведінки на gpt-5.4-mini:

Останні спостережені базові показники (з 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

diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # необов’язково    includeMessages: false # типове значення true    includePrompt: false # типове значення true    includeSystem: false # типове значення true

Типові значення:

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

Що перевіряти

• Події трасування кешу мають формат 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 також повертає заголовки трасування й обмеження частоти, як-от 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
• Використання токенів і витрати
• Очищення сеансу
• Довідник із конфігурації Gateway

Пов’язані матеріали

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