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

OpenClaw دو سازوکار محافظتی هماهنگ برای مقابله با الگوهای تکراری فراخوانی ابزار دارد که هر دو در tools.loopDetection پیکربندی می‌شوند:

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

برای غیرفعال‌کردن هر دو سازوکار محافظتی، 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[].tools.loopDetection):

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

تنظیمات ویژهٔ هر عامل، فیلدبه‌فیلد روی بلوک سراسری اعمال می‌شوند (از جمله detectors و postCompactionGuard تودرتو)؛ بنابراین هر عامل فقط باید فیلدهایی را تنظیم کند که می‌خواهد تغییر دهد.

رفتار فیلدها

برای exec، هش‌سازی حالت بدون پیشرفت، نتایج پایدار فرمان (وضعیت، کد خروج، پرچم پایان مهلت و خروجی) را مقایسه می‌کند و فراداده‌های متغیر زمان اجرا مانند مدت‌زمان، PID، شناسهٔ نشست و پوشهٔ کاری را نادیده می‌گیرد. نتایج ارسال پیام خروجی پس از حذف شناسه‌های متغیر هر فراخوانی (شناسهٔ پیام، شناسهٔ فایل و برچسب زمانی) هش می‌شوند؛ بنابراین نتیجهٔ «ارسال‌شده» با یک نتیجهٔ «ارسال‌شده» دیگر یکسان به نظر نمی‌رسد. هنگامی که شناسهٔ اجرا موجود باشد، تاریخچه فقط در محدودهٔ همان اجرا ارزیابی می‌شود؛ بنابراین چرخه‌های زمان‌بندی‌شدهٔ 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: {      // 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 را با ذکر ابزار متخلف و تعداد فراخوانی‌های یکسان تولید می‌کند.

مرتبط