ツールループ検出

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はループイベントを報告し、重大度に応じて次のツールサイクルをブロックまたは抑制します。これにより、通常のツールアクセスを維持しつつ、暴走するトークン消費やロックアップからユーザーを保護します。

まず警告と一時的な抑制を優先。
繰り返しのエビデンスが蓄積された場合にのみエスカレート。

注意事項

tools.loopDetectionはエージェントレベルのオーバーライドとマージされます。
エージェント単位の設定はグローバル値を完全にオーバーライドまたは拡張します。
設定が存在しない場合、ガードレールはオフのままです。