---
read_when:
    - عندما يبلّغ مستخدم عن تعثر الوكلاء في تكرار استدعاءات الأدوات
    - عندما تحتاج إلى ضبط الحماية من الاستدعاءات المتكررة
    - عندما تكون بصدد تحرير سياسات الأدوات/‏runtime الخاصة بالوكيل
summary: كيفية تمكين وضبط وسائل الحماية التي تكتشف حلقات استدعاء الأدوات المتكررة
title: اكتشاف حلقات الأدوات
x-i18n:
    generated_at: "2026-04-05T12:59:08Z"
    model: gpt-5.4
    provider: openai
    source_hash: dc3c92579b24cfbedd02a286b735d99a259b720f6d9719a9b93902c9fc66137d
    source_path: tools/loop-detection.md
    workflow: 15
---

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

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

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

## لماذا يوجد هذا

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

## كتلة التكوين

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

```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`: يكتشف الأنماط المعروفة الشبيهة بـ polling عند عدم تغير الحالة.
- `detectors.pingPong`: يكتشف أنماط التناوب ping-pong.

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

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

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

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

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

## ملاحظات

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