اكتشاف حلقة الأدوات

لدى OpenClaw آليتا حماية متعاونتان ضد أنماط استدعاء الأدوات المتكررة، وتُضبط كلتاهما ضمن tools.loopDetection:

1. اكتشاف الحلقات (enabled) - معطّل افتراضيًا. يراقب السجل المتحرك لاستدعاءات الأدوات بحثًا عن الأنماط المتكررة وإعادات محاولة الأدوات المجهولة.
2. آلية الحماية بعد Compaction (postCompactionGuard) - مفعّلة كلما لم تكن قيمة enabled هي false صراحةً. تُسلّح بعد كل إعادة محاولة تلي Compaction وتُجهض التشغيل إذا كرر الوكيل الثلاثية نفسها (tool, args, result) ضمن النافذة.

اضبط tools.loopDetection.enabled: false لتعطيل آليتي الحماية كلتيهما.

سبب وجود هذه الميزة

• اكتشاف التسلسلات المتكررة التي لا تحرز أي تقدم.
• اكتشاف حلقات انعدام النتائج عالية التكرار (الأداة نفسها، والمدخلات نفسها، والأخطاء المتكررة).
• اكتشاف أنماط محددة من الاستدعاءات المتكررة لأدوات الاستقصاء المعروفة.
• كسر دورات تجاوز السياق -> Compaction -> الحلقة نفسها بدلًا من السماح باستمرارها إلى أجل غير مسمى.

كتلة الإعداد

الإعدادات الافتراضية العامة، مع عرض كل حقل موثّق:

{  tools: {    loopDetection: {      enabled: false, // المفتاح الرئيسي لكاشفات السجل المتحرك      historySize: 30,      warningThreshold: 10,      criticalThreshold: 20,      unknownToolThreshold: 10,      globalCircuitBreakerThreshold: 30,      detectors: {        genericRepeat: true,        knownPollNoProgress: true,        pingPong: true,      },      postCompactionGuard: {        windowSize: 3, // تُسلّح بعد إعادة المحاولة التالية لـ Compaction؛ تعمل ما لم تكن enabled هي false صراحةً      },    },  },}

تجاوز خاص بكل وكيل (اختياري، في agents.list[].tools.loopDetection):

{  agents: {    list: [      {        id: "safe-runner",        tools: {          loopDetection: {            enabled: true,            warningThreshold: 8,            criticalThreshold: 16,          },        },      },    ],  },}

تُركّب إعدادات كل وكيل فوق الكتلة العامة حقلًا بحقل (بما في ذلك detectors وpostCompactionGuard المتداخلان)، لذا لا يحتاج الوكيل إلا إلى ضبط الحقول التي يريد تغييرها.

سلوك الحقول

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

الإعداد الموصى به

• للنماذج الأصغر، اضبط enabled: true واترك الحدود عند قيمها الافتراضية. نادرًا ما تحتاج النماذج الرائدة إلى اكتشاف السجل المتحرك، ويمكنها إبقاء المفتاح الرئيسي على false مع الاستفادة رغم ذلك من آلية الحماية بعد Compaction.
• حافظ على ترتيب الحدود warningThreshold < criticalThreshold < globalCircuitBreakerThreshold؛ يرفع وقت التشغيل criticalThreshold و globalCircuitBreakerThreshold إذا ضبطتهما عند الحد الذي يجب أن تتجاوزاه أو دونه.
• إذا حدثت نتائج إيجابية كاذبة:
  • ارفع warningThreshold و/أو criticalThreshold.
  • ارفع globalCircuitBreakerThreshold اختياريًا.
  • عطّل فقط الكاشف المحدد المسبب للمشكلات (detectors.<name>: false).
  • قلّل historySize للحصول على نافذة سجل أقصر.
• لتعطيل كل شيء، بما في ذلك آلية الحماية بعد Compaction، اضبط tools.loopDetection.enabled: false صراحةً.

آلية الحماية بعد Compaction

بعد إعادة محاولة Compaction التي تلي تجاوز السياق، يسلّح المشغّل آلية حماية ذات نافذة قصيرة لاستدعاءات الأدوات القليلة التالية. إذا أصدر الوكيل الثلاثية نفسها (toolName, argsHash, resultHash) بعدد مرات يساوي postCompactionGuard.windowSize ضمن تلك النافذة، تستنتج آلية الحماية أن Compaction لم تكسر الحلقة وتُجهض التشغيل بخطأ compaction_loop_persisted.

تخضع آلية الحماية للعلامة الرئيسية tools.loopDetection.enabled مع اختلاف واحد: تظل مفعّلة عندما تكون العلامة غير مضبوطة أو تساوي true، ولا تُعطّل إلا عندما تكون العلامة false صراحةً. هذا مقصود - إذ وُجدت آلية الحماية للخروج من حلقات Compaction التي كانت ستستهلك عددًا غير محدود من الرموز، وبذلك يحصل المستخدم الذي لا يضبط أي إعداد على الحماية أيضًا.

{  tools: {    loopDetection: {      // المفتاح الرئيسي؛ اضبطه على false لتعطيل آلية الحماية مع كاشفات السجل المتحرك      enabled: true,      postCompactionGuard: {        windowSize: 3, // القيمة الافتراضية      },    },  },}

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

السجلات والسلوك المتوقع

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

• تأتي التحذيرات أولًا.
• يبدأ الحظر عندما يستمر النمط متجاوزًا حد التحذير.
• تحظر الحدود الحرجة دورة الأداة التالية وتعرض سببًا واضحًا لاكتشاف الحلقة في سجل التشغيل.
• تصدر آلية الحماية بعد Compaction أخطاء compaction_loop_persisted تسمي الأداة المخالفة وعدد الاستدعاءات المتطابقة.

ذو صلة