---
read_when:
    - يبلّغ أحد المستخدمين عن تعلّق الوكلاء أثناء تكرار استدعاءات الأدوات
    - تحتاج إلى ضبط حماية الاستدعاءات المتكررة
    - أنت تعدّل سياسات أدوات/بيئة تشغيل الوكيل
summary: كيفية تمكين حواجز الحماية وضبطها لاكتشاف حلقات استدعاء الأدوات المتكررة
title: اكتشاف حلقات الأدوات
x-i18n:
    generated_at: "2026-04-30T08:31:27Z"
    model: gpt-5.5
    provider: openai
    source_hash: ba601384e7d23ddfd316f9e5eef92b3daa4618d2287228a516c76fe141700a28
    source_path: tools/loop-detection.md
    workflow: 16
---

يمكن لـ OpenClaw منع الوكلاء من التعثر في أنماط متكررة لاستدعاءات الأدوات.
تكون آلية الحماية **معطلة افتراضياً**.

فعّلها فقط عند الحاجة، لأنها قد تحظر الاستدعاءات المتكررة المشروعة عند استخدام إعدادات صارمة.

## سبب وجود هذا

- اكتشاف التسلسلات المتكررة التي لا تحقق تقدماً.
- اكتشاف حلقات عدم وجود نتائج عالية التكرار (الأداة نفسها، المدخلات نفسها، أخطاء متكررة).
- اكتشاف أنماط محددة للاستدعاءات المتكررة لأدوات الاستطلاع المعروفة.

## كتلة الإعدادات

الإعدادات الافتراضية العامة:

```json5
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
```

تجاوز لكل وكيل (اختياري):

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

### سلوك الحقول

- `enabled`: المفتاح الرئيسي. تعني `false` عدم تنفيذ أي اكتشاف للحلقات.
- `historySize`: عدد استدعاءات الأدوات الحديثة المحتفظ بها للتحليل.
- `warningThreshold`: الحد الذي يسبق تصنيف النمط كتحذير فقط.
- `criticalThreshold`: الحد اللازم لحظر أنماط الحلقات المتكررة.
- `globalCircuitBreakerThreshold`: حد قاطع عدم التقدم العام.
- `detectors.genericRepeat`: يكتشف أنماط تكرار الأداة نفسها + المعاملات نفسها.
- `detectors.knownPollNoProgress`: يكتشف الأنماط المعروفة الشبيهة بالاستطلاع دون تغير في الحالة.
- `detectors.pingPong`: يكتشف أنماط التناوب ذهاباً وإياباً.

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

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

- ابدأ باستخدام `enabled: true`، مع إبقاء الإعدادات الافتراضية دون تغيير.
- حافظ على ترتيب الحدود بالشكل `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- إذا حدثت نتائج إيجابية كاذبة:
  - ارفع `warningThreshold` و/أو `criticalThreshold`
  - ارفع `globalCircuitBreakerThreshold` (اختيارياً)
  - عطّل فقط الكاشف الذي يسبب المشكلات
  - قلّل `historySize` للحصول على سياق تاريخي أقل صرامة

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

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

- فضّل التحذير والكبح المؤقت أولاً.
- لا تصعّد إلا عند تراكم أدلة متكررة.

## ملاحظات

- يتم دمج `tools.loopDetection` مع تجاوزات مستوى الوكيل.
- إعدادات كل وكيل تتجاوز القيم العامة أو توسعها بالكامل.
- إذا لم توجد إعدادات، تبقى آليات الحماية معطلة.

## ذو صلة

- [موافقات التنفيذ](/ar/tools/exec-approvals)
- [مستويات التفكير](/ar/tools/thinking)
- [الوكلاء الفرعيون](/ar/tools/subagents)
