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

• Anthropic प्रॉम्प्ट कैशिंग: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• OpenAI प्रॉम्प्ट कैशिंग: https://developers.openai.com/api/docs/guides/prompt-caching
• OpenAI API हेडर और अनुरोध ID: https://developers.openai.com/api/reference/overview
• Anthropic अनुरोध ID और त्रुटियां: 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-कुंजी auth प्रोफाइलों के साथ, OpenClaw सेट न होने पर Anthropic मॉडल refs के लिए cacheRetention: "short" सीड करता है।
• Anthropic नेटिव Messages प्रतिक्रियाएं cache_read_input_tokens और cache_creation_input_tokens दोनों उजागर करती हैं, इसलिए OpenClaw cacheRead और cacheWrite दोनों दिखा सकता है।
• नेटिव Anthropic अनुरोधों के लिए, cacheRetention: "short" डिफॉल्ट 5-मिनट ephemeral कैश से मैप होता है, और cacheRetention: "long" केवल प्रत्यक्ष api.anthropic.com होस्टों पर 1-घंटे TTL में अपग्रेड करता है।

​

OpenAI (प्रत्यक्ष API)

• समर्थित हालिया मॉडलों पर प्रॉम्प्ट कैशिंग स्वचालित है। OpenClaw को ब्लॉक-स्तरीय कैश मार्कर इंजेक्ट करने की आवश्यकता नहीं है।
• OpenClaw टर्नों के बीच कैश रूटिंग स्थिर रखने के लिए prompt_cache_key का उपयोग करता है। जब cacheRetention: "long" चुना जाता है, तो प्रत्यक्ष OpenAI होस्ट prompt_cache_retention: "24h" का उपयोग करते हैं।
• OpenAI-संगत Completions प्रदाताओं को prompt_cache_key केवल तब मिलता है जब उनका मॉडल कॉन्फिग स्पष्ट रूप से compat.supportsPromptCacheKey: true सेट करता है। लंबी-रिटेंशन फॉरवर्डिंग एक अलग क्षमता है: स्पष्ट cacheRetention: "long" केवल तब prompt_cache_retention: "24h" भेजता है जब वह compat एंट्री लंबी कैश रिटेंशन का भी समर्थन करती है। Mistral जैसे प्रदाता कैश कुंजियों में ऑप्ट इन कर सकते हैं और लंबी-रिटेंशन फील्ड दबाने के लिए compat.supportsLongCacheRetention: false सेट कर सकते हैं। cacheRetention: "none" दोनों फील्ड दबा देता है।
• OpenAI प्रतिक्रियाएं usage.prompt_tokens_details.cached_tokens (या Responses API इवेंट्स पर input_tokens_details.cached_tokens) के जरिए कैश किए गए प्रॉम्प्ट टोकन उजागर करती हैं। OpenClaw इसे cacheRead पर मैप करता है।
• OpenAI अलग कैश-राइट टोकन काउंटर उजागर नहीं करता, इसलिए OpenAI पाथों पर cacheWrite 0 रहता है, भले ही प्रदाता कैश गर्म कर रहा हो।
• OpenAI x-request-id, openai-processing-ms, और x-ratelimit-* जैसे उपयोगी ट्रेसिंग और रेट-लिमिट हेडर लौटाता है, लेकिन कैश-हिट अकाउंटिंग उपयोग पेलोड से आनी चाहिए, हेडरों से नहीं।
• व्यवहार में, OpenAI अक्सर Anthropic-शैली चलायमान पूर्ण-इतिहास पुन: उपयोग के बजाय शुरुआती-प्रीफिक्स कैश जैसा व्यवहार करता है। मौजूदा लाइव प्रोब में स्थिर लंबे-प्रीफिक्स टेक्स्ट टर्न लगभग 4864 कैश्ड-टोकन पठार तक पहुंच सकते हैं, जबकि टूल-भारी या MCP-शैली ट्रांसक्रिप्ट अक्सर सटीक दोहरावों पर भी लगभग 4608 कैश्ड टोकन पर स्थिर होते हैं।

​

Anthropic Vertex

• Vertex AI (anthropic-vertex/*) पर Anthropic मॉडल प्रत्यक्ष Anthropic की तरह ही cacheRetention का समर्थन करते हैं।
• cacheRetention: "long" Vertex AI एंडपॉइंटों पर वास्तविक 1-घंटे प्रॉम्प्ट-कैश TTL से मैप होता है।
• anthropic-vertex के लिए डिफॉल्ट कैश रिटेंशन प्रत्यक्ष Anthropic डिफॉल्ट से मेल खाता है।
• Vertex अनुरोध सीमा-जागरूक कैश शेपिंग से रूट किए जाते हैं, ताकि कैश पुन: उपयोग प्रदाताओं को वास्तव में मिलने वाली सामग्री से संरेखित रहे।

​

Amazon Bedrock

• Anthropic Claude मॉडल refs (amazon-bedrock/*anthropic.claude*) स्पष्ट cacheRetention पास-थ्रू का समर्थन करते हैं।
• गैर-Anthropic Bedrock मॉडलों को runtime पर cacheRetention: "none" पर बाध्य किया जाता है।

​

OpenRouter मॉडल

​

अन्य प्रदाता

​

Google Gemini प्रत्यक्ष API

• प्रत्यक्ष Gemini ट्रांसपोर्ट (api: "google-generative-ai") अपस्ट्रीम cachedContentTokenCount के माध्यम से कैश हिट रिपोर्ट करता है; OpenClaw इसे cacheRead पर मैप करता है।
• जब प्रत्यक्ष Gemini मॉडल पर cacheRetention सेट होता है, तो OpenClaw Google AI Studio रन पर सिस्टम प्रॉम्प्टों के लिए cachedContents संसाधन अपने-आप बनाता, पुन: उपयोग करता, और रीफ्रेश करता है। इसका मतलब है कि अब आपको cached-content हैंडल पहले से मैन्युअली बनाने की आवश्यकता नहीं है।
• आप अब भी कॉन्फिगर किए गए मॉडल पर params.cachedContent (या legacy params.cached_content) के रूप में पहले से मौजूद Gemini cached-content हैंडल पास कर सकते हैं।
• यह Anthropic/OpenAI प्रॉम्प्ट-प्रीफिक्स कैशिंग से अलग है। Gemini के लिए, OpenClaw अनुरोध में कैश मार्कर इंजेक्ट करने के बजाय प्रदाता-नेटिव cachedContents संसाधन प्रबंधित करता है।

​

Gemini CLI उपयोग

• Gemini CLI stream-json आउटपुट stats.cached के माध्यम से कैश हिट दिखा सकता है; OpenClaw इसे cacheRead पर मैप करता है। Legacy --output-format json ओवरराइड समान उपयोग सामान्यीकरण का उपयोग करते हैं।
• यदि CLI प्रत्यक्ष stats.input मान छोड़ देता है, तो OpenClaw stats.input_tokens - stats.cached से इनपुट टोकन निकालता है।
• यह केवल उपयोग सामान्यीकरण है। इसका मतलब यह नहीं है कि OpenClaw Gemini CLI के लिए Anthropic/OpenAI-शैली प्रॉम्प्ट-कैश मार्कर बना रहा है।

​

सिस्टम-प्रॉम्प्ट कैश सीमा

• स्थिर workspace project-context फाइलें HEARTBEAT.md से पहले क्रमबद्ध होती हैं, ताकि Heartbeat churn स्थिर प्रीफिक्स को न तोड़े।
• सीमा Anthropic-family, OpenAI-family, Google, और CLI ट्रांसपोर्ट शेपिंग में लागू होती है, ताकि सभी समर्थित प्रदाता समान प्रीफिक्स स्थिरता से लाभान्वित हों।
• Codex Responses और Anthropic Vertex अनुरोध सीमा-जागरूक कैश शेपिंग से रूट किए जाते हैं, ताकि कैश पुन: उपयोग प्रदाताओं को वास्तव में मिलने वाली सामग्री से संरेखित रहे।
• सिस्टम-प्रॉम्प्ट फिंगरप्रिंट सामान्यीकृत होते हैं (whitespace, line endings, hook-added context, runtime capability ordering), ताकि semantically अपरिवर्तित प्रॉम्प्ट टर्नों के बीच KV/cache साझा करें।

​

OpenClaw कैश-स्थिरता गार्ड

• Bundle MCP टूल कैटलॉग टूल पंजीकरण से पहले deterministic रूप से क्रमबद्ध किए जाते हैं, ताकि listTools() क्रम में बदलाव tools block को churn करके प्रॉम्प्ट-कैश प्रीफिक्स न तोड़े।
• persisted image blocks वाले legacy sessions 3 सबसे हालिया पूर्ण टर्नों को अक्षुण्ण रखते हैं; पुराने पहले से संसाधित image blocks को marker से बदला जा सकता है, ताकि image-heavy follow-ups बड़े stale payloads को बार-बार न भेजते रहें।

​

ट्यूनिंग पैटर्न

​

मिश्रित ट्रैफिक (अनुशंसित डिफॉल्ट)

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"

​

लागत-प्रथम baseline

• baseline 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 के माध्यम से स्पष्ट warmup writes की अपेक्षा करें।
• repeated turns पर लगभग पूर्ण इतिहास reuse की अपेक्षा करें क्योंकि Anthropic cache control बातचीत के माध्यम से cache breakpoint को आगे बढ़ाता है।
• मौजूदा लाइव assertions अभी भी stable, tool, और image paths के लिए high hit-rate thresholds का उपयोग करते हैं।

​

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

• केवल cacheRead की अपेक्षा करें। cacheWrite 0 ही रहता है।
• repeated-turn cache reuse को provider-specific plateau मानें, Anthropic-शैली के moving full-history reuse के रूप में नहीं।
• मौजूदा लाइव 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

• 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

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

​

diagnostics.cacheTrace config

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 toggles (one-off 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 full और session usage summaries)।
• Anthropic के लिए, caching सक्रिय होने पर cacheRead और cacheWrite दोनों की अपेक्षा करें।
• OpenAI के लिए, cache hits पर cacheRead की अपेक्षा करें और cacheWrite को 0 ही रहने दें; OpenAI अलग cache-write token field प्रकाशित नहीं करता।
• यदि आपको 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 पर high cacheWrite: volatile system-prompt inputs जाँचें और सत्यापित करें कि model/provider आपकी cache settings का समर्थन करता है।
• Anthropic पर high cacheWrite: अक्सर इसका अर्थ होता है कि cache breakpoint ऐसी सामग्री पर landing कर रहा है जो हर request में बदलती है।
• Low OpenAI cacheRead: सत्यापित करें कि stable prefix सामने है, repeated prefix कम से कम 1024 tokens है, और वही prompt_cache_key उन turns के लिए reused है जिन्हें cache साझा करना चाहिए।
• cacheRetention से कोई प्रभाव नहीं: पुष्टि करें कि model key agents.defaults.models["provider/model"] से मेल खाती है।
• cache settings के साथ Bedrock Nova/Mistral requests: runtime द्वारा none पर force अपेक्षित है।

• Anthropic
• Token use और costs
• Session pruning
• Gateway configuration reference

​

संबंधित

• Token use और costs
• API usage और costs