工具迴圈偵測

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：偵測交替的乒乓模式。

建議設定

先以 enabled: true 啟用，其他保持預設值。
門檻值維持遞增順序：warningThreshold < criticalThreshold < globalCircuitBreakerThreshold。
如果出現誤判：
- 提高 warningThreshold 和/或 criticalThreshold
- （可選）提高 globalCircuitBreakerThreshold
- 僅停用造成問題的偵測器
- 減少 historySize 以降低歷史上下文的嚴格度

日誌與預期行為

偵測到迴圈時，OpenClaw 會回報迴圈事件，並根據嚴重程度封鎖或抑制下一次工具循環。這可以保護使用者免於 token 消耗失控與系統鎖定，同時維持正常的工具存取。

優先採用警告和暫時抑制。
僅在重複證據累積時才升級處置。

注意事項

tools.loopDetection 與代理層級覆寫合併。
代理層級設定會完全覆寫或擴展全域值。
若無任何設定，防護機制維持關閉。