نظرة متعمقة على إدارة الجلسات

يدير 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: الطابع الزمني لآخر تغيير في صف المخزن، ويُستخدم للسرد والتقليم ومسك السجلات. ليس هو المرجع لحداثة إعادة التعيين اليومية/عند الخمول.
• 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.

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، ومتغيرات مشابهة بصياغة المزوّد) → 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 في إعدادات الوكيل:

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

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

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

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

ذات صلة

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