loop-circuit-breaker について
OpenClaw向けに、セッション内のツール呼び出し失敗を監視する自動リトライループ検出スキルです。同一の呼び出し署名が繰り返し失敗すると再試行を止め、問題を記録して次の対応をユーザーに確認します。
主な機能
- 01セッションごとのツール呼び出し履歴管理
- 02呼び出し署名による反復失敗の検出
- 03一時的エラーと決定的エラーの分類
- 04検出時の再試行停止と状態記録
- 05閾値を変更するコマンド
活用シーン
- 01引数エラーによるツール呼び出しの反復防止
- 02タイムアウトやレート制限の再試行回数を制限
- 03失敗が続いてコンテキストを使い切る前に停止
- 04エラーを示し、修正・スキップ・中止を選択
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/loop-circuit-breakerを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
check.pyexample-state.yamlSTATE_SCHEMA.yaml詳細
loop-circuit-breaker
OpenClaw はすべてのエラーを同じように再試行します。レート制限やタイムアウトなどの一時的なエラーも、パラメーターの不足、型エラー、無効なパスなどの決定的なエラーも区別しません。このスキルはセッションごとにツール呼び出しの履歴を記録し、同一の失敗が繰り返されたことを検出して、コンテキストウィンドウと API の予算を使い切る前にループを停止します。
agent-self-recovery との違い
agent-self-recovery は手動の事後対応型リカバリープロトコルです。エージェントが行き詰まったことにユーザーまたはエージェントが気づいた後に、呼び出します。
loop-circuit-breaker は自動の事前対応型です。ユーザーが気づく前に、2 回目の同一エラーで作動します。
検出アルゴリズム
ツール呼び出しの結果を受け取るたびに、エージェントは次の項目を確認します。
- このツール呼び出しは失敗しましたか（エラー、例外、または空の結果）？
- 呼び出しのシグネチャを正規化します：（
(tool_name, sorted_args_hash, error_type)） - このシグネチャを、状態に記録されたセッションの呼び出し履歴から検索します
- 同じシグネチャが N 回（デフォルト：2 回）失敗した場合、サーキットブレーカーを作動させます
N=2 の根拠： 一時的なエラーであれば、1 回の再試行は妥当です。同一の引数で同じ失敗が 2 回続いた場合、再試行では解決できない決定的なエラーである可能性が高いと考えられます。
エラーの分類
| エラーの種類 | 分類 | 最大再試行回数 |
|---|---|---|
| レート制限（429） | 一時的 | 3 |
| タイムアウト／ネットワーク | 一時的 | 3 |
| 必須パラメーターの不足 | 決定的 | 1 |
| 型エラー／検証エラー | 決定的 | 1 |
| ファイルが見つからない | 決定的 | 1 |
| アクセス許可がない | 決定的 | 1 |
| 不明なエラー | 不明 | 2 |
サーキットブレーカーが作動したとき
- 直ちに再試行を停止します — 同じ呼び出しを再度実行しないでください
- 根本原因を診断します — エラーメッセージを注意深く読みます
- 次の情報とともに
LOOP_DETECTEDを状態に書き込みます：ツール名、引数、エラー、失敗回数、最初と最後のタイムスタンプ - ユーザーに通知します：「
<tool>(<args>)の再試行ループを検出しました。エラーは次のとおりです：<error>。再試行を停止しました。どのように進めましょうか？」 - 選択肢を提示します：引数を修正する、このステップをスキップする、またはタスクを中止する
セッションの範囲
ループの検出はセッションごとに行われます。新しいセッションの開始時に状態はリセットされます。2 時間を超えた呼び出し履歴は、状態から自動的に削除されます。
調整
決定的なエラーの再試行しきい値を調整するには：
python3 check.py --set-threshold 3 # Allow 3 failures before tripping