Buforowanie promptów

• Buforowanie promptów Anthropic
• Buforowanie promptów OpenAI

​

Główne ustawienia

​

cacheRetention

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # zastępuje globalną wartość domyślną dla tego modelu
  list:
    - id: "alerts"
      params:
        cacheRetention: "none" # zastępuje obie wartości domyślne dla tego agenta

1. agents.defaults.params - globalna wartość domyślna dla wszystkich modeli
2. agents.defaults.models["provider/model"].params - nadpisanie dla poszczególnego modelu
3. agents.list[].params - nadpisanie dla poszczególnego agenta, dopasowywane według identyfikatora agenta

​

contextPruning.mode: "cache-ttl"

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

​

Utrzymywanie aktywności przez Heartbeat

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

​

Zachowanie dostawcy

​

Anthropic (bezpośrednie API i Vertex AI)

• cacheRetention jest obsługiwane dla dostawców anthropic i anthropic-vertex, a także dla modeli Claude w amazon-bedrock i niestandardowych punktów końcowych zgodnych z anthropic-messages, gdy cacheRetention jest ustawione jawnie.
• Gdy ta wartość nie jest ustawiona, OpenClaw inicjalizuje cacheRetention: "short" dla bezpośredniego Anthropic (wyłącznie dostawcy anthropic i anthropic-vertex; inne ścieżki z rodziny Anthropic wymagają jawnej wartości).
• Natywne odpowiedzi Anthropic Messages udostępniają cache_read_input_tokens i cache_creation_input_tokens, mapowane odpowiednio na cacheRead i cacheWrite.
• cacheRetention: "short" odpowiada domyślnej efemerycznej pamięci podręcznej o czasie przechowywania wynoszącym 5 minut. cacheRetention: "long" żąda czasu TTL wynoszącego 1 godzinę (cache_control: { type: "ephemeral", ttl: "1h" }), gdy jest ustawione jawnie. Niejawne lub sterowane zmienną środowiskową długie przechowywanie (OPENCLAW_CACHE_RETENTION=long bez jawnego ustawienia cacheRetention) przechodzi na 1-godzinny TTL tylko na hostach api.anthropic.com lub Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); inne hosty zachowują 5-minutową pamięć podręczną.

​

OpenAI (bezpośrednie API)

• Buforowanie promptów odbywa się automatycznie w obsługiwanych najnowszych modelach; OpenClaw nie wstawia znaczników pamięci podręcznej na poziomie bloków.
• OpenClaw wysyła prompt_cache_key, aby zachować stabilne kierowanie do pamięci podręcznej między turami. Bezpośrednie hosty api.openai.com otrzymują to automatycznie. Serwery proxy zgodne z OpenAI (oMLX, llama.cpp, niestandardowe punkty końcowe) muszą mieć ustawione compat.supportsPromptCacheKey: true w konfiguracji modelu, aby włączyć tę funkcję — nigdy nie jest ona automatycznie wykrywana dla serwera proxy.
• prompt_cache_retention: "24h" jest dodawane tylko wtedy, gdy wybrano cacheRetention: "long", a rozpoznany punkt końcowy obsługuje zarówno klucz pamięci podręcznej, jak i długie przechowywanie (compat.supportsLongCacheRetention, domyślnie true; profile zgodności Together AI i Cloudflare wyłączają tę funkcję). cacheRetention: "none" pomija oba pola.
• Trafienia w pamięci podręcznej są udostępniane przez usage.prompt_tokens_details.cached_tokens (Chat Completions) lub input_tokens_details.cached_tokens (Responses API) i mapowane na cacheRead.
• Ładunki Responses API mogą również udostępniać input_tokens_details.cache_write_tokens, mapowane na cacheWrite i rozliczane według stawki modelu za zapis do pamięci podręcznej; w przypadku ładunków Responses, które pomijają to pole, cacheWrite zachowuje wartość 0. API Chat Completions firmy OpenAI nie dokumentuje ani nie emituje licznika cache_write_tokens, ale OpenClaw nadal odczytuje tam prompt_tokens_details.cache_write_tokens na potrzeby serwerów proxy zgodnych z OpenRouter i serwerów proxy w stylu DeepSeek, które raportują oddzielną liczbę zapisów.
• W praktyce OpenAI działa bardziej jak pamięć podręczna początkowego prefiksu niż mechanizm ponownego wykorzystania przesuwającej się pełnej historii firmy Anthropic — zobacz poniżej oczekiwania dotyczące działania OpenAI na żywo.

​

Amazon Bedrock

• Odwołania do modeli Anthropic Claude (amazon-bedrock/*anthropic.claude*, a także prefiksy systemowych profili wnioskowania AWS us./eu./global.anthropic.claude*) obsługują jawne przekazywanie cacheRetention.
• Modele Bedrock inne niż Anthropic (na przykład amazon.nova-*) w czasie wykonywania nie stosują przechowywania w pamięci podręcznej, niezależnie od skonfigurowanej wartości cacheRetention.
• Niejawne ARN-y profili wnioskowania aplikacji Bedrock (identyfikatory profili, które nie zawierają claude) również nie stosują przechowywania w pamięci podręcznej, chyba że jawnie ustawiono cacheRetention, ponieważ rodziny modelu nie można wywnioskować wyłącznie z ARN-u.

​

OpenRouter

​

Google Gemini (bezpośrednie API)

• Bezpośredni transport Gemini (api: "google-generative-ai") zgłasza trafienia w pamięci podręcznej za pośrednictwem nadrzędnego pola cachedContentTokenCount, mapowanego na cacheRead.
• Obsługiwane rodziny modeli: gemini-2.5* i gemini-3* (z wyłączeniem wariantów Live/preview, które nie pasują do tego prefiksu, na przykład gemini-live-2.5-flash-preview).
• Gdy na obsługiwanym modelu ustawiono cacheRetention, OpenClaw automatycznie tworzy, ponownie wykorzystuje i odświeża zasób cachedContents dla promptu systemowego — nie jest potrzebny ręczny uchwyt buforowanej zawartości. TTL wynosi 300s dla cacheRetention: "short" i 3600s dla "long".
• Nadal można przekazać istniejący uchwyt buforowanej zawartości Gemini jako params.cachedContent (lub starsze params.cached_content); jawny uchwyt całkowicie pomija automatyczną ścieżkę zarządzania pamięcią podręczną.
• Jest to niezależne od buforowania prefiksów promptów Anthropic/OpenAI: zamiast wstrzykiwać wbudowane znaczniki pamięci podręcznej, OpenClaw zarządza natywnym dla dostawcy zasobem cachedContents dla Gemini.

​

Dostawcy oparci na środowisku CLI (Claude Code, Gemini CLI)

​

Inni dostawcy

​

Granica pamięci podręcznej promptu systemowego

• Stabilne pliki kontekstu projektu z obszaru roboczego są umieszczane przed HEARTBEAT.md, aby zmienność mechanizmu Heartbeat nie unieważniała stabilnego prefiksu.
• Granica obowiązuje w kształtowaniu transportu dla rodzin Anthropic i OpenAI, Google oraz CLI, dzięki czemu wszyscy obsługiwani dostawcy korzystają z tej samej stabilności prefiksu.
• Żądania Codex Responses i Anthropic Vertex są kierowane przez mechanizm kształtowania pamięci podręcznej uwzględniający granicę, dzięki czemu ponowne użycie pamięci podręcznej pozostaje zgodne z danymi faktycznie otrzymywanymi przez dostawców.
• Odciski promptów systemowych są normalizowane (białe znaki, zakończenia wierszy, kontekst dodawany przez hooki, kolejność możliwości środowiska uruchomieniowego), dzięki czemu prompty niezmienione semantycznie współdzielą pamięć podręczną między turami.

​

Zabezpieczenia stabilności pamięci podręcznej OpenClaw

• Dołączone katalogi narzędzi MCP są sortowane deterministycznie (najpierw według nazwy serwera, a następnie nazwy narzędzia) przed rejestracją narzędzi, dzięki czemu zmiany kolejności listTools() nie powodują zmian w bloku narzędzi ani unieważniania prefiksów pamięci podręcznej promptów.
• Starsze sesje z utrwalonymi blokami obrazów zachowują bez zmian 3 ostatnie ukończone tury (z uwzględnieniem wszystkich ukończonych tur, a nie tylko tych zawierających obrazy). Starsze, już przetworzone bloki obrazów są zastępowane znacznikiem tekstowym, aby kolejne żądania związane z obrazami nie wysyłały ponownie dużych, nieaktualnych ładunków.

​

Wzorce dostrajania

​

Ruch mieszany (zalecane ustawienie domyślne)

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"

​

Konfiguracja bazowa ukierunkowana na koszty

• Należy ustawić bazowe cacheRetention: "short".
• Należy włączyć contextPruning.mode: "cache-ttl".
• Interwał Heartbeat powinien być krótszy niż TTL tylko w przypadku agentów, które korzystają z rozgrzanej pamięci podręcznej.

​

Testy regresji na żywo

• 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

​

Oczekiwania dotyczące działania Anthropic na żywo

• Oczekiwane są jawne zapisy rozgrzewające za pośrednictwem cacheWrite.
• Oczekiwane jest ponowne użycie niemal całej historii w kolejnych turach, ponieważ sterowanie pamięcią podręczną Anthropic przesuwa punkt graniczny pamięci podręcznej wraz z postępem konwersacji.
• Bazowe dolne progi dla stabilnych ścieżek oraz ścieżek narzędziowych, obrazowych i w stylu MCP są twardymi bramkami regresji.

​

Oczekiwania dotyczące działania OpenAI na żywo

• Oczekiwane jest tylko cacheRead; cacheWrite pozostaje 0 w Chat Completions.
• Ponowne użycie pamięci podręcznej w kolejnych turach należy traktować jako specyficzne dla dostawcy wypłaszczenie, a nie charakterystyczne dla Anthropic przesuwające się ponowne użycie całej historii.
• Dolne progi służą tylko do monitorowania (ich niespełnienie jest rejestrowane jako ostrzeżenie, a nie niepowodzenie testu) i wynikają z zachowania zaobserwowanego podczas działania na żywo w gpt-5.4-mini:

​

Konfiguracja diagnostics.cacheTrace

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # opcjonalne
    includeMessages: false # domyślnie true
    includePrompt: false # domyślnie true
    includeSystem: false # domyślnie true

​

Przełączniki zmiennych środowiskowych (jednorazowe debugowanie)

​

Co sprawdzić

• Zdarzenia śledzenia pamięci podręcznej mają format JSONL i zawierają etapowe migawki, takie jak session:loaded, prompt:before, stream:context oraz session:after.
• Wpływ tokenów pamięci podręcznej w poszczególnych turach jest widoczny w standardowych powierzchniach użycia: cacheRead i cacheWrite pojawiają się w /usage tokens, /status, podsumowaniach użycia sesji oraz niestandardowych układach messages.usageTemplate.
• W przypadku Anthropic, gdy pamięć podręczna jest aktywna, oczekiwane są zarówno cacheRead, jak i cacheWrite.
• W przypadku OpenAI przy trafieniach pamięci podręcznej oczekiwane jest cacheRead; cacheWrite jest uzupełniane tylko w ładunkach Responses API, które je zawierają (zobacz sekcję OpenAI powyżej).
• OpenAI zwraca również nagłówki śledzenia i limitów szybkości, takie jak x-request-id, openai-processing-ms oraz x-ratelimit-*; należy używać ich do śledzenia żądań, ale rozliczanie trafień pamięci podręcznej powinno nadal opierać się na ładunku użycia, a nie na nagłówkach.

​

Szybkie rozwiązywanie problemów

• Wysokie cacheWrite w większości tur: sprawdź zmienne dane wejściowe promptu systemowego; zweryfikuj, czy model lub dostawca obsługuje ustawienia pamięci podręcznej.
• Wysokie cacheWrite w Anthropic: często oznacza, że punkt graniczny pamięci podręcznej przypada na treść zmieniającą się przy każdym żądaniu.
• Niskie cacheRead OpenAI: zweryfikuj, czy stabilny prefiks znajduje się na początku, powtarzany prefiks ma co najmniej 1024 tokeny oraz czy ten sam prompt_cache_key jest ponownie używany w turach, które powinny współdzielić pamięć podręczną.
• Brak efektu działania cacheRetention: potwierdź, że klucz modelu odpowiada agents.defaults.models["provider/model"].
• Żądania Bedrock Nova z ustawieniami pamięci podręcznej: oczekiwane — w czasie wykonywania są rozwiązywane bez zachowywania pamięci podręcznej.

• Anthropic
• Użycie tokenów i koszty
• Przycinanie sesji
• Dokumentacja konfiguracji Gateway

​

Powiązane

• Użycie tokenów i koszty
• Użycie API i koszty