الغوص المتعمق في إدارة الجلسات

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

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

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

• إدارة الجلسات
• Compaction
• نظرة عامة على الذاكرة
• بحث الذاكرة
• تقليم الجلسات
• نظافة النصوص النصية

مصدر الحقيقة: 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 عن عمليات الإخراج المحتملة لكنه لا يغير المخزن/الملفات.

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

openclaw sessions cleanup --dry-runopenclaw 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.

معرّفات الجلسات (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: طابع وقت آخر تغيير لصف المخزن، يُستخدم للإدراج والتقليم ومسك الدفاتر. ليس هو السلطة لحداثة إعادة الضبط اليومية/الخاملة.
• 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: رسائل user/assistant/toolResult
• custom_message: رسائل يحقنها الامتداد وتدخل فعلا في سياق النموذج (يمكن إخفاؤها عن واجهة المستخدم)
• custom: حالة الامتداد التي لا تدخل في سياق النموذج
• compaction: ملخص Compaction مستمر مع firstKeptEntryId و tokensBefore
• branch_summary: ملخص مستمر عند التنقل في فرع شجري

يتعمد OpenClaw عدم "تصحيح" النصوص؛ إذ يستخدم Gateway ‏SessionManager لقراءتها وكتابتها.

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

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

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

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

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

للمزيد، راجع /token-use.

Compaction: ما هو

يلخص Compaction المحادثة الأقدم في إدخال compaction مستمر في النص ويحافظ على الرسائل الحديثة كما هي.

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

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

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

Compaction مستمر (بخلاف تشذيب الجلسة). راجع /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، ومتغيرات مشابهة بصيغة المزوّد) ← ضغط ← إعادة محاولة. عندما يبلّغ المزوّد عن عدد الرموز التي جرت محاولتها، يمرر 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 في إعدادات الوكيل:

{  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").
• راجع Memory لتخطيط ملفات مساحة العمل وأنماط الكتابة.

يكشف OpenClaw أيضا خطاف session_before_compact في واجهة API الخاصة بالامتداد، لكن منطق التفريغ في OpenClaw يعيش اليوم على جانب Gateway.

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

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

ذو صلة

• إدارة الجلسة
• تشذيب الجلسة
• محرك السياق