استرداد إعادة التشغيل

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

​

ما يبقى بعد إعادة التشغيل

​

عمليات إعادة التشغيل الآمنة تنتظر أولًا اكتمال العمل

إعادة التشغيل المطلوبة (openclaw gateway restart، أو تغيير إعداد يتطلب إعادة التشغيل، أو تحديث Gateway) لا توقف العمل الجاري فورًا. يتوقف Gateway عن قبول عمل جديد، ثم ينتظر اكتمال أدوار الوكلاء النشطة ومهام الخلفية، حتى حد زمني للتصريف (5 دقائق افتراضيًا). لذلك لا تقاطع معظم عمليات إعادة التشغيل أي عمل إطلاقًا. لا يُجهض إلا العمل الذي يتعذر إكماله ضمن الحد الزمني للتصريف (أو أي عملية قاطعتها إعادة تشغيل قسرية أو انهيار) — وقبل حدوث ذلك، تُعلَّم كل جلسة متأثرة للاسترداد.

​

كيفية اكتشاف العمل المنقطع

تحدد ثلاث آليات متكاملة الجلسات التي لم يكتمل دورها:

• عند قبول الدور: بالنسبة إلى دور نصي عادي في جلسة رئيسية موجودة، يضيف Gateway رسالة المستخدم، ويضع علامة التشغيل على الجلسة، ويسجل مطالبة تسليم الاسترداد الخاصة بها في معاملة SQLite واحدة قبل تنفيذ النموذج أو خطاف before_agent_reply. تفعل Control UI ذلك قبل إرجاع إقرار started؛ بينما ينفذه توجيه القناة عندما يتبنى الدور المُحضَّر عملية الوكيل. تحتفظ الأوامر والمرفقات والتجاوزات الخاصة بكل دور وعمليات التسليم المعلقة وتلميحات الإجهاض السابقة والجلسات المملوكة لـ Plugin والأدوار ذات خطافات التنفيذ بمسارات القبول المتخصصة الخاصة بها. إذا كان خطاف before_agent_reply مثبّتًا، يسجل القبول مرحلته أيضًا. لا يعيد الاسترداد مطلقًا تشغيل خطاف انقطع في منتصف الاستدعاء. بمجرد انتهاء خطاف غير معالَج، تسجل نقطة التحقق نتيجته، لكن الاسترداد يظل مغلقًا عند الفشل ما دام ذلك الخطاف نشطًا: إذ لا يمكن لنقطة التحقق إثبات أن شيفرة Plugin نفسها وإعداداته قد حُمّلت بعد إعادة التشغيل. تُسجَّل النتائج النصية المعالَجة والصامتة في نقاط تحقق منفصلة لضمان تسوية حتمية. لا تتضمن مطالبات الاسترداد الدائمة التي كتبتها الإصدارات الأقدم علامة ملكية المصدر، ولذلك تخضع لفحص الخطاف المغلق عند الفشل نفسه أثناء الترقية.
• عند إيقاف التشغيل: أثناء تصريف إعادة التشغيل، تُوسم كل جلسة ذات عملية نشطة بعلامة استرداد في مخزن الجلسات قبل إجهاض العملية.
• عند بدء التشغيل: يفحص Gateway مخازن الجلسات بحثًا عن الجلسات التي لا تزال تدّعي أنها قيد التشغيل لكن ليس لها مالك نشط في العملية الجديدة. يلتقط ذلك الانهيارات وعمليات الإنهاء القسرية التي لم تُنفّذ فيها أي شيفرة إيقاف تشغيل. كما تُنظَّف ملفات قفل النصوص المفرغة القديمة في الوقت نفسه.

​

الاستئناف التلقائي

بعد بضع ثوانٍ من بدء التشغيل، يعيد Gateway توجيه كل جلسة معلَّمة برسالة نظام اصطناعية تخبر الوكيل بأن دوره السابق قد انقطع بسبب إعادة التشغيل وأن عليه المتابعة من النص المفرغ الموجود. إذا كان رد نهائي قد أُنتج بالفعل لكنه لم يُسلَّم، يُضمَّن نصه حتى يتمكن الوكيل من تسليمه بدلًا من إعادة العمل. يعيد الاسترداد المحاولة حتى 3 مرات مع تراجع أُسّي. تعيد كل محاولة استخدام معرّف توجيه دائم واحد، ولذلك لا يمكن لفشل اتصال ملتبس أن يبدأ الاسترداد نفسه مرتين. تحتفظ أيضًا أدوار Control UI المكتملة وغير القابلة للاستئناف بشواهد حذف دائمة ومحدودة لضمان عدم تكرار التنفيذ، مما يسمح لصندوق صادر يعيد الاتصال بإزالتها دون إعادة تنفيذ الطلب. تستخدم الردود التي تقتصر على أداة الرسائل ارتباطًا دائمًا ثانيًا. قبل أن يصل إرسال نهائي ضمن المحادثة نفسها إلى القناة، يسجل Gateway نية تسليم غير محلولة في الجلسة ودور المصدر المحددين بدقة. يحل نجاح موفّر مؤكد هذه النية إلى إيصال تسليم دائم؛ بينما يمحوها الفشل المؤكد. يكمل الاسترداد إيصالًا مُسلَّمًا دون إعادة تشغيل الأدوات. إذا ترك انهيار نتيجة الموفّر مجهولة، يُغلق الاسترداد عند الفشل بدلًا من إعادة تشغيل تأثير خارجي. يُنسخ الرد المُسلَّم أيضًا إلى النص المفرغ مع معرّف رسالة المصدر الخاص به. تستخدم النسخ النهائية مفتاح إيصال مميزًا، ولذلك لا يمكن لإرسال تقدم يحمل مفتاح منع التكرار نفسه لدى الموفّر أن يحجب العلامة النهائية. لا يمكن لإرسالات التقدم وإيصالات الأدوار الأقدم إكمال الدور الحالي. لا يمكن استعادة صلاحية إجراءات الرسائل إلا من خلال مطالبات دخول القناة الدائمة. تحتفظ العملية المستأنفة بوضع تسليم المصدر وارتباط المصدر الأصليين، بما في ذلك هوية مقدم الطلب وأي قيد خاص بالقناة نفسها أو سلسلة الرسائل نفسها، ولذلك يظل الإيصال نفسه مرجعًا موثوقًا حتى إذا حدثت إعادة تشغيل أخرى أثناء الاسترداد. يُغلق الدور الذي يقتصر على أداة الرسائل ولا يملك صلاحية قناة قابلة لإعادة البناء عند الفشل، ويتلقى إشعار إعادة الإرسال لمرة واحدة. قبل الاستئناف، يتحقق Gateway من أن نهاية النص المفرغ آمنة للمتابعة منها. إذا لم تكن كذلك (على سبيل المثال، إذا انتهى الدور عند موافقة معلقة قديمة)، فلا تُعاد العملية في الجلسة دون تحقق؛ بل ينشر الوكيل إشعارًا قصيرًا يطلب من المستخدم إعادة إرسال الطلب الأخير. بالنسبة إلى WebChat، يُكتب ذلك الإشعار مباشرةً في سجل الجلسة ليظل مرئيًا بعد إعادة الاتصال. يستطيع OpenClaw أيضًا إعادة بناء عمل وضع الشيفرة المنقطع والمخصص للقراءة فقط. يضع وضع الشيفرة علامة أمان إعادة التشغيل على هذه العمليات ويرفض أدوات الكتالوج ذات الآثار الجانبية أو مساحات أسماء Plugin قبل تنفيذها. إذا وقعت إعادة التشغيل عند عنصر التحكم wait، يعيد Gateway الجديد بناء الدور من نصه المفرغ ويفرض بقاء التنفيذ المعاد بناؤه آمنًا لإعادة التشغيل حتى إذا أغفل النموذج تلك العلامة أو مسحها. يرشّح المضيف الدور المعاد بناؤه بأكمله ليقتصر على أدوات النواة المدققة المخصصة للقراءة فقط وأدوات Plugin الآمنة صراحةً لإعادة التشغيل، بما في ذلك عندما يكون وضع الشيفرة معطلًا بعد إعادة التشغيل. يظل العمل ذو الآثار الجانبية محميًا بإشعار إعادة الإرسال بدلًا من المخاطرة بكتابة مكررة.

​

الوكلاء الفرعيون

تُحفظ عمليات الوكلاء الفرعيين في قاعدة بيانات حالة SQLite المشتركة، ولذلك يبقى سجل الوكلاء الفرعيين بعد انتهاء العملية. عند الإقلاع، يُستعاد السجل وتُستأنف جلسات الوكلاء الفرعيين المنقطعة مع سياق مهمتها الأصلي. يُطبَّق صمامَا أمان:

• تُنهى العمليات التي انقطعت قبل أكثر من ساعتين بدلًا من استئنافها، حتى لا يعيد Gateway الذي ظل متوقفًا طوال الليل إحياء عمل قديم.
• تُوسم الجلسة التي تفشل في الاسترداد مرارًا بشاهد حذف باعتبارها عالقة، حتى لا يدخل الاسترداد في حلقة لا نهائية.

​

مهام الخلفية

يعتمد سجل مهام الخلفية على SQLite، وتُجرى تسويته عند الإقلاع وعلى فترات دورية: تُسترد النتائج الدائمة التي سجلتها العمليات المكتملة، وتُعلَّم العمليات التي اختفت العملية المالكة لها كمفقودة بعد فترة سماح بدلًا من بقائها عالقة إلى الأبد.

​

عمليات إعادة التشغيل التي يطلبها الوكيل

عندما يشغّل الوكيل نفسه إعادة تشغيل (بتطبيق تغيير إعداد، أو تحديث Gateway، أو طلب إعادة تشغيل صريح)، يُكتب حارس إعادة التشغيل في SQLite قبل خروج العملية. بعد الإقلاع، ينشر Gateway النتيجة مرة أخرى في المحادثة الأصلية ويوجه دور متابعة لمرة واحدة حتى يتابع الوكيل من الموضع نفسه تمامًا الذي توقف عنده، وعلى القناة وسلسلة الرسائل نفسيهما.

​

صمامات الأمان وقابلية الرصد

• قاطع حلقة الانهيار: تؤدي 3 عمليات إقلاع غير سليمة خلال 5 دقائق إلى تفعيل قاطع يمنع بدء الخدمات الجانبية تلقائيًا عند الإقلاع التالي، حتى لا يؤدي انهيار Gateway إلى تضخيم أثره. ويعود إلى حالته الطبيعية بمجرد انقضاء نافذة الإقلاع غير السليم.
• المقاييس: يُصدَّر نشاط الاسترداد عبر Prometheus باسمَي openclaw_session_recovery_total و openclaw_session_recovery_age_seconds.
• السجلات: تُسجَّل قرارات الاسترداد ضمن النظامين الفرعيين main-session-restart-recovery وsubagent-interrupted-resume.

​

ما لا يُستأنف

• الجلسات المستبعدة من استرداد الجلسة الرئيسية لأن مالكًا آخر يتولى التعامل معها بالفعل: جلسات الوكلاء الفرعيين (استرداد الوكلاء الفرعيين)، وجلسات Cron (يعيد المجدول تشغيلها حسب الجدول)، والجلسات التي يديرها ACP (يتولى IDE أو العميل المتصل عملية الاستئناف).
• الجلسات التي لا يمكن متابعة نهاية نصها المفرغ بأمان؛ تتلقى هذه الجلسات إشعار إعادة الإرسال الموضح أعلاه بدلًا من إعادة تشغيل صامتة.
• العمل الذي لم يُقبَل أصلًا: تُرفض الرسائل الواردة أثناء نافذة التصريف مع خطأ صريح لإعادة التشغيل بدلًا من وضعها بصمت في قائمة انتظار عملية على وشك الانتهاء.