---
read_when:
    - تحتاج إلى تصحيح معرّفات الجلسات أو JSONL للنصوص المنسوخة أو حقول sessions.json
    - أنت تغيّر سلوك الضغط التلقائي أو تضيف مهام صيانة "ما قبل الضغط"
    - تريد تنفيذ تفريغات الذاكرة أو دورات نظام صامتة
summary: 'نظرة معمقة: مخزن الجلسات والنصوص، ودورة الحياة، وآليات Compaction التلقائية والداخلية'
title: نظرة متعمقة على إدارة الجلسات
x-i18n:
    generated_at: "2026-07-04T20:34:16Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: c97994f674e14ec01b2eaadc10a61e524f5071f95b2ef84957d71abacbdc719b
    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، وواجهة Control UI للويب، وTUI) الاستعلام من Gateway عن قوائم الجلسات وأعداد الرموز.
- في الوضع البعيد، تكون ملفات الجلسة على المضيف البعيد؛ "فحص ملفات Mac المحلية لديك" لن يعكس ما يستخدمه Gateway.

---

## طبقتا الاستمرار

يحفظ OpenClaw الجلسات في طبقتين:

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

2. **النص التفريغي (`<sessionId>.jsonl`)**
   - نص تفريغي إلحاقي فقط ببنية شجرية (تحتوي الإدخالات على `id` + `parentId`)
   - يخزن المحادثة الفعلية + استدعاءات الأدوات + ملخصات Compaction
   - يُستخدم لإعادة بناء سياق النموذج للجولات المستقبلية
   - نقاط تحقق 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`:‏ `enforce` (الافتراضي) أو `warn`
- `pruneAfter`: حد عمر الإدخالات القديمة (الافتراضي `30d`)
- `maxEntries`: حد الإدخالات في `sessions.json` (الافتراضي `500`)
- احتفاظ مجسات تشغيل نموذج Gateway قصيرة الأجل ثابت عند `24h`، لكنه مقيّد بالضغط: يزيل صفوف المجسات الصارمة القديمة فقط عند بلوغ ضغط صيانة/حد إدخالات الجلسة. ينطبق هذا فقط على مفاتيح المجسات الصريحة الصارمة المطابقة لـ `agent:*:explicit:model-run-<uuid>` ويعمل قبل التنظيف/الحد العام للإدخالات القديمة عندما يعمل.
- `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، والوكلاء الفرعيين عندما تتجاوز العمر أو العدد أو ميزانية القرص المضبوطة. تستخدم جلسات مجسات تشغيل النموذج في Gateway احتفاظ تشغيل النموذج المنفصل `24h` فقط عندما يطابق مفتاحها تماماً `agent:*:explicit:model-run-<uuid>`؛ الجلسات الصريحة الأخرى ليست جزءاً من هذا الاحتفاظ. لا يطبق تنظيف تشغيل النموذج إلا تحت ضغط حد إدخالات الجلسات. تحتفظ عمليات cron المعزولة بضابط `cron.sessionRetention` الخاص بها، مستقلاً عن احتفاظ مجسات تشغيل النموذج.

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

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

ترتيب فرض تنظيف ميزانية القرص (`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.keepLines` يشذب صفوف سجل التشغيل المحتفظ بها في SQLite لكل مهمة cron (الافتراضي: `2000`). يظل `cron.runLog.maxBytes` مقبولاً لسجلات التشغيل الأقدم المدعومة بالملفات.

عندما ينشئ 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` جديداً عند وصول رسالة بعد نافذة الخمول. عندما يكون كل من اليومي + الخمول مضبوطين، يفوز ما تنتهي صلاحيته أولاً.
- **استئناف إعادة اتصال Control UI** يمكنه الحفاظ على الجلسة المرئية حالياً لإرسال واحد بعد إعادة الاتصال عندما يتلقى Gateway قيمة `sessionId` المطابقة من عميل واجهة مستخدم المشغل. لا تزال الإرسالات القديمة العادية تنشئ `sessionId` جديداً.
- **أحداث النظام** (Heartbeat، وإيقاظات cron، وإشعارات exec، ومسك دفاتر Gateway) قد تغيّر صف الجلسة لكنها لا تمدد حداثة إعادة الضبط اليومية/الخمول. يتخلص انتقال إعادة الضبط من إشعارات أحداث النظام المصطفة للجلسة السابقة قبل بناء الموجه الجديد.
- **سياسة تفرع الأصل** تستخدم الفرع النشط في OpenClaw عند إنشاء خيط أو تفرع وكيل فرعي. إذا كان ذلك الفرع كبيراً جداً، يبدأ 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 وexec الجلسات حيّة. تعود الصفوف القديمة التي لا تحتوي على هذا الحقل إلى وقت بدء الجلسة المسترد لحداثة الخمول.
- `updatedAt`: الطابع الزمني لآخر تغيير في صف المخزن، ويُستخدم للسرد والتقليم ومسك السجلات. ليس هو المرجع لحداثة إعادة التعيين اليومية/عند الخمول.
- `archivedAt`: طابع زمني اختياري للأرشفة. تبقى الجلسات المؤرشفة في المخزن مع بقاء نصها الكامل سليماً وتُستبعد من القوائم النشطة العادية.
- `pinnedAt`: طابع زمني اختياري للتثبيت. تُرتّب الجلسات النشطة المثبّتة قبل الجلسات غير المثبّتة؛ تؤدي أرشفة جلسة إلى مسح تثبيتها.
- توافق خيوط Codex: يتبع كلا الحقلين شكل إدارة الخيوط في Codex — تُشتق قيمتا `archived`/`pinned` المنطقيتان على السلك دائماً من الطابع الزمني وتُختمان من جهة الخادم، بما يطابق دلالات Codex `threads.archived_at` وتسلسل camelCase. طوابع OpenClaw الزمنية هي بالمللي ثانية منذ الحقبة، بينما يستخدم Codex الثواني منذ الحقبة، لذلك تحوّل الجسور عند حد Plugin الخاص بـ codex. لا يملك Codex واجهة API للتثبيت بعد (`thread/archive`/`thread/unarchive` فقط)؛ تبقى حالة التثبيت في جهة OpenClaw إلى أن توجد واحدة، وعندها يتيح الشكل المطابق للجلسات المرتبطة إجراء ذهاب وإياب لحالة التثبيت آلياً.
- `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` في `openclaw/plugin-sdk/agent-sessions`.

الملف بتنسيق 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`

إعادة حقن قسم AGENTS.md بعد Compaction اختيارية عبر
`agents.defaults.compaction.postCompactionSections`؛ عند عدم تعيينها أو كونها `[]`،
لا يضيف OpenClaw مقتطفات AGENTS.md فوق ملخص Compaction.

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

## حدود مقاطع Compaction وإقران الأدوات

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

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

---

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

في وكيل OpenClaw المضمّن، يتم تشغيل 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 → إعادة المحاولة.
   عندما يبلّغ المزوّد عن عدد الرموز الذي جرت محاولته، يمرّر OpenClaw ذلك
   العدد المرصود إلى Compaction استرداد الفائض. إذا أكّد المزوّد وجود
   فائض لكنه لا يكشف عن عدد قابل للتحليل، يمرّر OpenClaw عدداً اصطناعياً
   يتجاوز الميزانية بالحد الأدنى إلى محركات Compaction والتشخيصات.
   إذا ظل استرداد الفائض يفشل، يعرض OpenClaw إرشادات صريحة للمستخدم
   ويحافظ على تعيين الجلسة الحالي بدلاً من تدوير مفتاح الجلسة بصمت إلى
   معرّف جلسة جديد. الخطوة التالية يتحكم بها المشغّل: إعادة محاولة
   الرسالة، أو تشغيل `/compact`، أو تشغيل `/new` عندما تكون جلسة جديدة
   مفضلة.
2. **صيانة العتبة**: بعد دورة ناجحة، عندما:

`contextTokens > contextWindow - reserveTokens`

حيث:

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

هذه هي دلالات تشغيل OpenClaw.

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

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

---

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

توجد إعدادات Compaction لوقت تشغيل OpenClaw في إعدادات الوكيل:

```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`
  الصريحة ويحافظ على نقطة قص الذيل الحديث في وقت تشغيل OpenClaw. من دون
  ميزانية احتفاظ صريحة، يظل 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 حتمياً.

التنفيذ: `applyAgentCompactionSettingsFromConfig()` في `src/agents/agent-settings.ts`
(يُستدعى من مسارات إعداد دورة المشغّل المضمّن وCompaction).

---

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

يمكن لـ Plugins تسجيل مزوّد Compaction عبر `registerCompactionProvider()` في واجهة Plugin API. عند ضبط `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/agent-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 في وقت تشغيل OpenClaw)، شغّل توجيهًا صامتًا
   "اكتب الذاكرة الآن" إلى الوكيل.
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`).
- يعمل التفريغ فقط لجلسات OpenClaw المضمّنة (تتخطاه خلفيات CLI).
- يتم تخطي التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`).
- راجع [الذاكرة](/ar/concepts/memory) لمعرفة تخطيط ملفات مساحة العمل وأنماط الكتابة.

يعرض OpenClaw أيضًا خطاف `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)