---
read_when:
    - تريد تقليل تكاليف رموز الموجّه مع الاحتفاظ بالتخزين المؤقت
    - تحتاج إلى سلوك تخزين مؤقت لكل وكيل في إعدادات متعددة الوكلاء
    - أنت تضبط نبضات الإبقاء على السخونة وتشذيب `cache-ttl` معًا
summary: عناصر التحكم في التخزين المؤقت للموجّه، وترتيب الدمج، وسلوك المزوّد، وأنماط الضبط
title: التخزين المؤقت للموجّه
x-i18n:
    generated_at: "2026-04-05T12:55:53Z"
    model: gpt-5.4
    provider: openai
    source_hash: 13d5f3153b6593ae22cd04a6c2540e074cf15df9f1990fc5b7184fe803f4a1bd
    source_path: reference/prompt-caching.md
    workflow: 15
---

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

يعني التخزين المؤقت للموجّه أن مزوّد النموذج يمكنه إعادة استخدام بادئات الموجّه غير المتغيرة (عادةً تعليمات النظام/المطوّر والسياق المستقر الآخر) عبر الأدوار بدلًا من إعادة معالجتها في كل مرة. يقوم OpenClaw بتوحيد استخدام المزوّد إلى `cacheRead` و`cacheWrite` عندما تكشف واجهة API المصدر عن هذه العدادات مباشرةً.

يمكن لأسطح الحالة أيضًا استعادة عدادات التخزين المؤقت من أحدث سجل استخدام
للنص الحواري عندما تفتقد لقطة الجلسة الحية إليها، بحيث يمكن لأمر `/status` أن يستمر
في عرض سطر التخزين المؤقت بعد فقدان جزئي لبيانات تعريف الجلسة. ولا تزال قيم
التخزين المؤقت الحية الحالية غير الصفرية تحظى بالأولوية على قيم الاسترجاع من النص الحواري.

أهمية ذلك: تكلفة رموز أقل، واستجابات أسرع، وأداء أكثر قابلية للتنبؤ للجلسات طويلة التشغيل. بدون التخزين المؤقت، تدفع المطالبات المتكررة تكلفة الموجّه كاملة في كل دور حتى عندما لا يتغير معظم الإدخال.

تغطي هذه الصفحة جميع عناصر التحكم المتعلقة بالتخزين المؤقت التي تؤثر في إعادة استخدام الموجّه وتكلفة الرموز.

مراجع المزوّد:

- التخزين المؤقت للموجّه في Anthropic: [https://platform.claude.com/docs/en/build-with-claude/prompt-caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- التخزين المؤقت للموجّه في OpenAI: [https://developers.openai.com/api/docs/guides/prompt-caching](https://developers.openai.com/api/docs/guides/prompt-caching)
- رؤوس OpenAI API ومعرّفات الطلبات: [https://developers.openai.com/api/reference/overview](https://developers.openai.com/api/reference/overview)
- معرّفات طلبات Anthropic والأخطاء: [https://platform.claude.com/docs/en/api/errors](https://platform.claude.com/docs/en/api/errors)

## عناصر التحكم الأساسية

### `cacheRetention` (الافتراضي العام، والنموذج، ولكل وكيل)

عيّن الاحتفاظ بالتخزين المؤقت كافتراضي عام لجميع النماذج:

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

التجاوز لكل نموذج:

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

التجاوز لكل وكيل:

```yaml
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"`

يُشذّب سياق نتائج الأدوات القديمة بعد نوافذ TTL الخاصة بالتخزين المؤقت حتى لا تعيد الطلبات بعد فترات الخمول تخزين سجل كبير الحجم مؤقتًا مرة أخرى.

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

راجع [تشذيب الجلسات](/ar/concepts/session-pruning) للاطلاع على السلوك الكامل.

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

يمكن لنبضات الإبقاء على السخونة الحفاظ على دفء نوافذ التخزين المؤقت وتقليل عمليات كتابة التخزين المؤقت المتكررة بعد فجوات الخمول.

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

يُدعَم ضبط نبضات الإبقاء على السخونة لكل وكيل عند `agents.list[].heartbeat`.

## سلوك المزوّد

### 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

بالنسبة إلى مراجع النماذج `openrouter/anthropic/*`، يقوم OpenClaw بحقن
`cache_control` الخاص بـ Anthropic في كتل موجّه النظام/المطوّر لتحسين إعادة
استخدام التخزين المؤقت للموجّه فقط عندما يظل الطلب موجّهًا إلى مسار OpenRouter
متحقق منه (`openrouter` على نقطة النهاية الافتراضية الخاصة به، أو أي مزوّد/عنوان أساسي
يُحل إلى `openrouter.ai`).

إذا أعدت توجيه النموذج إلى عنوان proxy عشوائي متوافق مع OpenAI، فسيتوقف OpenClaw
عن حقن علامات التخزين المؤقت الخاصة بـ Anthropic وOpenRouter.

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

إذا كان المزوّد لا يدعم وضع التخزين المؤقت هذا، فلن يكون لـ `cacheRetention` أي تأثير.

### 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.

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

يقسّم OpenClaw موجّه النظام إلى **بادئة مستقرة** و**لاحقة متقلبة**
يفصل بينهما حد داخلي لبادئة التخزين المؤقت. يتم ترتيب المحتوى فوق
الحد (تعريفات الأدوات، وبيانات Skills، وملفات مساحة العمل، وغيرها من
السياقات الثابتة نسبيًا) بحيث يبقى مطابقًا بايتًا لبايت عبر الأدوار.
أما المحتوى أسفل الحد (مثل `HEARTBEAT.md` والطوابع الزمنية وقت التشغيل
وغيرها من البيانات الوصفية الخاصة بكل دور) فيُسمح له بالتغير
من دون إبطال البادئة المخزنة مؤقتًا.

خيارات التصميم الأساسية:

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

إذا لاحظت ارتفاعات غير متوقعة في `cacheWrite` بعد تغيير في الإعدادات أو مساحة العمل،
فتحقق مما إذا كان التغيير يقع فوق حد التخزين المؤقت أو تحته. غالبًا ما يؤدي نقل
المحتوى المتقلب إلى أسفل الحد (أو تثبيته) إلى حل المشكلة.

## وسائل الحماية من ثبات التخزين المؤقت في OpenClaw

يحافظ OpenClaw أيضًا على حتمية عدة أشكال من الحمولات الحساسة للتخزين المؤقت قبل
أن يصل الطلب إلى المزوّد:

- تُفرَز كتالوجات أدوات MCP المجمّعة بشكل حتمي قبل
  تسجيل الأدوات، بحيث لا تؤدي تغييرات ترتيب `listTools()` إلى تقلب كتلة الأدوات
  وإفساد بادئات التخزين المؤقت للموجّه.
- تحتفظ الجلسات القديمة ذات كتل الصور المحفوظة بأحدث **3 أدوار مكتملة**
  كما هي؛ ويمكن استبدال كتل الصور القديمة التي تمت معالجتها بالفعل
  بعلامة حتى لا تستمر المتابعات الثقيلة بالصور في إعادة إرسال
  حمولات كبيرة قديمة.

## أنماط الضبط

### حركة مختلطة (الافتراضي الموصى به)

احتفظ بخط أساس طويل العمر على وكيلك الرئيسي، وعطّل التخزين المؤقت على وكلاء الإشعارات المتقطعين:

```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"
```

### خط أساس يركز على التكلفة أولًا

- عيّن خط الأساس على `cacheRetention: "short"`.
- فعّل `contextPruning.mode: "cache-ttl"`.
- أبقِ نبضات الإبقاء على السخونة أقل من TTL فقط للوكلاء الذين يستفيدون من التخزين المؤقت الدافئ.

## تشخيصات التخزين المؤقت

يكشف OpenClaw عن تشخيصات مخصصة لتتبع التخزين المؤقت لتشغيلات الوكلاء المضمّنة.

بالنسبة إلى التشخيصات العادية الموجهة للمستخدم، يمكن لـ `/status` وملخصات الاستخدام الأخرى استخدام
أحدث إدخال استخدام في النص الحواري كمصدر احتياطي لـ `cacheRead` /
`cacheWrite` عندما لا يحتوي إدخال الجلسة الحية على هذه العدادات.

## اختبارات الانحدار الحية

يحتفظ OpenClaw ببوابة انحدار حية واحدة مدمجة للبادئات المتكررة، وأدوار الأدوات، وأدوار الصور، والنصوص الحوارية للأدوات بأسلوب MCP، وحالة تحكم بدون تخزين مؤقت لـ Anthropic.

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

شغّل البوابة الحية الضيقة باستخدام:

```sh
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`

```yaml
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](/ar/providers/anthropic)
- [استخدام الرموز والتكاليف](/reference/token-use)
- [تشذيب الجلسات](/ar/concepts/session-pruning)
- [مرجع إعدادات البوابة](/ar/gateway/configuration-reference)
