​

التخزين المؤقت للموجّه

• التخزين المؤقت للموجّه في 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"

1. agents.defaults.params (الافتراضي العام — ينطبق على جميع النماذج)
2. agents.defaults.models["provider/model"].params (تجاوز لكل نموذج)
3. agents.list[].params (معرّف الوكيل المطابق؛ يتجاوز حسب المفتاح)

​

contextPruning.mode: "cache-ttl"

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

​

نبضات الإبقاء على السخونة

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

​

سلوك المزوّد

​

Anthropic (واجهة API مباشرة)

• cacheRetention مدعوم.
• مع ملفات تعريف مصادقة مفتاح API الخاصة بـ Anthropic، يضبط OpenClaw القيمة cacheRetention: "short" افتراضيًا لمراجع نماذج Anthropic عندما لا تكون معيّنة.
• تكشف استجابات Messages الأصلية من Anthropic كلًا من cache_read_input_tokens وcache_creation_input_tokens، لذلك يمكن لـ OpenClaw عرض كل من cacheRead وcacheWrite.
• بالنسبة إلى طلبات Anthropic الأصلية، تُطابِق cacheRetention: "short" التخزين المؤقت المؤقت الافتراضي لمدة 5 دقائق، وتُرقّي cacheRetention: "long" إلى TTL لمدة ساعة واحدة فقط على مضيفات api.anthropic.com المباشرة.

​

OpenAI (واجهة API مباشرة)

• يكون التخزين المؤقت للموجّه تلقائيًا على النماذج الحديثة المدعومة. لا يحتاج OpenClaw إلى حقن علامات تخزين مؤقت على مستوى الكتل.
• يستخدم OpenClaw القيمة prompt_cache_key للحفاظ على استقرار توجيه التخزين المؤقت عبر الأدوار، ويستخدم prompt_cache_retention: "24h" فقط عند اختيار cacheRetention: "long" على مضيفات OpenAI المباشرة.
• تكشف استجابات OpenAI عن رموز الموجّه المخزنة مؤقتًا عبر usage.prompt_tokens_details.cached_tokens (أو input_tokens_details.cached_tokens في أحداث Responses API). ويحوّل OpenClaw ذلك إلى cacheRead.
• لا يكشف OpenAI عن عدّاد منفصل لرموز كتابة التخزين المؤقت، لذلك تبقى cacheWrite عند 0 في مسارات OpenAI حتى عندما يكون المزوّد يدفئ التخزين المؤقت.
• يعيد 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" القيمة TTL الفعلية لمدة ساعة واحدة لذاكرة التخزين المؤقت للموجّه على نقاط نهاية Vertex AI.
• يتطابق الاحتفاظ الافتراضي بالتخزين المؤقت لـ anthropic-vertex مع افتراضيات Anthropic المباشر.
• تُوجَّه طلبات Vertex عبر تشكيل تخزين مؤقت واعٍ بالحدود حتى تبقى إعادة استخدام التخزين المؤقت متوافقة مع ما يتلقاه المزوّدون فعليًا.

​

Amazon Bedrock

• تدعم مراجع نماذج Anthropic Claude (amazon-bedrock/*anthropic.claude*) تمرير cacheRetention الصريح.
• تُفرَض القيمة cacheRetention: "none" وقت التشغيل على نماذج Bedrock غير التابعة لـ Anthropic.

​

نماذج Anthropic عبر OpenRouter

​

مزوّدون آخرون

​

Google Gemini API مباشرة

• ينقل Gemini المباشر (api: "google-generative-ai") إصابات التخزين المؤقت عبر cachedContentTokenCount من المصدر؛ ويحوّل OpenClaw ذلك إلى cacheRead.
• عند تعيين cacheRetention على نموذج Gemini مباشر، ينشئ OpenClaw تلقائيًا موارد cachedContents ويعيد استخدامها ويحدّثها لموجّهات النظام في عمليات Google AI Studio. وهذا يعني أنك لم تعد بحاجة إلى إنشاء مقبض cached-content مسبقًا يدويًا.
• لا يزال بإمكانك تمرير مقبض Gemini cached-content موجود مسبقًا عبر params.cachedContent (أو params.cached_content القديم) على النموذج المهيأ.
• هذا منفصل عن التخزين المؤقت لبادئة الموجّه في Anthropic/OpenAI. بالنسبة إلى Gemini، يدير OpenClaw مورد cachedContents أصليًا من المزوّد بدلًا من حقن علامات تخزين مؤقت في الطلب.

​

استخدام JSON في Gemini CLI

• يمكن لمخرجات JSON في Gemini CLI أيضًا إظهار إصابات التخزين المؤقت عبر stats.cached؛ ويحوّل OpenClaw ذلك إلى cacheRead.
• إذا أغفل CLI قيمة stats.input مباشرةً، يشتق OpenClaw رموز الإدخال من stats.input_tokens - stats.cached.
• هذا مجرد توحيد للاستخدام. ولا يعني أن OpenClaw ينشئ علامات تخزين مؤقت للموجّه بأسلوب Anthropic/OpenAI من أجل Gemini CLI.

​

حد التخزين المؤقت لموجّه النظام

• تُرتَّب ملفات سياق مشروع مساحة العمل المستقرة قبل HEARTBEAT.md بحيث لا يؤدي تغيّر نبضات الإبقاء على السخونة إلى إفساد البادئة المستقرة.
• يُطبَّق الحد عبر تشكيل الطلبات لعائلة Anthropic وعائلة OpenAI وGoogle وCLI بحيث تستفيد جميع المزوّدات المدعومة من الاستقرار نفسه للبادئة.
• تُوجَّه طلبات Codex Responses وAnthropic Vertex عبر تشكيل تخزين مؤقت واعٍ بالحدود بحيث تبقى إعادة استخدام التخزين المؤقت متوافقة مع ما يتلقاه المزوّدون فعليًا.
• تُطبَّع بصمات موجّه النظام (المسافات البيضاء، ونهايات الأسطر، والسياق المضاف بواسطة hooks، وترتيب قدرات وقت التشغيل) بحيث تشترك الموجّهات غير المتغيرة دلاليًا في KV/التخزين المؤقت عبر الأدوار.

​

وسائل الحماية من ثبات التخزين المؤقت في 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".
• أبقِ نبضات الإبقاء على السخونة أقل من 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.
• توقّع إعادة استخدام شبه كاملة للسجل في الأدوار المتكررة لأن التحكم في التخزين المؤقت لدى 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

• بادئة مستقرة: cacheRead=4864، معدل الإصابة 0.966
• نص حواري للأدوات: cacheRead=4608، معدل الإصابة 0.896
• نص حواري للصور: cacheRead=4864، معدل الإصابة 0.954
• نص حواري بأسلوب MCP: cacheRead=4608، معدل الإصابة 0.891

• يكشف Anthropic عن نقاط توقف تخزين مؤقت صريحة وإعادة استخدام متحركة لسجل المحادثة.
• لا يزال التخزين المؤقت للموجّه في OpenAI حساسًا للبادئة المطابقة تمامًا، لكن البادئة الفعلية القابلة لإعادة الاستخدام في حركة Responses الحية قد تستقر مبكرًا قبل الموجّه الكامل.
• لذلك، فإن مقارنة Anthropic وOpenAI باستخدام حد نسبة مئوية واحد عبر المزوّدين تُنشئ إنذارات انحدار كاذبة.

​

إعداد diagnostics.cacheTrace

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # اختياري
    includeMessages: false # الافتراضي true
    includePrompt: false # الافتراضي true
    includeSystem: false # الافتراضي true

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: 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 full وملخصات استخدام الجلسات).
• بالنسبة إلى Anthropic، توقّع وجود كل من cacheRead وcacheWrite عندما يكون التخزين المؤقت نشطًا.
• بالنسبة إلى OpenAI، توقّع cacheRead عند إصابات التخزين المؤقت وأن تبقى cacheWrite عند 0؛ إذ لا ينشر OpenAI حقلًا منفصلًا لرموز كتابة التخزين المؤقت.
• إذا كنت تحتاج إلى تتبع الطلبات، فسجّل معرّفات الطلبات ورؤوس حدود المعدل بشكل منفصل عن مقاييس التخزين المؤقت. يركز مخرج تتبع التخزين المؤقت الحالي في OpenClaw على شكل الموجّه/الجلسة واستخدام الرموز الموحّد بدلًا من رؤوس استجابة المزوّد الخام.

​

استكشاف الأخطاء وإصلاحها بسرعة

• ارتفاع cacheWrite في معظم الأدوار: تحقق من مدخلات موجّه النظام المتقلبة وتأكد من أن النموذج/المزوّد يدعم إعدادات التخزين المؤقت الخاصة بك.
• ارتفاع cacheWrite في Anthropic: يعني غالبًا أن نقطة توقف التخزين المؤقت تقع على محتوى يتغير في كل طلب.
• انخفاض cacheRead في OpenAI: تحقق من أن البادئة المستقرة موجودة في المقدمة، وأن البادئة المتكررة لا تقل عن 1024 رمزًا، وأن prompt_cache_key نفسه يُعاد استخدامه للأدوار التي يجب أن تشترك في التخزين المؤقت.
• لا يوجد تأثير من cacheRetention: تأكد من أن مفتاح النموذج يطابق agents.defaults.models["provider/model"].
• طلبات Bedrock Nova/Mistral مع إعدادات التخزين المؤقت: من المتوقع فرضها وقت التشغيل إلى none.

• Anthropic
• استخدام الرموز والتكاليف
• تشذيب الجلسات
• مرجع إعدادات البوابة