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

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

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

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

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

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

cacheRetention

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

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; у Chat Completions значення cacheWrite залишається 0.
• Розглядайте повторне використання кешу під час повторних ходів як специфічне для постачальника плато, а не як характерне для 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: часто означає, що точка розриву кешу припадає на вміст, який змінюється з кожним запитом.
• Низьке значення cacheRead в OpenAI: переконайтеся, що стабільний префікс розташований на початку, повторюваний префікс містить щонайменше 1024 токени, а те саме значення prompt_cache_key повторно використовується для ходів, які мають спільно використовувати кеш.
• Відсутній ефект від cacheRetention: переконайтеся, що ключ моделі відповідає agents.defaults.models["provider/model"].
• Запити Bedrock Nova з параметрами кешу: це очікувана поведінка — під час виконання для них не застосовується утримання кешу.

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

• Anthropic
• Використання токенів і витрати
• Очищення сеансів
• Довідник із конфігурації Gateway

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

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