​

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

• Кешування промптів Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Кешування промптів OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Заголовки API OpenAI та ID запитів: https://developers.openai.com/api/reference/overview
• ID запитів і помилки 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 (відповідний id агента; перевизначення за ключем)

​

contextPruning.mode: "cache-ttl"

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

​

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

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

​

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

​

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

​

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

​

Прямий 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.

​

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

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

​

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

• Каталоги інструментів 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 лише для агентів, яким корисний теплий кеш.

​

Діагностика кешу

​

Живі регресійні тести

• 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

​

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

• стабільний префікс: cacheRead=4864, коефіцієнт попадань 0.966
• транскрипт інструментів: cacheRead=4608, коефіцієнт попадань 0.896
• транскрипт зображень: cacheRead=4864, коефіцієнт попадань 0.954
• транскрипт у стилі MCP: cacheRead=4608, коефіцієнт попадань 0.891

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