設定 OpenClaw 工具迴圈偵測：防止 AI 陷入無限迴圈

寫過 AI Agent 的人都知道，最怕的就是 Agent 突然「卡住」或是陷入無限迴圈，對著同一個 API 瘋狂發送請求。這不僅會讓你的 Token 支出瞬間爆炸，還可能導致帳號因為異常流量被封鎖。

OpenClaw 內建了工具迴圈偵測機制，可以防止 Agent 陷入這種重複的工具調用模式。不過要記得，這個防護機制預設是關閉的。建議你只在必要時開啟，因為如果設定過於嚴格，可能會誤擋掉一些正常的重複調用。

為什麼需要這個功能

• 偵測沒有實質進展的重複序列，以及高頻率且無結果的迴圈（例如相同的工具、相同的輸入，卻不斷重複報錯）。
• 偵測針對已知輪詢 (polling) 工具的特定重複調用模式。

配置區塊

全域預設值：

{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 20,
      detectorCooldownMs: 12000,
      repeatThreshold: 3,
      criticalThreshold: 6,
      detectors: {
        repeatedFailure: true,
        knownPollLoop: true,
        repeatingNoProgress: true,
      },
    },
  },
}

個別 Agent 覆寫（選填）：

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

欄位行為

• enabled: 總開關。設定為 false 時不會執行任何迴圈偵測。
• historySize: 保留用於分析的近期工具調用數量。
• detectorCooldownMs: 「無進展偵測器」使用的時間窗口。
• repeatThreshold: 開始觸發警告或阻斷前的最小重複次數。
• criticalThreshold: 更嚴格的門檻，會觸發更強力的處理機制。
• detectors.repeatedFailure: 偵測在相同調用路徑上重複失敗的嘗試。
• detectors.knownPollLoop: 偵測類似輪詢的已知迴圈。
• detectors.repeatingNoProgress: 偵測高頻率且狀態未改變的重複調用。

建議設定

• 你可以先從 enabled: true 開始，並暫時維持預設值。
• 如果在使用過程中出現誤判（False Positives）：
  • 調高 repeatThreshold 或 criticalThreshold。
  • 針對性地關閉造成問題的偵測器。
  • 減少 historySize 以降低歷史背景的分析嚴格度。

日誌與預期行為

當偵測到迴圈時，OpenClaw 會記錄一個迴圈事件，並根據嚴重程度阻斷或減緩下一個工具週期。這能保護你免於失控的 Token 支出，同時盡可能保留正常的工具存取權限。

• 系統會優先採用警告和暫時抑制的手段。
• 只有在重複證據持續累積時，才會升級處理強度。

注意事項

• tools.loopDetection 會與 Agent 層級的覆寫設定進行合併，且個別 Agent 的配置會完全覆寫或擴充全域數值。
• 如果你的配置檔中沒有相關設定，防護機制會保持關閉狀態。

下一步

• 了解 Agent 配置
• 管理工具列表

想要更快速地完成設定嗎？試試我們的 AI Setup Assistant。