ツールループ検出

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. ループ検出 (tools.loopDetection.enabled) — デフォルトでは無効です。ローリング形式のツール呼び出し履歴を監視し、反復パターンと不明ツールの再試行を検出します。
2. Compaction 後ガード (tools.loopDetection.postCompactionGuard) — tools.loopDetection.enabled が明示的に false に設定されていない限り、デフォルトで有効です。各 Compaction 再試行後に作動し、エージェントがウィンドウ内で同じ (tool, args, result) の 3 要素を出力した場合に実行を中止します。

​

これが存在する理由

• 進捗を生まない反復シーケンスを検出する。
• 高頻度の結果なしループ（同じツール、同じ入力、反復するエラー）を検出する。
• 既知のポーリングツールに対する特定の反復呼び出しパターンを検出する。
• コンテキストオーバーフロー、Compaction、同じループというサイクルが無期限に実行されるのを防ぐ。

​

設定ブロック

{
  tools: {
    loopDetection: {
      enabled: false, // master switch for the rolling-history detectors
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      unknownToolThreshold: 10,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
      postCompactionGuard: {
        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
      },
    },
  },
}

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

​

フィールドの挙動

​

推奨設定

• 小さめのモデルでは、enabled: true を設定し、しきい値はデフォルトのままにします。フラッグシップモデルではローリング履歴検出が必要になることはほとんどなく、マスタースイッチを false のままにしつつ、Compaction 後ガードの恩恵は受けられます。
• しきい値は warningThreshold < criticalThreshold < globalCircuitBreakerThreshold の順序を保ちます。
• 誤検出が発生する場合:
  • warningThreshold や criticalThreshold、またはその両方を引き上げます。
  • 必要に応じて globalCircuitBreakerThreshold を引き上げます。
  • 問題を起こしている特定の検出器だけを無効化します（detectors.<name>: false）。
  • 履歴コンテキストを緩めるために historySize を減らします。
• すべて（Compaction 後ガードを含む）を無効化するには、tools.loopDetection.enabled: false を明示的に設定します。

​

Compaction 後ガード

{
  tools: {
    loopDetection: {
      // master switch; set false to disable the guard along with the rolling detectors
      enabled: true,
      postCompactionGuard: {
        windowSize: 3, // default
      },
    },
  },
}

• windowSize が低いほど厳格です（中止前の試行回数が少なくなります）。
• windowSize が高いほど、エージェントにより多くの回復試行を与えます。
• ガードは結果が変化している場合には中止せず、ウィンドウ全体で結果がバイト単位で同一の場合にのみ中止します。
• 意図的に範囲を狭くしています。Compaction 再試行の直後にのみ発火します。

​

ログと期待される挙動

• まず警告が出ます。
• パターンが警告しきい値を超えて継続すると抑制が続きます。
• 重大しきい値では次のツールサイクルがブロックされ、実行レコードに明確なループ検出理由が表示されます。
• Compaction 後ガードは、問題のツール名と同一呼び出しカウントを含む compaction_loop_persisted エラーを出力します。

​

関連