Buforowanie promptów

Buforowanie promptów oznacza, że dostawca modelu może ponownie używać niezmienionych prefiksów promptu (zwykle instrukcji systemowych/deweloperskich i innego stabilnego kontekstu) między turami, zamiast przetwarzać je za każdym razem od nowa. OpenClaw normalizuje użycie dostawcy do cacheRead i cacheWrite, gdy nadrzędne API bezpośrednio udostępnia te liczniki.

Powierzchnie statusu mogą też odzyskać liczniki cache z najnowszego logu użycia transkrypcji, gdy brakuje ich w migawce sesji na żywo, dzięki czemu /status może nadal pokazywać wiersz cache po częściowej utracie metadanych sesji. Istniejące niezerowe wartości cache z sesji na żywo nadal mają pierwszeństwo przed wartościami zapasowymi z transkrypcji.

Dlaczego to ważne: niższy koszt tokenów, szybsze odpowiedzi i bardziej przewidywalna wydajność w długotrwałych sesjach. Bez buforowania powtarzane prompty płacą pełny koszt promptu w każdej turze, nawet gdy większość wejścia się nie zmieniła.

Poniższe sekcje omawiają każde pokrętło związane z cache, które wpływa na ponowne użycie promptu i koszt tokenów.

Referencje dostawców:

• Buforowanie promptów Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Buforowanie promptów OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Nagłówki API OpenAI i identyfikatory żądań: https://developers.openai.com/api/reference/overview
• Identyfikatory żądań i błędy Anthropic: https://platform.claude.com/docs/en/api/errors

Główne pokrętła

cacheRetention (globalna wartość domyślna, model i ustawienie per agent)

Ustaw retencję cache jako globalną wartość domyślną dla wszystkich modeli:

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

Nadpisz per model:

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

Nadpisanie per agent:

agents:  list:    - id: "alerts"      params:        cacheRetention: "none"

Kolejność scalania konfiguracji:

1. agents.defaults.params (globalna wartość domyślna — dotyczy wszystkich modeli)
2. agents.defaults.models["provider/model"].params (nadpisanie per model)
3. agents.list[].params (pasujący identyfikator agenta; nadpisuje według klucza)

contextPruning.mode: "cache-ttl"

Przycina stary kontekst wyników narzędzi po oknach TTL cache, aby żądania po bezczynności nie buforowały ponownie nadmiernie dużej historii.

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

Pełne zachowanie opisuje Przycinanie sesji.

Utrzymywanie cache w cieple przez Heartbeat

Heartbeat może utrzymywać okna cache w cieple i ograniczać powtarzane zapisy cache po okresach bezczynności.

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

Heartbeat per agent jest obsługiwany w agents.list[].heartbeat.

Zachowanie dostawców

Anthropic (bezpośrednie API)

• cacheRetention jest obsługiwane.
• Przy profilach uwierzytelniania Anthropic z kluczem API OpenClaw ustawia początkowo cacheRetention: "short" dla referencji modeli Anthropic, gdy ta wartość nie jest ustawiona.
• Natywne odpowiedzi Messages Anthropic udostępniają zarówno cache_read_input_tokens, jak i cache_creation_input_tokens, więc OpenClaw może pokazywać zarówno cacheRead, jak i cacheWrite.
• Dla natywnych żądań Anthropic cacheRetention: "short" mapuje się na domyślny 5-minutowy efemeryczny cache, a cacheRetention: "long" przełącza na TTL 1 godziny tylko na bezpośrednich hostach api.anthropic.com.

OpenAI (bezpośrednie API)

• Buforowanie promptów jest automatyczne w obsługiwanych najnowszych modelach. OpenClaw nie musi wstrzykiwać znaczników cache na poziomie bloków.
• OpenClaw używa prompt_cache_key, aby utrzymać stabilne trasowanie cache między turami. Bezpośrednie hosty OpenAI używają prompt_cache_retention: "24h", gdy wybrane jest cacheRetention: "long".
• Dostawcy Completions zgodni z OpenAI otrzymują prompt_cache_key tylko wtedy, gdy ich konfiguracja modelu jawnie ustawia compat.supportsPromptCacheKey: true. Przekazywanie długiej retencji jest osobną zdolnością: jawne cacheRetention: "long" wysyła prompt_cache_retention: "24h" tylko wtedy, gdy ten wpis zgodności obsługuje również długą retencję cache. Dostawcy tacy jak Mistral mogą włączyć klucze cache, ustawiając jednocześnie compat.supportsLongCacheRetention: false, aby pominąć pole długiej retencji. cacheRetention: "none" pomija oba pola.
• Odpowiedzi OpenAI udostępniają zbuforowane tokeny promptu przez usage.prompt_tokens_details.cached_tokens (lub input_tokens_details.cached_tokens w zdarzeniach Responses API). OpenClaw mapuje to na cacheRead.
• Użycie Responses GPT-5.6 może też udostępniać input_tokens_details.cache_write_tokens. OpenClaw mapuje to na cacheWrite i wycenia według stawki zapisu cache danego modelu; odpowiedzi, które pomijają to pole, pozostawiają cacheWrite na poziomie 0.
• OpenAI zwraca przydatne nagłówki śledzenia i limitów szybkości, takie jak x-request-id, openai-processing-ms i x-ratelimit-*, ale rozliczanie trafień cache powinno pochodzić z ładunku użycia, a nie z nagłówków.
• W praktyce OpenAI często zachowuje się jak cache początkowego prefiksu, a nie jak ponowne użycie przesuwającej się pełnej historii w stylu Anthropic. Stabilne tury z długim tekstem prefiksowym mogą trafiać w okolice plateau 4864 zbuforowanych tokenów w bieżących sondach na żywo, podczas gdy transkrypcje intensywnie używające narzędzi lub w stylu MCP często osiągają plateau w okolicach 4608 zbuforowanych tokenów nawet przy dokładnych powtórzeniach.

Anthropic Vertex

• Modele Anthropic w Vertex AI (anthropic-vertex/*) obsługują cacheRetention tak samo jak bezpośredni Anthropic.
• cacheRetention: "long" mapuje się na rzeczywisty 1-godzinny TTL cache promptów w punktach końcowych Vertex AI.
• Domyślna retencja cache dla anthropic-vertex odpowiada domyślnym wartościom bezpośredniego Anthropic.
• Żądania Vertex są trasowane przez kształtowanie cache świadome granic, aby ponowne użycie cache pozostało zgodne z tym, co dostawcy faktycznie otrzymują.

Amazon Bedrock

• Referencje modeli Anthropic Claude (amazon-bedrock/*anthropic.claude*) obsługują jawne przekazywanie cacheRetention.
• Modele Bedrock inne niż Anthropic są w czasie działania wymuszane na cacheRetention: "none".

Modele OpenRouter

Dla referencji modeli openrouter/anthropic/* OpenClaw wstrzykuje Anthropic cache_control w blokach promptu systemowego/deweloperskiego, aby poprawić ponowne użycie cache promptów tylko wtedy, gdy żądanie nadal kieruje do zweryfikowanej trasy OpenRouter (openrouter na jego domyślnym punkcie końcowym albo dowolny dostawca/bazowy URL, który rozwiązuje się do openrouter.ai).

Dla referencji modeli openrouter/deepseek/*, openrouter/moonshot*/* i openrouter/zai/* contextPruning.mode: "cache-ttl" jest dozwolone, ponieważ OpenRouter automatycznie obsługuje buforowanie promptów po stronie dostawcy. OpenClaw nie wstrzykuje znaczników Anthropic cache_control do tych żądań.

Budowanie cache DeepSeek odbywa się w trybie najlepszych starań i może potrwać kilka sekund. Natychmiastowe kolejne żądanie może nadal pokazywać cached_tokens: 0; zweryfikuj to powtórzonym żądaniem z tym samym prefiksem po krótkim opóźnieniu i użyj usage.prompt_tokens_details.cached_tokens jako sygnału trafienia cache.

Jeśli przekierujesz model na dowolny URL proxy zgodny z OpenAI, OpenClaw przestaje wstrzykiwać te specyficzne dla OpenRouter znaczniki cache Anthropic.

Inni dostawcy

Jeśli dostawca nie obsługuje tego trybu cache, cacheRetention nie ma efektu.

Bezpośrednie API Google Gemini

• Bezpośredni transport Gemini (api: "google-generative-ai") zgłasza trafienia cache przez nadrzędne cachedContentTokenCount; OpenClaw mapuje to na cacheRead.
• Gdy cacheRetention jest ustawione dla bezpośredniego modelu Gemini, OpenClaw automatycznie tworzy, ponownie używa i odświeża zasoby cachedContents dla promptów systemowych w uruchomieniach Google AI Studio. Oznacza to, że nie trzeba już ręcznie tworzyć wcześniej uchwytu cached-content.
• Nadal możesz przekazać istniejący uchwyt cached-content Gemini jako params.cachedContent (lub starsze params.cached_content) w skonfigurowanym modelu.
• Jest to osobne od buforowania prefiksów promptów Anthropic/OpenAI. Dla Gemini OpenClaw zarządza natywnym dla dostawcy zasobem cachedContents, zamiast wstrzykiwać znaczniki cache do żądania.

Użycie Gemini CLI

• Wyjście Gemini CLI stream-json może ujawniać trafienia cache przez stats.cached; OpenClaw mapuje to na cacheRead. Starsze nadpisania --output-format json używają tej samej normalizacji użycia.
• Jeśli CLI pomija bezpośrednią wartość stats.input, OpenClaw wyprowadza tokeny wejściowe z stats.input_tokens - stats.cached.
• To wyłącznie normalizacja użycia. Nie oznacza, że OpenClaw tworzy znaczniki cache promptów w stylu Anthropic/OpenAI dla Gemini CLI.

Granica cache promptu systemowego

OpenClaw dzieli prompt systemowy na stabilny prefiks i zmienny sufiks, rozdzielone wewnętrzną granicą prefiksu cache. Treść powyżej granicy (definicje narzędzi, metadane Skills, pliki obszaru roboczego i inny stosunkowo statyczny kontekst) jest porządkowana tak, aby pozostawała identyczna bajtowo między turami. Treść poniżej granicy (na przykład HEARTBEAT.md, znaczniki czasu środowiska uruchomieniowego i inne metadane per tura) może się zmieniać bez unieważniania zbuforowanego prefiksu.

Kluczowe decyzje projektowe:

• Stabilne pliki kontekstu projektu w obszarze roboczym są porządkowane przed HEARTBEAT.md, aby zmienność heartbeat nie psuła stabilnego prefiksu.
• Granica jest stosowana w kształtowaniu transportu rodzin Anthropic, OpenAI, Google i CLI, więc wszyscy obsługiwani dostawcy korzystają z tej samej stabilności prefiksu.
• Żądania Codex Responses i Anthropic Vertex są trasowane przez kształtowanie cache świadome granic, aby ponowne użycie cache pozostało zgodne z tym, co dostawcy faktycznie otrzymują.
• Odciski palca promptu systemowego są normalizowane (białe znaki, zakończenia linii, kontekst dodany przez hooki, kolejność zdolności środowiska uruchomieniowego), aby semantycznie niezmienione prompty współdzieliły KV/cache między turami.

Jeśli widzisz nieoczekiwane skoki cacheWrite po zmianie konfiguracji lub obszaru roboczego, sprawdź, czy zmiana trafia powyżej czy poniżej granicy cache. Przeniesienie zmiennej treści poniżej granicy (lub jej ustabilizowanie) często rozwiązuje problem.

Osłony stabilności cache OpenClaw

OpenClaw utrzymuje też deterministyczny kształt kilku wrażliwych na cache ładunków, zanim żądanie dotrze do dostawcy:

• Katalogi narzędzi Bundle MCP są sortowane deterministycznie przed rejestracją narzędzi, więc zmiany kolejności listTools() nie zmieniają bloku narzędzi i nie psują prefiksów cache promptów.
• Starsze sesje z utrwalonymi blokami obrazów zachowują nienaruszone 3 najnowsze ukończone tury; starsze, już przetworzone bloki obrazów mogą zostać zastąpione znacznikiem, aby kontynuacje z dużą liczbą obrazów nie wysyłały ponownie dużych, nieaktualnych ładunków.

Wzorce strojenia

Ruch mieszany (zalecana wartość domyślna)

Utrzymuj długotrwałą bazę na głównym agencie, wyłącz buforowanie na agentach powiadomień obsługujących skoki ruchu:

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"

Baza nastawiona na koszt

• Ustaw bazowe cacheRetention: "short".
• Włącz contextPruning.mode: "cache-ttl".
• Utrzymuj heartbeat poniżej swojego TTL tylko dla agentów, którzy korzystają z ciepłych cache.

Diagnostyka cache

OpenClaw udostępnia dedykowaną diagnostykę śledzenia cache dla osadzonych uruchomień agentów.

W normalnej diagnostyce widocznej dla użytkownika /status i inne podsumowania użycia mogą używać najnowszego wpisu użycia transkrypcji jako źródła zapasowego dla cacheRead / cacheWrite, gdy wpis sesji na żywo nie ma tych liczników.

Testy regresji na żywo

OpenClaw utrzymuje jedną połączoną bramkę regresji cache na żywo dla powtarzanych prefiksów, tur narzędzi, tur obrazów, transkrypcji narzędzi w stylu MCP i kontrolnego przypadku Anthropic bez cache.

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-baseline.ts

Uruchom wąską bramkę na żywo poleceniem:

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

Plik bazowy przechowuje najnowsze zaobserwowane liczby live oraz specyficzne dla dostawcy dolne progi regresji używane przez test. Runner używa też świeżych identyfikatorów sesji i przestrzeni nazw promptów dla każdego uruchomienia, aby poprzedni stan cache nie zanieczyszczał bieżącej próbki regresji.

Te testy celowo nie używają identycznych kryteriów powodzenia dla wszystkich dostawców.

Oczekiwania live dla Anthropic

• Oczekuj jawnych zapisów rozgrzewających przez cacheWrite.
• Oczekuj niemal pełnego ponownego użycia historii przy powtarzanych turach, ponieważ kontrola cache Anthropic przesuwa punkt graniczny cache przez rozmowę.
• Bieżące asercje live nadal używają wysokich progów trafień dla ścieżek stabilnych, narzędziowych i obrazowych.

Oczekiwania live dla OpenAI

• Oczekuj tylko cacheRead. cacheWrite pozostaje 0.
• Traktuj ponowne użycie cache w powtarzanych turach jako specyficzne dla dostawcy plateau, a nie jako ponowne użycie ruchomej pełnej historii w stylu Anthropic.
• Bieżące asercje live używają konserwatywnych kontroli dolnych progów wyprowadzonych z zaobserwowanego zachowania live na gpt-5.4-mini:
  • stabilny prefiks: cacheRead >= 4608, współczynnik trafień >= 0.90
  • transkrypcja narzędziowa: cacheRead >= 4096, współczynnik trafień >= 0.85
  • transkrypcja obrazowa: cacheRead >= 3840, współczynnik trafień >= 0.82
  • transkrypcja w stylu MCP: cacheRead >= 4096, współczynnik trafień >= 0.85

Świeża połączona weryfikacja live z 2026-04-04 zakończyła się na poziomie:

• stabilny prefiks: cacheRead=4864, współczynnik trafień 0.966
• transkrypcja narzędziowa: cacheRead=4608, współczynnik trafień 0.896
• transkrypcja obrazowa: cacheRead=4864, współczynnik trafień 0.954
• transkrypcja w stylu MCP: cacheRead=4608, współczynnik trafień 0.891

Ostatni lokalny czas zegarowy dla połączonej bramki wynosił około 88s.

Dlaczego asercje się różnią:

• Anthropic udostępnia jawne punkty graniczne cache i ruchome ponowne użycie historii rozmowy.
• Buforowanie promptów OpenAI nadal jest wrażliwe na dokładny prefiks, ale efektywny prefiks możliwy do ponownego użycia w ruchu live Responses może osiągnąć plateau wcześniej niż pełny prompt.
• Z tego powodu porównywanie Anthropic i OpenAI przy użyciu jednego procentowego progu między dostawcami tworzy fałszywe regresje.

Konfiguracja 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

Wartości domyślne:

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: true

Przełączniki środowiskowe (jednorazowe debugowanie)

• OPENCLAW_CACHE_TRACE=1 włącza śledzenie cache.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl nadpisuje ścieżkę wyjściową.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 przełącza przechwytywanie pełnego ładunku wiadomości.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 przełącza przechwytywanie tekstu promptu.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 przełącza przechwytywanie promptu systemowego.

Co sprawdzać

• Zdarzenia śledzenia cache są w formacie JSONL i obejmują przygotowane migawki, takie jak session:loaded, prompt:before, stream:context i session:after.
• Wpływ tokenów cache w każdej turze jest widoczny w normalnych powierzchniach użycia przez cacheRead i cacheWrite (na przykład /usage tokens, /status, podsumowania użycia sesji oraz niestandardowe układy messages.usageTemplate).
• Dla Anthropic oczekuj zarówno cacheRead, jak i cacheWrite, gdy cache jest aktywny.
• Dla OpenAI oczekuj cacheRead przy trafieniach cache. GPT-5.6 Responses może też raportować cacheWrite podczas zapisywania segmentów promptu; inne ładunki Responses, które pomijają licznik zapisu, utrzymują go na poziomie 0.
• Jeśli potrzebujesz śledzenia żądań, loguj identyfikatory żądań i nagłówki limitów szybkości oddzielnie od metryk cache. Bieżące wyjście śledzenia cache OpenClaw skupia się na kształcie promptu/sesji i znormalizowanym użyciu tokenów, a nie na surowych nagłówkach odpowiedzi dostawcy.

Szybkie rozwiązywanie problemów

• Wysokie cacheWrite w większości tur: sprawdź niestabilne wejścia promptu systemowego i zweryfikuj, czy model/dostawca obsługuje Twoje ustawienia cache.
• Wysokie cacheWrite w Anthropic: często oznacza, że punkt graniczny cache trafia na treść, która zmienia się przy każdym żądaniu.
• Niskie cacheRead w OpenAI: zweryfikuj, czy stabilny prefiks jest na początku, powtarzany prefiks ma co najmniej 1024 tokeny i ten sam prompt_cache_key jest ponownie używany w turach, które powinny współdzielić cache.
• Brak efektu z cacheRetention: potwierdź, że klucz modelu pasuje do agents.defaults.models["provider/model"].
• Żądania Bedrock Nova/Mistral z ustawieniami cache: oczekiwane wymuszenie runtime do none.

Powiązane dokumenty:

• 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