تشخیص حلقهٔ ابزار

OpenClaw دو گاردریل همکاری‌کننده برای الگوهای تکراری فراخوانی ابزار دارد:

1. تشخیص حلقه (tools.loopDetection.enabled) — به‌طور پیش‌فرض غیرفعال است. تاریخچهٔ چرخشی فراخوانی‌های ابزار را برای الگوهای تکراری و تلاش‌های دوباره برای ابزارهای ناشناخته زیر نظر می‌گیرد.
2. محافظ پس از Compaction (tools.loopDetection.postCompactionGuard) — به‌طور پیش‌فرض فعال است، مگر اینکه tools.loopDetection.enabled صراحتاً false باشد. پس از هر تلاش دوبارهٔ Compaction فعال می‌شود و وقتی عامل همان سه‌تایی (tool, args, result) را در پنجره منتشر کند، اجرا را متوقف می‌کند.

هر دو زیر همان بلوک tools.loopDetection پیکربندی می‌شوند، اما محافظ پس از Compaction هر زمان که کلید اصلی صراحتاً خاموش نباشد اجرا می‌شود. برای خاموش‌کردن هر دو سطح، tools.loopDetection.enabled: false را تنظیم کنید.

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

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

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

پیش‌فرض‌های سراسری، با همهٔ فیلدهای مستندشده:

{
  tools: {
    loopDetection: {
      enabled: false, // master switch for the rolling-history detectors
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
      },
    },
  },
}

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

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

# رفتار فیلدها

فیلد	پیش‌فرض	اثر
enabled	false	کلید اصلی برای آشکارسازهای تاریخچهٔ چرخشی. تنظیم false همچنین محافظ پس از Compaction را غیرفعال می‌کند.
historySize	30	تعداد فراخوانی‌های اخیر ابزار که برای تحلیل نگه داشته می‌شوند.
warningThreshold	10	آستانه‌ای که پیش از آن یک الگو فقط به‌عنوان هشدار طبقه‌بندی می‌شود.
criticalThreshold	20	آستانهٔ مسدودکردن الگوهای حلقهٔ تکراری.
unknownToolThreshold	10	پس از این تعداد عدم‌موفقیت، فراخوانی‌های تکراری به همان ابزارِ در دسترس نبودنی را مسدود می‌کند.
globalCircuitBreakerThreshold	30	آستانهٔ قطع‌کنندهٔ سراسریِ نبود پیشرفت در همهٔ آشکارسازها.
detectors.genericRepeat	true	الگوهای تکراریِ همان ابزار + همان پارامترها را شناسایی می‌کند.
detectors.knownPollNoProgress	true	الگوهای شناخته‌شدهٔ شبیه نظرسنجی را بدون تغییر وضعیت شناسایی می‌کند.
detectors.pingPong	true	الگوهای متناوب رفت‌وبرگشتی را شناسایی می‌کند.
postCompactionGuard.windowSize	3	تعداد فراخوانی‌های ابزار پس از Compaction که طی آن محافظ مسلح می‌ماند و تعداد سه‌تایی‌های یکسانی که اجرا را متوقف می‌کند.

برای exec، بررسی‌های نبود پیشرفت، نتایج پایدار فرمان را مقایسه می‌کنند و فرادادهٔ ناپایدار زمان اجرا مانند مدت، PID، شناسهٔ نشست، و دایرکتوری کاری را نادیده می‌گیرند. وقتی شناسهٔ اجرا موجود باشد، تاریخچهٔ اخیر فراخوانی ابزار فقط در همان اجرا ارزیابی می‌شود تا چرخه‌های Heartbeat زمان‌بندی‌شده و اجراهای تازه، شمارش‌های کهنهٔ حلقه را از اجراهای قبلی به ارث نبرند.

# راه‌اندازی پیشنهادی

• برای مدل‌های کوچک‌تر، enabled: true را تنظیم کنید و آستانه‌ها را روی پیش‌فرض‌هایشان بگذارید. مدل‌های پرچم‌دار به‌ندرت به تشخیص تاریخچهٔ چرخشی نیاز دارند و می‌توانند کلید اصلی را روی false بگذارند، درحالی‌که همچنان از محافظ پس از Compaction بهره می‌برند.
• آستانه‌ها را به ترتیب warningThreshold < criticalThreshold < globalCircuitBreakerThreshold نگه دارید.
• اگر مثبت‌های کاذب رخ داد:
  • warningThreshold و/یا criticalThreshold را افزایش دهید.
  • در صورت نیاز globalCircuitBreakerThreshold را افزایش دهید.
  • فقط همان آشکارساز مشخصی را که مشکل ایجاد می‌کند غیرفعال کنید (detectors.<name>: false).
  • برای زمینهٔ تاریخی کمتر سخت‌گیرانه، historySize را کاهش دهید.
• برای غیرفعال‌کردن همه‌چیز (از جمله محافظ پس از Compaction)، صراحتاً tools.loopDetection.enabled: false را تنظیم کنید.

# محافظ پس از Compaction

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

محافظ با پرچم اصلی tools.loopDetection.enabled کنترل می‌شود، با یک تفاوت: وقتی پرچم تنظیم نشده یا true باشد فعال می‌ماند و فقط زمانی غیرفعال می‌شود که پرچم صراحتاً false باشد. این عمدی است. محافظ برای خروج از حلقه‌های Compaction وجود دارد که در غیر این صورت توکن‌های نامحدود مصرف می‌کنند، بنابراین کاربری که هیچ پیکربندی‌ای ندارد نیز همچنان این محافظت را دریافت می‌کند.

{
  tools: {
    loopDetection: {
      // master switch; set false to disable the guard along with the rolling detectors
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // default
      },
    },
  },
}

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

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

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

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

# مرتبط