docs/docs/fa/tools/loop-detection.md

read_when	summary	title	x-i18n
کاربری گزارش می‌دهد که عامل‌ها در تکرار فراخوانی‌های ابزار گیر می‌کنند باید محافظت در برابر فراخوانی‌های تکراری را تنظیم کنید شما در حال ویرایش سیاست‌های ابزار/زمان اجرای عامل هستید	نحوهٔ فعال‌سازی و تنظیم سازوکارهای محافظتی که حلقه‌های تکراری فراخوانی ابزار را تشخیص می‌دهند	تشخیص حلقهٔ ابزار	generated_at model provider source_hash source_path workflow 2026-05-05T01:52:30Z gpt-5.5 openai b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb tools/loop-detection.md 16

OpenClaw می‌تواند از گیرکردن عامل‌ها در الگوهای تکراری فراخوانی ابزار جلوگیری کند. این محافظ به‌صورت پیش‌فرض غیرفعال است.

آن را فقط در جاهایی که لازم است فعال کنید، چون با تنظیمات سخت‌گیرانه می‌تواند فراخوانی‌های تکراری مشروع را مسدود کند.

چرا این وجود دارد

• شناسایی دنباله‌های تکراری که پیشرفتی ایجاد نمی‌کنند.
• شناسایی حلقه‌های پربسامد بدون نتیجه (همان ابزار، همان ورودی‌ها، خطاهای تکراری).
• شناسایی الگوهای مشخص فراخوانی تکراری برای ابزارهای نظرسنجی شناخته‌شده.

بلوک پیکربندی

پیش‌فرض‌های سراسری:

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

بازنویسی برای هر عامل (اختیاری):

{
  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 را کاهش دهید

محافظ پس از Compaction

وقتی اجراکننده یک تلاش مجدد Compaction خودکار را کامل می‌کند (پس از سرریز زمینه)، یک محافظ با پنجره کوتاه فعال می‌کند که چند فراخوانی ابزار بعدی را زیر نظر می‌گیرد. اگر عامل سه‌تایی یکسان (toolName, args, result) را چند بار در همان پنجره منتشر کند، محافظ نتیجه می‌گیرد که Compaction حلقه را نشکسته است و اجرا را با خطای compaction_loop_persisted متوقف می‌کند.

این مسیر کد از آشکارسازهای سراسری tools.loopDetection جداست. پیکربندی آن مستقل است:

{
  tools: {
    loopDetection: {
      enabled: true, // existing master switch; set false to disable loop guards
      postCompactionGuard: {
        windowSize: 3, // default: 3
      },
    },
  },
}

• windowSize: تعداد فراخوانی‌های ابزار پس از Compaction که در طول آن محافظ مسلح می‌ماند و شمار سه‌تایی‌های یکسان (ابزار، آرگومان‌ها، نتیجه) که باعث توقف می‌شود.

محافظ هرگز وقتی نتایج در حال تغییر هستند اجرا را متوقف نمی‌کند، فقط وقتی نتایج در سراسر پنجره از نظر بایتی یکسان باشند. این عمدا محدود است: فقط بلافاصله پس از یک تلاش مجدد Compaction فعال می‌شود.

گزارش‌ها و رفتار مورد انتظار

وقتی حلقه‌ای شناسایی می‌شود، OpenClaw یک رویداد حلقه گزارش می‌کند و بسته به شدت، چرخه ابزار بعدی را مسدود یا تضعیف می‌کند. این کار ضمن حفظ دسترسی عادی به ابزارها، کاربران را از مصرف بی‌مهار توکن و قفل‌شدن محافظت می‌کند.

• ابتدا هشدار و سرکوب موقت را ترجیح دهید.
• فقط وقتی شواهد تکراری انباشته شد تشدید کنید.

نکات

• tools.loopDetection با بازنویسی‌های سطح عامل ادغام می‌شود.
• پیکربندی هر عامل، مقادیر سراسری را کاملا بازنویسی یا گسترش می‌دهد.
• اگر هیچ پیکربندی‌ای وجود نداشته باشد، محافظ‌ها خاموش می‌مانند.

مرتبط

• تأییدهای Exec
• سطوح تفکر
• عامل‌های فرعی