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

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

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

برای خاموش‌کردن هر دو سازوکار محافظتی، tools.loopDetection.enabled: false را تنظیم کنید.

دلیل وجود این قابلیت

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

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

تنظیم سراسری:

{  tools: {    loopDetection: {      enabled: false, // کلید اصلی آشکارسازهای تاریخچهٔ چرخشی    },  },}

بازنویسی مخصوص هر عامل (اختیاری، در agents.entries.*.tools.loopDetection):

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

تنظیم مخصوص هر عامل، تنظیم سراسری را بازنویسی می‌کند.

رفتار فیلدها

برای exec، هش‌سازیِ عدم پیشرفت، نتایج پایدار فرمان (وضعیت، کد خروج، پرچم پایان مهلت، خروجی) را مقایسه می‌کند و فرادادهٔ متغیر زمان اجرا، مانند مدت، PID، شناسهٔ نشست و دایرکتوری کاری را نادیده می‌گیرد. نتایج ارسال پیام پس از حذف شناسه‌های متغیر هر فراخوانی (شناسهٔ پیام، شناسهٔ فایل، برچسب زمانی) هش می‌شوند تا یک نتیجهٔ «ارسال‌شده» با نتیجهٔ «ارسال‌شده» دیگری یکسان به نظر نرسد. هنگامی که شناسهٔ اجرا موجود باشد، تاریخچه فقط در همان اجرا ارزیابی می‌شود؛ بنابراین چرخه‌های زمان‌بندی‌شدهٔ Heartbeat و اجراهای تازه، شمارش‌های کهنهٔ حلقه را از اجراهای قبلی به ارث نمی‌برند.

تنظیم پیشنهادی

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

محافظ پس از Compaction

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

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

{  tools: {    loopDetection: {      // کلید اصلی؛ برای غیرفعال‌کردن محافظ همراه با آشکارسازهای چرخشی، آن را روی false تنظیم کنید      enabled: true,    },  },}

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

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

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

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

مرتبط