OpenClawのツールループ検出設定：無限ループを防止する

エージェントを開発していると、同じツールを何度も呼び出し続けたり、エラーのループから抜け出せなくなったりすることはありませんか？トークンの無駄遣いや、処理が止まってしまうのは、開発者にとって大きな悩みどころですよね。

OpenClawには、エージェントが同じツール呼び出しのパターンで停滞するのを防ぐ機能があります。このガード機能はデフォルトでは無効になっています。設定が厳しすぎると、正当な繰り返しの呼び出しまでブロックしてしまう可能性があるため、必要な場所で有効にするのがおすすめです。

なぜこれが必要なのか

進展のない繰り返しのシーケンスを検知するため。
高頻度で結果が得られないループ（同じツール、同じ入力、繰り返されるエラー）を検知するため。
既知のポーリングツールにおける特定の繰り返しパターンを検知するため。

設定ブロック

グローバルのデフォルト設定は以下の通りです。

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

エージェントごとの個別設定（オプション）は以下の通りです。

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

フィールドの動作

enabled: メインスイッチです。false の場合、ループ検知は行われません。
historySize: 分析のために保持される直近のツール呼び出しの数です。
detectorCooldownMs: 進展なし検知（no-progress detector）で使用されるタイムウィンドウです。
repeatThreshold: 警告やブロックを開始するまでの最小繰り返し回数です。
criticalThreshold: より厳格な処理をトリガーする、より強力なしきい値です。
detectors.repeatedFailure: 同じ呼び出しパスでの失敗した試行の繰り返しを検知します。
detectors.knownPollLoop: 既知のポーリングのようなループを検知します。
detectors.repeatingNoProgress: 状態変化のない高頻度の繰り返し呼び出しを検知します。

推奨設定

まずは enabled: true にし、デフォルト値のままで始めてみてください。
もし誤検知（false positives）が発生した場合は、以下の調整を検討しましょう。
- repeatThreshold や criticalThreshold の値を上げる。
- 問題を起こしている特定の検知器（detector）のみを無効にする。
- historySize を小さくして、過去のコンテキストをあまり厳しく参照しないようにする。

ログと期待される動作

ループが検知されると、OpenClawはループイベントを報告し、深刻度に応じて次のツールサイクルをブロックまたは抑制します。これにより、通常のツールアクセスを維持しながら、トークンの過剰な消費やフリーズからユーザーを守ります。

まずは警告や一時的な抑制を優先します。
繰り返しの証拠が蓄積された場合にのみ、制限を強化します。

注意事項

tools.loopDetection はエージェントレベルの設定とマージされます。
エージェントごとの設定は、グローバル値を完全に上書き、または拡張します。
設定が存在しない場合、ガードレール機能はオフのままとなります。

AI Setup Assistant

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。