Tools
ツールループの検出
OpenClaw には、反復的なツール呼び出しパターンを防ぐために連携して動作する 2 つのガードレールがあり、
どちらも tools.loopDetection で設定されます。
- ループ検出（
enabled）- デフォルトでは無効です。ローリング形式の ツール呼び出し履歴を監視し、反復パターンや不明なツールの再試行を検出します。 - Compaction 後ガード -
enabledが明示的にfalseでない場合は常に有効です。Compaction の再試行後に毎回作動し、 エージェントがウィンドウ内で同じ(tool, args, result)の組み合わせを 繰り返すと、実行を中止します。
両方のガードレールを無効にするには、tools.loopDetection.enabled: false を設定します。
この機能が存在する理由
- 進展のない反復シーケンスを検出します。
- 高頻度で結果が得られないループ（同じツール、同じ入力、反復する エラー）を検出します。
- 既知のポーリングツールに固有の反復呼び出しパターンを検出します。
- コンテキストオーバーフロー -> Compaction -> 同じループというサイクルを、 無期限に実行させる代わりに中断します。
設定ブロック
グローバル設定：
{ tools: { loopDetection: { enabled: false, // ローリング履歴検出機能のマスタースイッチ }, },}エージェントごとのオーバーライド（任意、agents.entries.*.tools.loopDetection）：
{ agents: { list: [ { id: "safe-runner", tools: { loopDetection: { enabled: true, }, }, }, ], },}エージェントごとの設定はグローバル設定をオーバーライドします。
フィールドの動作
| フィールド | デフォルト | 効果 |
|---|---|---|
enabled |
false |
ローリング履歴検出機能のマスタースイッチです。false にすると Compaction 後ガードも無効になります。 |
exec では、進展なしのハッシュ処理は安定したコマンド結果（ステータス、
終了コード、タイムアウトフラグ、出力）を比較し、実行時間、PID、セッション ID、作業ディレクトリなどの
変動するランタイムメタデータを無視します。外向けメッセージ送信の
結果は、呼び出しごとに変動する ID（メッセージ ID、ファイル ID、タイムスタンプ）を
除外してハッシュ化されるため、ある「送信済み」の結果が別の「送信済み」の
結果と同一とはみなされません。実行 ID が利用可能な場合、履歴はその実行内でのみ評価されるため、
スケジュールされた Heartbeat サイクルや新規実行が、以前の実行から古いループ回数を
引き継ぐことはありません。
推奨設定
- 小規模なモデルでは、
enabled: trueを設定します。フラッグシップモデルでローリング履歴検出が必要になることはほとんどなく、 マスタースイッチをfalseのままにしても、 Compaction 後ガードの恩恵を受けられます。 - Compaction 後ガードを含むすべての機能を無効にするには、
tools.loopDetection.enabled: falseを明示的に設定します。
Compaction 後ガード
コンテキストオーバーフロー後に Compaction の再試行が行われると、ランナーは
続く数回のツール呼び出しに対して短いウィンドウのガードを作動させます。エージェントがそのウィンドウ内で同じ
(toolName, argsHash, resultHash) の組み合わせを十分な回数出力すると、ガードは Compaction によって
ループが解消されなかったと判断し、compaction_loop_persisted エラーで実行を中止します。
このガードはマスター tools.loopDetection.enabled フラグによって制御されますが、1 つ例外があります。
フラグが未設定または true の場合は 有効なまま であり、フラグが明示的に
false の場合にのみ無効になります。これは意図的な動作です。このガードは、
無制限にトークンを消費しかねない Compaction ループから抜け出すために存在するため、
設定を行っていないユーザーにも保護が適用されます。
{ tools: { loopDetection: { // マスタースイッチ。ローリング検出機能とともにガードを無効にするには false に設定する enabled: true, }, },}- 結果が変化している間、ガードが実行を中止することはありません。ウィンドウ全体で バイト単位で同一の結果が得られた場合にのみ作動します。
- 実行中の他の時点ではなく、Compaction の再試行直後にのみ作動します。
ログと想定される動作
ループが検出されると、OpenClaw はループイベントをログに記録し、重大度に応じて 次のツールサイクルに警告を出すかブロックします。これにより、通常のツールアクセスを維持しながら、 制御不能なトークン消費やロックアップを防ぎます。
- 最初に警告が出されます。
- パターンが警告しきい値を超えて継続すると、ブロックされます。
- 重大なしきい値に達すると次のツールサイクルをブロックし、実行記録に明確な ループ検出理由を表示します。
- Compaction 後ガードは、問題のあるツールと同一呼び出し回数を示す
compaction_loop_persistedエラーを出力します。
