---
read_when:
    - تحتاج إلى استكشاف أخطاء معرّفات الجلسات أو JSONL لسجل المحادثة أو حقول sessions.json وإصلاحها
    - أنت تغيّر سلوك Compaction التلقائي أو تضيف مهام صيانة "ما قبل Compaction"
    - تريد تنفيذ عمليات تفريغ الذاكرة أو دورات النظام الصامتة
summary: 'نظرة معمّقة: مخزن الجلسات + سجلات المحادثات، ودورة الحياة، وداخليات Compaction (التلقائي)'
title: تعمّق في إدارة الجلسات
x-i18n:
    generated_at: "2026-05-11T20:40:45Z"
    model: gpt-5.5
    provider: openai
    source_hash: 4ed30f6b1943b2ed5808c5ccdd593e6899e10fb7f75ff5911e6a9623a30ed6be
    source_path: reference/session-management-compaction.md
    workflow: 16
---

يدير OpenClaw الجلسات من البداية إلى النهاية عبر هذه المجالات:

- **توجيه الجلسات** (كيف ترتبط الرسائل الواردة بـ `sessionKey`)
- **مخزن الجلسات** (`sessions.json`) وما يتتبعه
- **استدامة سجل المحادثة** (`*.jsonl`) وبنيته
- **نظافة سجل المحادثة** (تصحيحات خاصة بالمزوّدين قبل التشغيل)
- **حدود السياق** (نافذة السياق مقابل الرموز المتتبعة)
- **Compaction** (يدوي وتلقائي) وموضع ربط عمل ما قبل Compaction
- **الصيانة الصامتة** (كتابات الذاكرة التي يجب ألا تنتج مخرجات مرئية للمستخدم)

إذا أردت نظرة عامة أعلى مستوى أولًا، فابدأ بـ:

- [إدارة الجلسات](/ar/concepts/session)
- [Compaction](/ar/concepts/compaction)
- [نظرة عامة على الذاكرة](/ar/concepts/memory)
- [بحث الذاكرة](/ar/concepts/memory-search)
- [تقليم الجلسات](/ar/concepts/session-pruning)
- [نظافة سجل المحادثة](/ar/reference/transcript-hygiene)

---

## مصدر الحقيقة: Gateway

صُمم OpenClaw حول **عملية Gateway** واحدة تملك حالة الجلسة.

- يجب أن تستعلم واجهات المستخدم (تطبيق macOS، واجهة التحكم على الويب، TUI) من Gateway عن قوائم الجلسات وعدد الرموز.
- في الوضع البعيد، تكون ملفات الجلسات على المضيف البعيد؛ ولن يعكس "فحص ملفات Mac المحلية لديك" ما يستخدمه Gateway.

---

## طبقتا استدامة

يستديم OpenClaw الجلسات في طبقتين:

1. **مخزن الجلسات (`sessions.json`)**
   - خريطة مفتاح/قيمة: `sessionKey -> SessionEntry`
   - صغير، قابل للتغيير، وآمن للتحرير (أو حذف الإدخالات)
   - يتتبع بيانات تعريف الجلسة (معرّف الجلسة الحالي، آخر نشاط، المفاتيح التبديلية، عدّادات الرموز، إلخ)

2. **سجل المحادثة (`<sessionId>.jsonl`)**
   - سجل محادثة إلحاقي فقط ببنية شجرية (تحتوي الإدخالات على `id` + `parentId`)
   - يخزّن المحادثة الفعلية + استدعاءات الأدوات + ملخصات Compaction
   - يُستخدم لإعادة بناء سياق النموذج للدورات المستقبلية
   - تُتخطى نقاط فحص التصحيح الكبيرة قبل Compaction بمجرد أن يتجاوز سجل
     المحادثة النشط حد حجم نقطة الفحص، لتجنب نسخة `.checkpoint.*.jsonl`
     عملاقة ثانية.

يجب أن يتجنب قارئو سجل Gateway تحميل سجل المحادثة كاملًا في الذاكرة ما لم
تحتج الواجهة صراحةً إلى وصول تاريخي عشوائي. تستخدم عمليات سجل الصفحة الأولى،
وسجل الدردشة المضمّن، واسترداد إعادة التشغيل، وفحوصات الرموز/الاستخدام قراءات
ذيل محدودة. تمر عمليات الفحص الكاملة لسجل المحادثة عبر فهرس سجل المحادثة غير
المتزامن، والذي يُخزّن مؤقتًا حسب مسار الملف إضافةً إلى `mtimeMs`/`size` ويُشارك
بين القرّاء المتزامنين.

---

## المواقع على القرص

لكل وكيل، على مضيف Gateway:

- المخزن: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- سجلات المحادثة: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
  - جلسات موضوع Telegram: `.../<sessionId>-topic-<threadId>.jsonl`

يحل OpenClaw هذه المسارات عبر `src/config/sessions.ts`.

---

## صيانة المخزن وضوابط القرص

تحتوي استدامة الجلسات على ضوابط صيانة تلقائية (`session.maintenance`) لـ `sessions.json`، وآثار سجل المحادثة، والملفات الجانبية للمسارات:

- `mode`: `warn` (افتراضي) أو `enforce`
- `pruneAfter`: حد عمر الإدخال القديم (افتراضيًا `30d`)
- `maxEntries`: حد الإدخالات في `sessions.json` (افتراضيًا `500`)
- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات سجل المحادثة `*.reset.<timestamp>` (افتراضيًا: مثل `pruneAfter`؛ يعطل `false` التنظيف)
- `maxDiskBytes`: ميزانية اختيارية لدليل الجلسات
- `highWaterBytes`: هدف اختياري بعد التنظيف (افتراضيًا `80%` من `maxDiskBytes`)

تمر كتابات Gateway العادية عبر كاتب جلسات لكل مخزن، يسلْسل التغييرات داخل العملية من دون أخذ قفل ملف وقت التشغيل. تستعير مساعدات التصحيح في المسارات الساخنة ذاكرة التخزين المؤقت القابلة للتغيير والمتحقق منها أثناء احتفاظها بموضع الكاتب، لذلك لا تُنسخ ملفات `sessions.json` الكبيرة أو تُعاد قراءتها لكل تحديث بيانات تعريف. يجب أن يفضل كود وقت التشغيل `updateSessionStore(...)` أو `updateSessionStoreEntry(...)`؛ أما عمليات حفظ المخزن كاملًا مباشرةً فهي أدوات توافق وصيانة خارج الاتصال. عندما يمكن الوصول إلى Gateway، يفوض `openclaw sessions cleanup` غير التجريبي و`openclaw agents delete` تغييرات المخزن إلى Gateway حتى ينضم التنظيف إلى طابور الكاتب نفسه؛ ويكون `--store <path>` هو مسار الإصلاح خارج الاتصال الصريح لصيانة الملفات مباشرةً. لا يزال تنظيف `maxEntries` يُجمّع على دفعات للحدود ذات الحجم الإنتاجي، لذلك قد يتجاوز المخزن مؤقتًا الحد المكوّن قبل أن يعيده تنظيف مستوى الماء العالي التالي إلى ما دونه. لا تقلّم قراءات مخزن الجلسات الإدخالات أو تحدها أثناء بدء Gateway؛ استخدم الكتابات أو `openclaw sessions cleanup --enforce` للتنظيف. لا يزال `openclaw sessions cleanup --enforce` يطبق الحد المكوّن فورًا ويقلّم آثار سجل المحادثة ونقاط الفحص والمسارات القديمة غير المشار إليها حتى عند عدم تكوين ميزانية قرص.

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

لم يعد OpenClaw ينشئ نسخ تدوير احتياطية تلقائية `sessions.json.bak.*` أثناء كتابات Gateway. يُتجاهل مفتاح `session.maintenance.rotateBytes` القديم ويزيله `openclaw doctor --fix` من الإعدادات الأقدم.

تستخدم تغييرات سجل المحادثة قفل كتابة جلسة على ملف سجل المحادثة. ينتظر الحصول على القفل حتى
`session.writeLock.acquireTimeoutMs` قبل إظهار خطأ جلسة مشغولة؛ الافتراضي هو `60000`
مللي ثانية. ارفع هذا فقط عندما تتنافس أعمال تحضير أو تنظيف أو Compaction أو عكس سجل محادثة مشروعة
لفترة أطول على الأجهزة البطيئة. تبقى سياسات كشف القفل القديم وتحذيرات مدة الاحتفاظ القصوى منفصلة.

ترتيب فرض تنظيف ميزانية القرص (`mode: "enforce"`):

1. أزل أولًا أقدم آثار الأرشيف أو سجل المحادثة اليتيم أو المسار اليتيم.
2. إذا بقي الاستخدام فوق الهدف، فأخرج أقدم إدخالات الجلسات وملفات سجل المحادثة/المسار الخاصة بها.
3. استمر حتى يصبح الاستخدام عند `highWaterBytes` أو دونه.

في `mode: "warn"`، يبلغ OpenClaw عن عمليات الإخراج المحتملة لكنه لا يغيّر المخزن/الملفات.

شغّل الصيانة عند الطلب:

```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce
```

---

## جلسات Cron وسجلات التشغيل

تنشئ عمليات Cron المعزولة أيضًا إدخالات جلسات/سجلات محادثة، ولها ضوابط احتفاظ مخصصة:

- `cron.sessionRetention` (افتراضيًا `24h`) يقلّم جلسات تشغيل Cron المعزولة القديمة من مخزن الجلسات (يعطل `false` ذلك).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يقلّمان ملفات `~/.openclaw/cron/runs/<jobId>.jsonl` (الافتراضيات: `2_000_000` بايت و`2000` سطر).

عندما ينشئ Cron قسرًا جلسة تشغيل معزولة جديدة، فإنه يعقم إدخال جلسة
`cron:<jobId>` السابق قبل كتابة الصف الجديد. ويحمل تفضيلات آمنة مثل إعدادات
التفكير/السرعة/الإسهاب، والتسميات، وتجاوزات النموذج/المصادقة المحددة صراحةً
من المستخدم. ويسقط سياق المحادثة المحيط مثل توجيه القناة/المجموعة، وسياسة
الإرسال أو الطابور، والرفع، والأصل، وربط وقت تشغيل ACP حتى لا ترث عملية
معزولة جديدة تسليمًا قديمًا أو سلطة وقت تشغيل من عملية أقدم.

---

## مفاتيح الجلسات (`sessionKey`)

يحدد `sessionKey` _سلة المحادثة التي أنت فيها_ (التوجيه + العزل).

الأنماط الشائعة:

- الدردشة الرئيسية/المباشرة (لكل وكيل): `agent:<agentId>:<mainKey>` (افتراضيًا `main`)
- المجموعة: `agent:<agentId>:<channel>:group:<id>`
- الغرفة/القناة (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` أو `...:room:<id>`
- Cron: `cron:<job.id>`
- Webhook: `hook:<uuid>` (ما لم يُتجاوز)

القواعد الرسمية موثقة في [/concepts/session](/ar/concepts/session).

---

## معرّفات الجلسات (`sessionId`)

يشير كل `sessionKey` إلى `sessionId` حالي (ملف سجل المحادثة الذي يواصل المحادثة).

قواعد عامة:

- **إعادة التعيين** (`/new`، `/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`.
- **إعادة التعيين اليومية** (افتراضيًا الساعة 4:00 صباحًا بالتوقيت المحلي على مضيف Gateway) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة التعيين.
- **انتهاء الصلاحية بسبب الخمول** (`session.reset.idleMinutes` أو `session.idleMinutes` القديم) ينشئ `sessionId` جديدًا عند وصول رسالة بعد نافذة الخمول. عند تكوين اليومية + الخمول معًا، يفوز أيهما تنتهي صلاحيته أولًا.
- **أحداث النظام** (Heartbeat، تنبيهات إيقاظ Cron، إشعارات التنفيذ، مسك دفاتر Gateway) قد تغيّر صف الجلسة لكنها لا تمدد حداثة إعادة التعيين اليومية/الخمول. يتخلص انتقال إعادة التعيين من إشعارات أحداث النظام المنتظرة للجلسة السابقة قبل بناء الموجه الجديد.
- **سياسة تفريع الوالد** تستخدم الفرع النشط لـ Pi عند إنشاء خيط أو تفريع وكيل فرعي. إذا كان ذلك الفرع كبيرًا جدًا، يبدأ OpenClaw الطفل بسياق معزول بدلًا من الفشل أو وراثة سجل غير قابل للاستخدام. سياسة التحجيم تلقائية؛ يزيل `openclaw doctor --fix` إعداد `session.parentForkMaxTokens` القديم.

تفصيل تنفيذي: يحدث القرار في `initSessionState()` في `src/auto-reply/reply/session.ts`.

---

## مخطط مخزن الجلسات (`sessions.json`)

نوع قيمة المخزن هو `SessionEntry` في `src/config/sessions.ts`.

حقول رئيسية (ليست شاملة):

- `sessionId`: معرّف سجل المحادثة الحالي (يُشتق اسم الملف من هذا ما لم يُعيّن `sessionFile`)
- `sessionStartedAt`: الطابع الزمني لبداية `sessionId` الحالي؛ تستخدم حداثة إعادة التعيين اليومية
  هذا الحقل. قد تستمد الصفوف القديمة ذلك من ترويسة جلسة JSONL.
- `lastInteractionAt`: الطابع الزمني لآخر تفاعل حقيقي من مستخدم/قناة؛ تستخدم حداثة إعادة تعيين
  الخمول هذا الحقل حتى لا تبقي أحداث Heartbeat وCron والتنفيذ الجلسات
  حية. تعود الصفوف القديمة التي لا تحتوي على هذا الحقل إلى وقت بدء الجلسة المسترد
  لحداثة الخمول.
- `updatedAt`: الطابع الزمني لآخر تغيير في صف المخزن، يُستخدم للعرض، والتقليم، ومسك
  الدفاتر. ليس هو السلطة لحداثة إعادة التعيين اليومية/الخمول.
- `sessionFile`: تجاوز اختياري صريح لمسار سجل المحادثة
- `chatType`: `direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال)
- `provider`, `subject`, `room`, `space`, `displayName`: بيانات تعريف لتسمية المجموعة/القناة
- المفاتيح التبديلية:
  - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
  - `sendPolicy` (تجاوز لكل جلسة)
- اختيار النموذج:
  - `providerOverride`, `modelOverride`, `authProfileOverride`
- عدّادات الرموز (أفضل جهد / معتمدة على المزوّد):
  - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: عدد مرات اكتمال Compaction التلقائي لمفتاح الجلسة هذا
- `memoryFlushAt`: الطابع الزمني لآخر تفريغ ذاكرة قبل Compaction
- `memoryFlushCompactionCount`: عدد مرات Compaction عندما شُغّل آخر تفريغ

المخزن آمن للتحرير، لكن Gateway هو السلطة: قد يعيد كتابة الإدخالات أو يعيد ترطيبها أثناء تشغيل الجلسات.

---

## بنية سجل المحادثة (`*.jsonl`)

تُدار سجلات المحادثة بواسطة `SessionManager` الخاص بـ `@earendil-works/pi-coding-agent`.

الملف بتنسيق JSONL:

- السطر الأول: ترويسة الجلسة (`type: "session"`، تتضمن `id`، و`cwd`، و`timestamp`، و`parentSession` اختياريًا)
- ثم: إدخالات الجلسة مع `id` + `parentId` (شجرة)

أنواع إدخال بارزة:

- `message`: رسائل المستخدم/المساعد/نتيجة الأداة
- `custom_message`: رسائل محقونة من الملحقات _تدخل_ سياق النموذج (يمكن إخفاؤها عن واجهة المستخدم)
- `custom`: حالة ملحق _لا_ تدخل سياق النموذج
- `compaction`: ملخص Compaction مستدام مع `firstKeptEntryId` و`tokensBefore`
- `branch_summary`: ملخص مستدام عند التنقل في فرع شجرة

يتعمد OpenClaw **عدم** "تصحيح" سجلات المحادثة؛ يستخدم Gateway `SessionManager` لقراءتها/كتابتها.

---

## نوافذ السياق مقابل الرموز المتتبعة

هناك مفهومان مختلفان مهمان:

1. **نافذة سياق النموذج**: حد صارم لكل نموذج (الرموز المرئية للنموذج)
2. **عدّادات مخزن الجلسة**: إحصاءات متدحرجة تُكتب في `sessions.json` (تُستخدم لـ /status ولوحات المعلومات)

إذا كنت تضبط الحدود:

- تأتي نافذة السياق من كتالوج النماذج (ويمكن تجاوزها عبر الإعدادات).
- `contextTokens` في المخزن قيمة تقديرية/إبلاغية وقت التشغيل؛ لا تتعامل معها كضمان صارم.

للمزيد، راجع [/token-use](/ar/reference/token-use).

---

## Compaction: ما هو

يلخص Compaction المحادثة الأقدم في إدخال `compaction` مستدام في سجل المحادثة، ويبقي الرسائل الحديثة كما هي.

بعد Compaction، ترى الدورات المستقبلية:

- ملخص Compaction
- الرسائل بعد `firstKeptEntryId`

Compaction **دائم** (بخلاف تقليم الجلسة). راجع [/concepts/session-pruning](/ar/concepts/session-pruning).

## حدود أجزاء Compaction واقتران الأدوات

عندما يقسم OpenClaw نصًا طويلاً إلى أجزاء Compaction، فإنه يبقي
استدعاءات أدوات المساعد مقترنة بإدخالات `toolResult` المطابقة لها.

- إذا وقع تقسيم حصة الرموز بين استدعاء أداة ونتيجته، فإن OpenClaw
  ينقل الحد إلى رسالة استدعاء أداة المساعد بدلاً من فصل
  الزوج.
- إذا كان من شأن كتلة نتيجة أداة لاحقة أن تتجاوز بالجزء الهدف،
  فإن OpenClaw يحافظ على كتلة الأداة المعلقة تلك ويبقي الذيل غير الملخص
  سليمًا.
- لا تبقي كتل استدعاءات الأدوات الملغاة/الخاطئة تقسيمًا معلقًا مفتوحًا.

---

## متى يحدث Compaction التلقائي (وقت تشغيل Pi)

في وكيل Pi المضمن، يبدأ Compaction التلقائي في حالتين:

1. **استرداد الفائض**: يعيد النموذج خطأ فيضان السياق
   (`request_too_large`, `context length exceeded`, `input exceeds the maximum
number of tokens`, `input token count exceeds the maximum number of input
tokens`, `input is too long for the model`, `ollama error: context length
exceeded`، ومتغيرات مشابهة بصياغة المزوّد) → Compaction → إعادة المحاولة.
2. **صيانة العتبة**: بعد دورة ناجحة، عندما:

`contextTokens > contextWindow - reserveTokens`

حيث:

- `contextWindow` هي نافذة سياق النموذج
- `reserveTokens` هي مساحة احتياطية محجوزة للمطالبات + خرج النموذج التالي

هذه دلالات وقت تشغيل Pi (يستهلك OpenClaw الأحداث، لكن Pi يقرر متى يجري Compaction).

يمكن لـ OpenClaw أيضًا تشغيل Compaction محلي تمهيدي قبل فتح التشغيل التالي
عند ضبط `agents.defaults.compaction.maxActiveTranscriptBytes` ووصول ملف
النص النشط إلى ذلك الحجم. هذا حاجز لحجم الملف لتكلفة إعادة الفتح المحلية،
وليس أرشفة أولية: لا يزال OpenClaw يشغّل Compaction الدلالي المعتاد،
ويتطلب `truncateAfterCompaction` حتى يمكن للملخص المضغوط أن يصبح
نصًا لاحقًا جديدًا.

بالنسبة لتشغيلات Pi المضمنة، يضيف `agents.defaults.compaction.midTurnPrecheck.enabled: true`
حاجزًا اختياريًا لحلقة الأدوات. بعد إلحاق نتيجة أداة وقبل استدعاء
النموذج التالي، يقدّر OpenClaw ضغط المطالبة باستخدام منطق الميزانية التمهيدية نفسه
المستخدم عند بداية الدورة. إذا لم يعد السياق مناسبًا، لا يجري الحاجز
Compaction داخل خطاف `transformContext` الخاص بـ Pi. بل يرفع إشارة
فحص تمهيدي منظمة في منتصف الدورة، ويوقف إرسال المطالبة الحالي، ويتيح
لحلقة التشغيل الخارجية استخدام مسار الاسترداد الحالي: اقتطاع نتائج الأدوات كبيرة الحجم
عندما يكون ذلك كافيًا، أو تشغيل وضع Compaction المضبوط وإعادة المحاولة. يكون
الخيار معطلاً افتراضيًا ويعمل مع وضعي Compaction `default` و`safeguard`
كليهما، بما في ذلك Compaction الحماية المدعوم بمزوّد.
هذا مستقل عن `maxActiveTranscriptBytes`: يعمل حاجز حجم البايتات
قبل فتح الدورة، بينما يعمل الفحص التمهيدي في منتصف الدورة لاحقًا في حلقة أدوات Pi
المضمنة بعد إلحاق نتائج أدوات جديدة.

---

## إعدادات Compaction (`reserveTokens`, `keepRecentTokens`)

توجد إعدادات Compaction الخاصة بـ Pi في إعدادات Pi:

```json5
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}
```

يفرض OpenClaw أيضًا حدًا أدنى آمنًا للتشغيلات المضمنة:

- إذا كان `compaction.reserveTokens < reserveTokensFloor`، يرفعه OpenClaw.
- الحد الافتراضي هو `20000` رمز.
- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل الحد.
- إذا كان أعلى بالفعل، يتركه OpenClaw كما هو.
- يحترم `/compact` اليدوي قيمة `agents.defaults.compaction.keepRecentTokens`
  الصريحة ويبقي نقطة قطع الذيل الحديث الخاصة بـ Pi. ومن دون ميزانية إبقاء صريحة،
  يبقى Compaction اليدوي نقطة تحقق صارمة ويبدأ السياق المعاد بناؤه من
  الملخص الجديد.
- اضبط `agents.defaults.compaction.midTurnPrecheck.enabled: true` لتشغيل
  الفحص التمهيدي الاختياري لحلقة الأدوات بعد نتائج الأدوات الجديدة وقبل استدعاء
  النموذج التالي. هذا مشغل فقط؛ لا يزال توليد الملخص يستخدم مسار
  Compaction المضبوط. وهو مستقل عن `maxActiveTranscriptBytes`، وهو
  حاجز حجم بايتات النص النشط عند بداية الدورة.
- اضبط `agents.defaults.compaction.maxActiveTranscriptBytes` على قيمة بايتات أو
  سلسلة مثل `"20mb"` لتشغيل Compaction محلي قبل دورة عندما يكبر
  النص النشط. يكون هذا الحاجز نشطًا فقط عندما يكون
  `truncateAfterCompaction` ممكّنًا أيضًا. اتركه غير مضبوط أو اضبطه على `0`
  للتعطيل.
- عند تمكين `agents.defaults.compaction.truncateAfterCompaction`،
  يدير OpenClaw النص النشط إلى ملف JSONL لاحق مضغوط بعد
  Compaction. يبقى النص الكامل القديم مؤرشفًا ومربوطًا من نقطة تحقق
  Compaction بدلاً من إعادة كتابته في مكانه.

السبب: ترك مساحة احتياطية كافية لأعمال "الصيانة" متعددة الدورات (مثل كتابات الذاكرة) قبل أن يصبح Compaction لا مفر منه.

التنفيذ: `ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts`
(تُستدعى من `src/agents/pi-embedded-runner.ts`).

---

## مزوّدو Compaction القابلون للتوصيل

يمكن لـ Plugins تسجيل مزوّد Compaction عبر `registerCompactionProvider()` في واجهة API الخاصة بـ Plugin. عندما يتم ضبط `agents.defaults.compaction.provider` على معرّف مزوّد مسجل، يفوض امتداد الحماية التلخيص إلى ذلك المزوّد بدلاً من مسار `summarizeInStages` المدمج.

- `provider`: معرّف Plugin مزوّد Compaction مسجل. اتركه غير مضبوط لاستخدام تلخيص LLM الافتراضي.
- ضبط `provider` يفرض `mode: "safeguard"`.
- يتلقى المزوّدون تعليمات Compaction وسياسة الحفاظ على المعرّفات نفسها مثل المسار المدمج.
- لا تزال الحماية تحافظ على سياق لاحقة الدورات الحديثة والدورات المقسمة بعد خرج المزوّد.
- يعيد التلخيص المدمج في وضع الحماية تقطير الملخصات السابقة مع الرسائل الجديدة
  بدلاً من الحفاظ على الملخص السابق الكامل حرفيًا.
- يفعّل وضع الحماية عمليات تدقيق جودة الملخص افتراضيًا؛ اضبط
  `qualityGuard.enabled: false` لتخطي سلوك إعادة المحاولة عند وجود خرج سيئ التنسيق.
- إذا فشل المزوّد أو أعاد نتيجة فارغة، يعود OpenClaw تلقائيًا إلى تلخيص LLM المدمج.
- تُعاد رمي إشارات الإلغاء/انتهاء المهلة (ولا تُبتلع) لاحترام إلغاء المستدعي.

المصدر: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`.

---

## الأسطح المرئية للمستخدم

يمكنك مراقبة Compaction وحالة الجلسة عبر:

- `/status` (في أي جلسة دردشة)
- `openclaw status` (CLI)
- `openclaw sessions` / `sessions --json`
- سجلات Gateway (`pnpm gateway:watch` أو `openclaw logs --follow`): `embedded run auto-compaction start` + `complete`
- الوضع المفصل: `🧹 Auto-compaction complete` + عدد مرات Compaction

---

## الصيانة الصامتة (`NO_REPLY`)

يدعم OpenClaw دورات "صامتة" للمهام الخلفية حيث يجب ألا يرى المستخدم خرجًا وسيطًا.

العرف:

- يبدأ المساعد خرجه بالرمز الصامت الدقيق `NO_REPLY` /
  `no_reply` للإشارة إلى "لا تسلم ردًا إلى المستخدم".
- يزيل OpenClaw هذا/يكبته في طبقة التسليم.
- كبت الرمز الصامت الدقيق غير حساس لحالة الأحرف، لذا يُحتسب `NO_REPLY` و
  `no_reply` كلاهما عندما تكون الحمولة بأكملها هي الرمز الصامت فقط.
- هذا مخصص فقط للدورات الخلفية/بلا تسليم الحقيقية؛ وليس اختصارًا
  لطلبات المستخدم العادية القابلة للتنفيذ.

اعتبارًا من `2026.1.10`، يكبت OpenClaw أيضًا **بث المسودة/الكتابة** عندما تبدأ
قطعة جزئية بـ `NO_REPLY`، حتى لا تسرب العمليات الصامتة خرجًا جزئيًا
في منتصف الدورة.

---

## "تفريغ الذاكرة" قبل Compaction (منفذ)

الهدف: قبل حدوث Compaction التلقائي، تشغيل دورة وكيلية صامتة تكتب حالة دائمة
إلى القرص (مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) حتى لا يتمكن Compaction من
محو سياق حرج.

يستخدم OpenClaw نهج **التفريغ قبل العتبة**:

1. راقب استخدام سياق الجلسة.
2. عندما يتجاوز "عتبة لينة" (أدنى من عتبة Compaction الخاصة بـ Pi)، شغّل توجيهًا صامتًا
   "اكتب الذاكرة الآن" إلى الوكيل.
3. استخدم الرمز الصامت الدقيق `NO_REPLY` / `no_reply` حتى لا يرى المستخدم
   شيئًا.

الإعداد (`agents.defaults.compaction.memoryFlush`):

- `enabled` (الافتراضي: `true`)
- `model` (تجاوز اختياري دقيق للمزوّد/النموذج لدورة التفريغ، مثل `ollama/qwen3:8b`)
- `softThresholdTokens` (الافتراضي: `4000`)
- `prompt` (رسالة المستخدم لدورة التفريغ)
- `systemPrompt` (مطالبة نظام إضافية تُلحق لدورة التفريغ)

ملاحظات:

- تتضمن المطالبة/مطالبة النظام الافتراضية تلميح `NO_REPLY` لكبت
  التسليم.
- عند ضبط `model`، تستخدم دورة التفريغ ذلك النموذج دون وراثة
  سلسلة الرجوع الاحتياطي للجلسة النشطة، حتى لا تعود الصيانة المحلية فقط بصمت
  إلى نموذج محادثة مدفوع.
- يعمل التفريغ مرة واحدة لكل دورة Compaction (يُتتبع في `sessions.json`).
- يعمل التفريغ فقط لجلسات Pi المضمنة (تتخطاه خلفيات CLI).
- يتم تخطي التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`).
- راجع [الذاكرة](/ar/concepts/memory) لتخطيط ملفات مساحة العمل وأنماط الكتابة.

يعرض Pi أيضًا خطاف `session_before_compact` في API الامتداد، لكن منطق التفريغ الخاص بـ OpenClaw
يعيش حاليًا على جانب Gateway.

---

## قائمة تحقق استكشاف الأخطاء وإصلاحها

- مفتاح الجلسة خاطئ؟ ابدأ بـ [/concepts/session](/ar/concepts/session) وأكد `sessionKey` في `/status`.
- عدم تطابق المخزن مع النص؟ أكد مضيف Gateway ومسار المخزن من `openclaw status`.
- تكرار Compaction المفرط؟ تحقق من:
  - نافذة سياق النموذج (صغيرة جدًا)
  - إعدادات Compaction (`reserveTokens` مرتفعة جدًا بالنسبة لنافذة النموذج وقد تسبب Compaction أبكر)
  - تضخم نتائج الأدوات: فعّل/اضبط تقليم الجلسة
- هل تتسرب الدورات الصامتة؟ أكد أن الرد يبدأ بـ `NO_REPLY` (رمز دقيق غير حساس لحالة الأحرف) وأنك على بناء يتضمن إصلاح كبت البث.

## ذات صلة

- [إدارة الجلسات](/ar/concepts/session)
- [تقليم الجلسة](/ar/concepts/session-pruning)
- [محرك السياق](/ar/concepts/context-engine)