Technical reference
التخزين المؤقت للمطالبات
يعني التخزين المؤقت للموجّه أن مزوّد النموذج يستطيع إعادة استخدام بادئات الموجّه غير المتغيرة (عادةً تعليمات النظام/المطوّر والسياقات المستقرة الأخرى) عبر الأدوار بدلًا من إعادة معالجتها في كل مرة. يطبّع OpenClaw استخدام المزوّد إلى cacheRead وcacheWrite عندما تكشف واجهة API العليا تلك العدادات مباشرةً.
يمكن لأسطح الحالة أيضًا استرداد عدادات التخزين المؤقت من أحدث سجل استخدام في النص المنسوخ
عندما تكون لقطة الجلسة الحية فاقدة لها، بحيث يستطيع /status مواصلة
عرض سطر التخزين المؤقت بعد فقدان جزئي لبيانات تعريف الجلسة. وتظل قيم التخزين المؤقت الحية
غير الصفرية القائمة لها الأولوية على قيم الرجوع إلى النص المنسوخ.
سبب أهمية ذلك: تكلفة رموز أقل، واستجابات أسرع، وأداء أكثر قابلية للتنبؤ للجلسات طويلة التشغيل. من دون التخزين المؤقت، تدفع الموجّهات المتكررة تكلفة الموجّه كاملة في كل دور حتى عندما لا يتغير معظم الإدخال.
تغطي الأقسام أدناه كل مفتاح متعلق بالتخزين المؤقت يؤثر في إعادة استخدام الموجّه وتكلفة الرموز.
مراجع المزوّدين:
- التخزين المؤقت للموجّهات في Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- التخزين المؤقت للموجّهات في OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
- ترويسات OpenAI API ومعرّفات الطلبات: https://developers.openai.com/api/reference/overview
- معرّفات طلبات 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"ترتيب دمج الإعدادات:
agents.defaults.params(الافتراضي العام — ينطبق على كل النماذج)agents.defaults.models["provider/model"].params(تجاوز لكل نموذج)agents.list[].params(معرّف الوكيل المطابق؛ يتجاوز حسب المفتاح)
contextPruning.mode: "cache-ttl"
يشذّب سياق نتائج الأدوات القديم بعد نوافذ مدة بقاء التخزين المؤقت بحيث لا تعيد الطلبات بعد الخمول تخزين سجل كبير جدًا مؤقتًا.
agents: defaults: contextPruning: mode: "cache-ttl" ttl: "1h"راجع تشذيب الجلسة للاطلاع على السلوك الكامل.
إبقاء Heartbeat دافئًا
يمكن أن يبقي Heartbeat نوافذ التخزين المؤقت دافئة ويقلل عمليات كتابة التخزين المؤقت المتكررة بعد فجوات الخمول.
agents: defaults: heartbeat: every: "55m"يُدعم Heartbeat لكل وكيل في agents.list[].heartbeat.
سلوك المزوّد
Anthropic (واجهة API مباشرة)
cacheRetentionمدعوم.- مع ملفات تعريف مصادقة مفتاح Anthropic API، يزرع OpenClaw القيمة
cacheRetention: "short"لمراجع نماذج Anthropic عندما لا تكون مضبوطة. - تكشف استجابات Messages الأصلية في Anthropic كلًا من
cache_read_input_tokensوcache_creation_input_tokens، لذلك يستطيع OpenClaw عرض كلٍ منcacheReadوcacheWrite. - لطلبات Anthropic الأصلية، يطابق
cacheRetention: "short"التخزين المؤقت العابر الافتراضي لمدة 5 دقائق، ويرقّيcacheRetention: "long"إلى مدة بقاء ساعة واحدة فقط على مضيفيapi.anthropic.comالمباشرين.
OpenAI (واجهة API مباشرة)
- التخزين المؤقت للموجّهات تلقائي على النماذج الحديثة المدعومة. لا يحتاج OpenClaw إلى حقن علامات تخزين مؤقت على مستوى الكتل.
- يستخدم OpenClaw
prompt_cache_keyلإبقاء توجيه التخزين المؤقت مستقرًا عبر الأدوار. يستخدم مضيفو OpenAI المباشرونprompt_cache_retention: "24h"عندما يُختارcacheRetention: "long". - يتلقى مزوّدو Completions المتوافقون مع OpenAI المفتاح
prompt_cache_keyفقط عندما تضبط إعدادات نموذجهم صراحةًcompat.supportsPromptCacheKey: true. تمرير الاحتفاظ الطويل قدرة منفصلة: يرسلcacheRetention: "long"الصريحprompt_cache_retention: "24h"فقط عندما يدعم إدخال التوافق هذا أيضًا الاحتفاظ الطويل بالتخزين المؤقت. يمكن لمزوّدين مثل Mistral الاشتراك في مفاتيح التخزين المؤقت مع ضبطcompat.supportsLongCacheRetention: falseلمنع حقل الاحتفاظ الطويل. يمنعcacheRetention: "none"كلا الحقلين. - تكشف استجابات OpenAI رموز الموجّه المخزّنة مؤقتًا عبر
usage.prompt_tokens_details.cached_tokens(أوinput_tokens_details.cached_tokensفي أحداث Responses API). يربط OpenClaw ذلك بـcacheRead. - يمكن أن يكشف استخدام GPT-5.6 Responses أيضًا
input_tokens_details.cache_write_tokens. يربط OpenClaw ذلك بـcacheWriteويسعّره وفق معدل كتابة التخزين المؤقت للنموذج؛ وتُبقي استجابات Responses التي تحذف الحقلcacheWriteعند0. - يعيد OpenAI ترويسات مفيدة للتتبع وحدود المعدل مثل
x-request-idوopenai-processing-msوx-ratelimit-*، لكن يجب أن يأتي حساب إصابات التخزين المؤقت من حمولة الاستخدام، لا من الترويسات. - عمليًا، غالبًا ما يتصرف OpenAI مثل تخزين مؤقت لبادئة أولية بدلًا من إعادة استخدام سجل كامل متحرك بأسلوب Anthropic. يمكن أن تصل أدوار النص ذي البادئة الطويلة المستقرة إلى هضبة رموز مخزّنة مؤقتًا قريبة من
4864في فحوصات حية حالية، بينما غالبًا ما تستقر النصوص المنسوخة الكثيفة بالأدوات أو بأسلوب MCP قرب4608رموز مخزّنة مؤقتًا حتى عند التكرارات المطابقة تمامًا.
Anthropic Vertex
- تدعم نماذج Anthropic على Vertex AI (
anthropic-vertex/*)cacheRetentionبالطريقة نفسها مثل Anthropic المباشر. - يطابق
cacheRetention: "long"مدة بقاء التخزين المؤقت الحقيقي للموجّه لمدة ساعة واحدة على نقاط نهاية Vertex AI. - يطابق الاحتفاظ الافتراضي بالتخزين المؤقت لـ
anthropic-vertexافتراضيات Anthropic المباشر. - تُوجّه طلبات Vertex عبر تشكيل تخزين مؤقت واعٍ بالحدود بحيث تبقى إعادة استخدام التخزين المؤقت متوافقة مع ما يتلقاه المزوّدون فعليًا.
Amazon Bedrock
- تدعم مراجع نماذج Anthropic Claude (
amazon-bedrock/*anthropic.claude*) تمريرcacheRetentionالصريح. - تُجبر نماذج Bedrock غير التابعة لـ Anthropic على
cacheRetention: "none"في وقت التشغيل.
نماذج OpenRouter
بالنسبة إلى مراجع نماذج openrouter/anthropic/*، يحقن OpenClaw
cache_control في كتل موجّهات النظام/المطوّر لتحسين إعادة استخدام التخزين المؤقت
للموجّهات فقط عندما يظل الطلب مستهدفًا مسار OpenRouter متحققًا منه
(openrouter على نقطة نهايته الافتراضية، أو أي مزوّد/عنوان URL أساسي يتحول
إلى openrouter.ai).
بالنسبة إلى مراجع نماذج openrouter/deepseek/* وopenrouter/moonshot*/* وopenrouter/zai/*،
يُسمح بـ contextPruning.mode: "cache-ttl" لأن OpenRouter
يتعامل تلقائيًا مع التخزين المؤقت للموجّهات من جهة المزوّد. لا يحقن OpenClaw
علامات cache_control الخاصة بـ Anthropic في تلك الطلبات.
بناء تخزين DeepSeek المؤقت هو أفضل جهد وقد يستغرق بضع ثوانٍ. قد يظل
المتابع الفوري يعرض cached_tokens: 0؛ تحقق بطلب مكرر
بنفس البادئة بعد تأخير قصير واستخدم usage.prompt_tokens_details.cached_tokens
كإشارة إصابة التخزين المؤقت.
إذا أعدت توجيه النموذج إلى عنوان URL وكيل عشوائي متوافق مع OpenAI، يتوقف OpenClaw عن حقن علامات التخزين المؤقت الخاصة بـ Anthropic والمحددة لـ OpenRouter.
مزوّدون آخرون
إذا كان المزوّد لا يدعم وضع التخزين المؤقت هذا، فلن يكون لـ cacheRetention أي تأثير.
واجهة Google Gemini API المباشرة
- يبلّغ نقل Gemini المباشر (
api: "google-generative-ai") عن إصابات التخزين المؤقت عبرcachedContentTokenCountمن المصدر الأعلى؛ يربط OpenClaw ذلك بـcacheRead. - عندما يُضبط
cacheRetentionعلى نموذج Gemini مباشر، ينشئ OpenClaw تلقائيًا مواردcachedContentsلموجّهات النظام في تشغيلات Google AI Studio ويعيد استخدامها ويحدّثها. هذا يعني أنك لم تعد بحاجة إلى إنشاء مقبض محتوى مخزّن مؤقتًا مسبقًا يدويًا. - لا يزال بإمكانك تمرير مقبض محتوى Gemini مخزّن مؤقتًا قائم مسبقًا كـ
params.cachedContent(أو القديمparams.cached_content) على النموذج المُعدّ. - هذا منفصل عن التخزين المؤقت لبادئات الموجّهات في Anthropic/OpenAI. بالنسبة إلى Gemini،
يدير OpenClaw مورد
cachedContentsأصليًا لدى المزوّد بدلًا من حقن علامات التخزين المؤقت في الطلب.
استخدام Gemini CLI
- يمكن أن يبرز خرج Gemini CLI
stream-jsonإصابات التخزين المؤقت عبرstats.cached؛ يربط OpenClaw ذلك بـcacheRead. تستخدم تجاوزات--output-format jsonالقديمة تطبيع الاستخدام نفسه. - إذا حذف CLI قيمة
stats.inputمباشرة، يشتق OpenClaw رموز الإدخال منstats.input_tokens - stats.cached. - هذا تطبيع استخدام فقط. لا يعني أن OpenClaw ينشئ علامات تخزين مؤقت للموجّهات بأسلوب Anthropic/OpenAI من أجل Gemini CLI.
حدّ التخزين المؤقت لموجّه النظام
يقسم OpenClaw موجّه النظام إلى بادئة مستقرة ولاحقة متقلبة
يفصل بينهما حد داخلي لبادئة التخزين المؤقت. يُرتَّب المحتوى أعلى
الحد (تعريفات الأدوات، وبيانات Skills الوصفية، وملفات مساحة العمل، وسياقات أخرى
ثابتة نسبيًا) بحيث يبقى مطابقًا بايتًا ببايت عبر الأدوار.
ويُسمح للمحتوى أسفل الحد (مثل HEARTBEAT.md، وطوابع وقت التشغيل، وبيانات
تعريف أخرى لكل دور) بالتغير من دون إبطال البادئة المخزّنة
مؤقتًا.
اختيارات التصميم الرئيسية:
- تُرتَّب ملفات سياق مشروع مساحة العمل المستقرة قبل
HEARTBEAT.mdبحيث لا يؤدي تغير Heartbeat المتكرر إلى كسر البادئة المستقرة. - يُطبّق الحد عبر تشكيل نقل عائلة Anthropic، وعائلة OpenAI، وGoogle، وCLI بحيث يستفيد كل المزوّدين المدعومين من استقرار البادئة نفسه.
- تُوجّه طلبات Codex Responses وAnthropic Vertex عبر تشكيل تخزين مؤقت واعٍ بالحدود بحيث تبقى إعادة استخدام التخزين المؤقت متوافقة مع ما يتلقاه المزوّدون فعليًا.
- تُطبّع بصمات موجّه النظام (المسافات البيضاء، ونهايات الأسطر، والسياق المضاف عبر hooks، وترتيب قدرات وقت التشغيل) بحيث تشترك الموجّهات غير المتغيرة دلاليًا في KV/التخزين المؤقت عبر الأدوار.
إذا رأيت ارتفاعات غير متوقعة في cacheWrite بعد تغيير في الإعدادات أو مساحة العمل،
فتحقق مما إذا كان التغيير يقع أعلى حد التخزين المؤقت أو أسفله. غالبًا ما يؤدي نقل
المحتوى المتقلب إلى أسفل الحد (أو تثبيته) إلى حل
المشكلة.
حراس استقرار التخزين المؤقت في OpenClaw
يبقي OpenClaw أيضًا عدة أشكال حمولات حساسة للتخزين المؤقت حتمية قبل وصول الطلب إلى المزوّد:
- تُفرز كتالوجات أدوات MCP المضمّنة حتميًا قبل تسجيل الأدوات، بحيث لا تؤدي
تغييرات ترتيب
listTools()إلى تغيير كتلة الأدوات وكسر بادئات التخزين المؤقت للموجّهات. - تحتفظ الجلسات القديمة ذات كتل الصور المستمرة بأحدث 3 أدوار مكتملة كما هي؛ وقد تُستبدل كتل الصور الأقدم المعالجة سابقًا بعلامة بحيث لا تستمر المتابعات الكثيفة بالصور في إعادة إرسال حمولات قديمة كبيرة.
أنماط الضبط
حركة مختلطة (الافتراضي الموصى به)
احتفظ بخط أساس طويل العمر على وكيلك الرئيسي، وعطّل التخزين المؤقت على وكلاء الإشعارات كثيرة الدفعات:
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 دون مدة البقاء لديك فقط للوكلاء الذين يستفيدون من التخزينات المؤقتة الدافئة.
تشخيصات التخزين المؤقت
يكشف OpenClaw تشخيصات مخصصة لتتبع التخزين المؤقت لتشغيلات الوكلاء المضمّنة.
بالنسبة إلى التشخيصات العادية المواجهة للمستخدم، يمكن لـ /status وملخصات الاستخدام الأخرى استخدام
أحدث إدخال استخدام في النص المنسوخ كمصدر رجوع لـ cacheRead /
cacheWrite عندما لا يحتوي إدخال الجلسة الحية على تلك العدادات.
اختبارات الانحدار الحية
يبقي OpenClaw بوابة انحدار حية مشتركة واحدة للبادئات المتكررة، وأدوار الأدوات، وأدوار الصور، والنصوص المنسوخة لأدوات بأسلوب MCP، وضابط Anthropic بلا تخزين مؤقت.
src/agents/live-cache-regression.live.test.tssrc/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
- البادئة الثابتة:
استقر التحقق الحي المدمج الجديد في 2026-04-04 عند:
- البادئة الثابتة:
cacheRead=4864، معدل الإصابة0.966 - نص الأداة:
cacheRead=4608، معدل الإصابة0.896 - نص الصورة:
cacheRead=4864، معدل الإصابة0.954 - نص بنمط MCP:
cacheRead=4608، معدل الإصابة0.891
كان وقت الجدار المحلي الأخير للبوابة المدمجة نحو 88s.
سبب اختلاف التأكيدات:
- يوفّر 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.jsonlincludeMessages:trueincludePrompt:trueincludeSystem:true
مفاتيح تبديل البيئة (تصحيح أخطاء لمرة واحدة)
- يفعّل
OPENCLAW_CACHE_TRACE=1تتبّع التخزين المؤقت. - يتجاوز
OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonlمسار الإخراج. - يبدّل
OPENCLAW_CACHE_TRACE_MESSAGES=0|1التقاط حمولة الرسائل الكاملة. - يبدّل
OPENCLAW_CACHE_TRACE_PROMPT=0|1التقاط نص المطالبة. - يبدّل
OPENCLAW_CACHE_TRACE_SYSTEM=0|1التقاط مطالبة النظام.
ما يجب فحصه
- أحداث تتبّع التخزين المؤقت هي JSONL وتتضمن لقطات مرحلية مثل
session:loadedوprompt:beforeوstream:contextوsession:after. - يظهر تأثير رموز التخزين المؤقت لكل منعطف في أسطح الاستخدام العادية عبر
cacheReadوcacheWrite(على سبيل المثال/usage tokensو/statusوملخصات استخدام الجلسات وتخطيطاتmessages.usageTemplateالمخصصة). - بالنسبة إلى Anthropic، توقّع كلاً من
cacheReadوcacheWriteعندما يكون التخزين المؤقت نشطاً. - بالنسبة إلى OpenAI، توقّع
cacheReadعند إصابات التخزين المؤقت. يمكن أن تبلغ GPT-5.6 Responses أيضاً عنcacheWriteأثناء كتابة مقاطع المطالبة؛ أما حمولات Responses الأخرى التي تحذف عداد الكتابة فتبقيه عند0. - إذا كنت تحتاج إلى تتبّع الطلبات، فسجّل معرّفات الطلبات وترويسات حدود المعدل بشكل منفصل عن مقاييس التخزين المؤقت. يركّز إخراج تتبّع التخزين المؤقت الحالي في OpenClaw على شكل المطالبة/الجلسة واستخدام الرموز الموحّد بدلاً من ترويسات استجابة الموفّر الخام.
استكشاف الأخطاء وإصلاحها بسرعة
- ارتفاع
cacheWriteفي معظم المنعطفات: تحقق من مدخلات مطالبة النظام المتقلبة وتحقق من أن النموذج/الموفّر يدعم إعدادات التخزين المؤقت لديك. - ارتفاع
cacheWriteعلى Anthropic: غالباً يعني أن نقطة فصل التخزين المؤقت تقع على محتوى يتغير في كل طلب. - انخفاض
cacheReadفي OpenAI: تحقق من أن البادئة الثابتة في البداية، وأن البادئة المتكررة لا تقل عن 1024 رمزاً، وأنprompt_cache_keyنفسه يُعاد استخدامه للمنعطفات التي يجب أن تشارك التخزين المؤقت. - لا تأثير من
cacheRetention: تأكد من أن مفتاح النموذج يطابقagents.defaults.models["provider/model"]. - طلبات Bedrock Nova/Mistral مع إعدادات التخزين المؤقت: من المتوقع أن يفرض وقت التشغيل القيمة
none.
المستندات ذات الصلة:
