Technical reference

प्रॉम्प्ट कैशिंग

प्रॉम्प्ट कैशिंग का अर्थ है कि मॉडल प्रदाता हर बार उन्हें दोबारा प्रोसेस करने के बजाय टर्नों में अपरिवर्तित प्रॉम्प्ट प्रीफिक्स (आमतौर पर सिस्टम/डेवलपर निर्देश और अन्य स्थिर संदर्भ) का पुन: उपयोग कर सकता है। OpenClaw प्रदाता उपयोग को cacheRead और cacheWrite में सामान्यीकृत करता है, जहां upstream API उन काउंटरों को सीधे उजागर करता है।

जब live session snapshot में कैश काउंटर मौजूद नहीं होते, तो status सतहें सबसे हालिया transcript usage log से भी कैश काउंटर पुनर्प्राप्त कर सकती हैं, ताकि /status आंशिक session metadata loss के बाद भी कैश लाइन दिखाता रहे। मौजूदा nonzero live cache values अब भी transcript fallback values पर प्राथमिकता रखते हैं।

यह क्यों मायने रखता है: कम टोकन लागत, तेज प्रतिक्रियाएं, और लंबे समय तक चलने वाले सेशनों के लिए अधिक पूर्वानुमेय प्रदर्शन। कैशिंग के बिना, दोहराए गए प्रॉम्प्ट हर टर्न पर पूरी प्रॉम्प्ट लागत चुकाते हैं, भले ही अधिकांश इनपुट नहीं बदला हो।

नीचे के अनुभाग हर उस cache-related knob को कवर करते हैं जो प्रॉम्प्ट reuse और token cost को प्रभावित करता है।

Provider संदर्भ:

Anthropic prompt caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
OpenAI prompt caching: https://developers.openai.com/api/docs/guides/prompt-caching
OpenAI API headers and request IDs: https://developers.openai.com/api/reference/overview
Anthropic request IDs and errors: https://platform.claude.com/docs/en/api/errors

प्राथमिक knobs

`cacheRetention` (global default, model, और per-agent)

सभी मॉडलों के लिए global default के रूप में cache retention सेट करें:

yaml

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

per-model override करें:

yaml

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

Per-agent override:

yaml

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

Config merge order:

agents.defaults.params (global default — सभी मॉडलों पर लागू होता है)
agents.defaults.models["provider/model"].params (per-model override)
agents.list[].params (matching agent id; key के आधार पर override करता है)

`contextPruning.mode: "cache-ttl"`

cache TTL windows के बाद पुराने tool-result context को prune करता है ताकि post-idle requests oversized history को दोबारा cache न करें।

yaml

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

पूर्ण व्यवहार के लिए Session Pruning देखें।

Heartbeat keep-warm

Heartbeat cache windows को warm रख सकता है और idle gaps के बाद दोहराए गए cache writes को कम कर सकता है।

yaml

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

Per-agent heartbeat agents.list[].heartbeat पर समर्थित है।

Provider व्यवहार

Anthropic (direct API)

cacheRetention समर्थित है।
Anthropic API-key auth profiles के साथ, जब unset हो तो OpenClaw Anthropic model refs के लिए cacheRetention: "short" seed करता है।
Anthropic native Messages responses cache_read_input_tokens और cache_creation_input_tokens दोनों expose करते हैं, इसलिए OpenClaw cacheRead और cacheWrite दोनों दिखा सकता है।
native Anthropic requests के लिए, cacheRetention: "short" default 5-minute ephemeral cache पर map होता है, और cacheRetention: "long" केवल direct api.anthropic.com hosts पर 1-hour TTL में upgrade करता है।

OpenAI (direct API)

समर्थित recent models पर prompt caching automatic है। OpenClaw को block-level cache markers inject करने की जरूरत नहीं है।
OpenClaw turns में cache routing stable रखने के लिए prompt_cache_key का उपयोग करता है। Direct OpenAI hosts cacheRetention: "long" चुने जाने पर prompt_cache_retention: "24h" का उपयोग करते हैं।
OpenAI-compatible Completions providers को prompt_cache_key केवल तब मिलता है जब उनका model config स्पष्ट रूप से compat.supportsPromptCacheKey: true सेट करता है। Long-retention forwarding एक अलग capability है: explicit cacheRetention: "long" prompt_cache_retention: "24h" केवल तब भेजता है जब वह compat entry long cache retention को भी support करती हो। Mistral जैसे Providers cache keys में opt in कर सकते हैं और long-retention field को suppress करने के लिए compat.supportsLongCacheRetention: false सेट कर सकते हैं। cacheRetention: "none" दोनों fields को suppress करता है।
OpenAI responses cached prompt tokens को usage.prompt_tokens_details.cached_tokens (या Responses API events पर input_tokens_details.cached_tokens) के माध्यम से expose करते हैं। OpenClaw उसे cacheRead पर map करता है।
GPT-5.6 Responses usage input_tokens_details.cache_write_tokens भी expose कर सकता है। OpenClaw उसे cacheWrite पर map करता है और model की cache-write rate पर उसकी कीमत लगाता है; जो Responses field omit करते हैं, वे cacheWrite को 0 पर रखते हैं।
OpenAI x-request-id, openai-processing-ms, और x-ratelimit-* जैसे उपयोगी tracing और rate-limit headers लौटाता है, लेकिन cache-hit accounting usage payload से आनी चाहिए, headers से नहीं।
व्यवहार में, OpenAI अक्सर Anthropic-style moving full-history reuse के बजाय initial-prefix cache जैसा व्यवहार करता है। Stable long-prefix text turns मौजूदा live probes में लगभग 4864 cached-token plateau के पास land कर सकते हैं, जबकि tool-heavy या MCP-style transcripts exact repeats पर भी अक्सर लगभग 4608 cached tokens के पास plateau करते हैं।

Anthropic Vertex

Vertex AI (anthropic-vertex/*) पर Anthropic models direct Anthropic की तरह ही cacheRetention support करते हैं।
cacheRetention: "long" Vertex AI endpoints पर वास्तविक 1-hour prompt-cache TTL पर map होता है।
anthropic-vertex के लिए default cache retention direct Anthropic defaults से match करता है।
Vertex requests boundary-aware cache shaping के माध्यम से route किए जाते हैं ताकि cache reuse providers को वास्तव में मिलने वाली चीज़ों से aligned रहे।

Amazon Bedrock

Anthropic Claude model refs (amazon-bedrock/*anthropic.claude*) explicit cacheRetention pass-through support करते हैं।
Non-Anthropic Bedrock models runtime पर forced to cacheRetention: "none" होते हैं।

OpenRouter models

openrouter/anthropic/* model refs के लिए, OpenClaw prompt-cache reuse सुधारने के लिए system/developer prompt blocks पर Anthropic cache_control inject करता है, केवल तब जब request अभी भी verified OpenRouter route (openrouter उसके default endpoint पर, या कोई भी provider/base URL जो openrouter.ai पर resolve होता है) को target कर रही हो।

openrouter/deepseek/*, openrouter/moonshot*/*, और openrouter/zai/* model refs के लिए, contextPruning.mode: "cache-ttl" allowed है क्योंकि OpenRouter provider-side prompt caching automatically handle करता है। OpenClaw उन requests में Anthropic cache_control markers inject नहीं करता।

DeepSeek cache construction best-effort है और इसमें कुछ सेकंड लग सकते हैं। एक immediate follow-up अब भी cached_tokens: 0 दिखा सकता है; थोड़ी देरी के बाद repeated same-prefix request से verify करें और cache-hit signal के रूप में usage.prompt_tokens_details.cached_tokens का उपयोग करें।

यदि आप model को किसी arbitrary OpenAI-compatible proxy URL पर repoint करते हैं, तो OpenClaw उन OpenRouter-specific Anthropic cache markers को inject करना बंद कर देता है।

अन्य providers

यदि provider इस cache mode को support नहीं करता, तो cacheRetention का कोई प्रभाव नहीं होता।

Google Gemini direct API

Direct Gemini transport (api: "google-generative-ai") upstream cachedContentTokenCount के माध्यम से cache hits report करता है; OpenClaw उसे cacheRead पर map करता है।
जब direct Gemini model पर cacheRetention सेट होता है, तो OpenClaw Google AI Studio runs पर system prompts के लिए cachedContents resources automatically create, reuse, और refresh करता है। इसका अर्थ है कि अब आपको cached-content handle manually pre-create करने की जरूरत नहीं है।
आप configured model पर params.cachedContent (या legacy params.cached_content) के रूप में pre-existing Gemini cached-content handle अब भी pass कर सकते हैं।
यह Anthropic/OpenAI prompt-prefix caching से अलग है। Gemini के लिए, OpenClaw request में cache markers inject करने के बजाय provider-native cachedContents resource manage करता है।

Gemini CLI usage

Gemini CLI stream-json output stats.cached के माध्यम से cache hits surface कर सकता है; OpenClaw उसे cacheRead पर map करता है। Legacy --output-format json overrides वही usage normalization उपयोग करते हैं।
यदि CLI direct stats.input value omit करता है, तो OpenClaw input tokens को stats.input_tokens - stats.cached से derive करता है।
यह केवल usage normalization है। इसका अर्थ यह नहीं है कि OpenClaw Gemini CLI के लिए Anthropic/OpenAI-style prompt-cache markers create कर रहा है।

System-prompt cache boundary

OpenClaw system prompt को एक stable prefix और एक volatile suffix में split करता है, जिन्हें internal cache-prefix boundary अलग करती है। Boundary के ऊपर की सामग्री (tool definitions, skills metadata, workspace files, और अन्य relatively static context) इस तरह ordered होती है कि वह turns में byte-identical रहे। Boundary के नीचे की सामग्री (उदाहरण के लिए HEARTBEAT.md, runtime timestamps, और अन्य per-turn metadata) cached prefix को invalid किए बिना बदल सकती है।

मुख्य design choices:

Stable workspace project-context files को HEARTBEAT.md से पहले ordered किया जाता है ताकि heartbeat churn stable prefix को bust न करे।
Boundary Anthropic-family, OpenAI-family, Google, और CLI transport shaping में apply की जाती है ताकि सभी supported providers को उसी prefix stability से benefit मिले।
Codex Responses और Anthropic Vertex requests boundary-aware cache shaping के माध्यम से route किए जाते हैं ताकि cache reuse providers को वास्तव में मिलने वाली चीज़ों से aligned रहे।
System-prompt fingerprints normalized होते हैं (whitespace, line endings, hook-added context, runtime capability ordering) ताकि semantically unchanged prompts turns में KV/cache share करें।

यदि config या workspace change के बाद unexpected cacheWrite spikes दिखें, तो जांचें कि change cache boundary के ऊपर land करता है या नीचे। Volatile content को boundary के नीचे move करना (या उसे stabilize करना) अक्सर issue resolve करता है।

OpenClaw cache-stability guards

OpenClaw request के provider तक पहुंचने से पहले कई cache-sensitive payload shapes को deterministic भी रखता है:

Bundle MCP tool catalogs tool registration से पहले deterministically sorted होते हैं, ताकि listTools() order changes tools block को churn न करें और prompt-cache prefixes को bust न करें।
Persisted image blocks वाले legacy sessions 3 most recent completed turns intact रखते हैं; पुराने already-processed image blocks को marker से replace किया जा सकता है ताकि image-heavy follow-ups large stale payloads को दोबारा भेजते न रहें।

Tuning patterns

Mixed traffic (recommended default)

अपने main agent पर long-lived baseline रखें, bursty notifier agents पर caching disable करें:

yaml

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"

Cost-first baseline

Baseline cacheRetention: "short" सेट करें।
contextPruning.mode: "cache-ttl" enable करें।
केवल उन agents के लिए heartbeat को अपने TTL से कम रखें जिन्हें warm caches से benefit होता है।

Cache diagnostics

OpenClaw embedded agent runs के लिए dedicated cache-trace diagnostics expose करता है।

Normal user-facing diagnostics के लिए, /status और अन्य usage summaries cacheRead / cacheWrite के लिए fallback source के रूप में latest transcript usage entry का उपयोग कर सकते हैं जब live session entry में वे counters नहीं होते।

Live regression tests

OpenClaw repeated prefixes, tool turns, image turns, MCP-style tool transcripts, और Anthropic no-cache control के लिए एक combined live cache regression gate रखता है।

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

Narrow live gate इस तरह run करें:

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

बेसलाइन फ़ाइल सबसे हाल ही में देखी गई लाइव संख्याएँ और परीक्षण द्वारा उपयोग की जाने वाली प्रदाता-विशिष्ट रिग्रेशन न्यूनतम सीमाएँ संग्रहीत करती है। रनर ताज़ा प्रति-रन सेशन ID और प्रॉम्प्ट नेमस्पेस भी उपयोग करता है ताकि पिछली कैश स्थिति वर्तमान रिग्रेशन नमूने को प्रदूषित न करे।

ये परीक्षण जानबूझकर सभी प्रदाताओं में समान सफलता मानदंडों का उपयोग नहीं करते।

Anthropic लाइव अपेक्षाएँ

cacheWrite के माध्यम से स्पष्ट वार्मअप writes की अपेक्षा करें।
दोहराए गए turns पर लगभग पूरे इतिहास के पुनः उपयोग की अपेक्षा करें, क्योंकि Anthropic cache control बातचीत के माध्यम से कैश ब्रेकपॉइंट को आगे बढ़ाता है।
मौजूदा लाइव assertions अभी भी stable, tool, और image पथों के लिए उच्च hit-rate thresholds का उपयोग करती हैं।

OpenAI लाइव अपेक्षाएँ

केवल cacheRead की अपेक्षा करें। cacheWrite 0 ही रहता है।
repeated-turn cache reuse को Anthropic-शैली के moving full-history reuse के बजाय प्रदाता-विशिष्ट plateau मानें।
मौजूदा लाइव assertions gpt-5.4-mini पर देखे गए लाइव व्यवहार से निकले conservative floor checks का उपयोग करती हैं:
- stable prefix: cacheRead >= 4608, hit rate >= 0.90
- tool transcript: cacheRead >= 4096, hit rate >= 0.85
- image transcript: cacheRead >= 3840, hit rate >= 0.82
- MCP-style transcript: cacheRead >= 4096, hit rate >= 0.85

2026-04-04 पर ताज़ा संयुक्त लाइव verification यहाँ पहुँचा:

stable prefix: cacheRead=4864, hit rate 0.966
tool transcript: cacheRead=4608, hit rate 0.896
image transcript: cacheRead=4864, hit rate 0.954
MCP-style transcript: cacheRead=4608, hit rate 0.891

संयुक्त gate के लिए हालिया स्थानीय wall-clock समय लगभग 88s था।

assertions अलग क्यों हैं:

Anthropic स्पष्ट cache breakpoints और moving conversation-history reuse उजागर करता है।
OpenAI prompt caching अभी भी exact-prefix sensitive है, लेकिन लाइव Responses traffic में प्रभावी reusable prefix पूरे prompt से पहले plateau हो सकता है।
इसके कारण, Anthropic और OpenAI की तुलना एक ही cross-provider percentage threshold से करने पर false regressions बनते हैं।

`diagnostics.cacheTrace` config

yaml

diagnostics:  cacheTrace:    enabled: true    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional    includeMessages: false # default true    includePrompt: false # default true    includeSystem: false # default true

Defaults:

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

Env toggles (एक-बार debugging)

OPENCLAW_CACHE_TRACE=1 cache tracing सक्षम करता है।
OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl output path को override करता है।
OPENCLAW_CACHE_TRACE_MESSAGES=0|1 full message payload capture को toggle करता है।
OPENCLAW_CACHE_TRACE_PROMPT=0|1 prompt text capture को toggle करता है।
OPENCLAW_CACHE_TRACE_SYSTEM=0|1 system prompt capture को toggle करता है।

क्या inspect करें

Cache trace events JSONL होते हैं और session:loaded, prompt:before, stream:context, और session:after जैसे staged snapshots शामिल करते हैं।
Per-turn cache token impact सामान्य usage surfaces में cacheRead और cacheWrite के माध्यम से दिखाई देता है (उदाहरण के लिए /usage tokens, /status, session usage summaries, और custom messages.usageTemplate layouts)।
Anthropic के लिए, caching सक्रिय होने पर cacheRead और cacheWrite दोनों की अपेक्षा करें।
OpenAI के लिए, cache hits पर cacheRead की अपेक्षा करें। GPT-5.6 Responses prompt segments लिखे जाते समय cacheWrite भी report कर सकते हैं; अन्य Responses payloads जो write counter छोड़ देते हैं, उसे 0 पर रखते हैं।
यदि आपको request tracing चाहिए, तो request IDs और rate-limit headers को cache metrics से अलग log करें। OpenClaw का मौजूदा cache-trace output raw provider response headers के बजाय prompt/session shape और normalized token usage पर केंद्रित है।

त्वरित troubleshooting

अधिकांश turns पर उच्च cacheWrite: volatile system-prompt inputs की जाँच करें और verify करें कि model/provider आपकी cache settings का समर्थन करता है।
Anthropic पर उच्च cacheWrite: अक्सर इसका मतलब है कि cache breakpoint ऐसी content पर landing कर रहा है जो हर request में बदलती है।
कम OpenAI cacheRead: verify करें कि stable prefix front पर है, repeated prefix कम से कम 1024 tokens है, और वही prompt_cache_key उन turns के लिए reuse होता है जिन्हें cache साझा करना चाहिए।
cacheRetention से कोई प्रभाव नहीं: confirm करें कि model key agents.defaults.models["provider/model"] से मेल खाती है।
cache settings के साथ Bedrock Nova/Mistral requests: runtime द्वारा none पर force किया जाना expected है।

प्रॉम्प्ट कैशिंग

प्राथमिक knobs

`cacheRetention` (global default, model, और per-agent)

`contextPruning.mode: "cache-ttl"`

Heartbeat keep-warm

Provider व्यवहार

Anthropic (direct API)

OpenAI (direct API)

Anthropic Vertex

Amazon Bedrock

OpenRouter models

अन्य providers

Google Gemini direct API

Gemini CLI usage

System-prompt cache boundary

OpenClaw cache-stability guards

Tuning patterns

Mixed traffic (recommended default)

Cost-first baseline

Cache diagnostics

Live regression tests

Anthropic लाइव अपेक्षाएँ

OpenAI लाइव अपेक्षाएँ

`diagnostics.cacheTrace` config

Env toggles (एक-बार debugging)

क्या inspect करें

त्वरित troubleshooting

संबंधित

On this page

Molty

प्राथमिक knobs

cacheRetention (global default, model, और per-agent)

contextPruning.mode: "cache-ttl"

Heartbeat keep-warm

Provider व्यवहार

Anthropic (direct API)

OpenAI (direct API)

Anthropic Vertex

Amazon Bedrock

OpenRouter models

अन्य providers

Google Gemini direct API

Gemini CLI usage

System-prompt cache boundary

OpenClaw cache-stability guards

Tuning patterns

Mixed traffic (recommended default)

Cost-first baseline

Cache diagnostics

Live regression tests

Anthropic लाइव अपेक्षाएँ

OpenAI लाइव अपेक्षाएँ

diagnostics.cacheTrace config

Env toggles (एक-बार debugging)

क्या inspect करें

त्वरित troubleshooting

संबंधित

On this page

`cacheRetention` (global default, model, और per-agent)

`contextPruning.mode: "cache-ttl"`

`diagnostics.cacheTrace` config