環境変数

CLAUDE_CODE_RETRY_WATCHDOG

評価ハーネス、CIジョブ、またはリモートワーカーなどの無人セッション向けに、429や529エラーを無制限にリトライするように設定します。

使い方・用途

  • CI/CDパイプラインなどの自動実行環境において、レート制限や一時的なサーバー負荷による失敗を防ぎ、成功するまでバックオフを取りながら待機させます。
  • CLAUDE_CODE_MAX_RETRIESの設定にかかわらず、リミットが解除されるまでリトライを継続させたい場合に有効です。
英語原文(公式ドキュメントより)

Set to 1 for unattended sessions such as eval harnesses, CI jobs, or remote workers. Retries 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. The watchdog backs off up to 5 minutes between attempts, or until the limit resets when the response carries a rate-limit reset time, so a session that hits a usage limit waits out the remaining window. Requires Claude Code v2.1.186 or later

関連ドキュメント

関連する変更履歴

v2.1.271(1件)

Fixed
使用クレジットの上限に達した際にターンが失敗したり、オーバーロードを fast speed のままリトライしてしまう問題を修正し、標準速度へフォールバックするようにした
英語原文を表示
Fixed fast mode under CLAUDE_CODE_RETRY_WATCHDOG failing the turn on a usage-credits limit, or retrying an overload at fast speed, instead of falling back to standard speed

変更前

CLAUDE_CODE_RETRY_WATCHDOG 環境変数が設定された環境で fast mode を使っている際に、使用クレジットの上限に達するとターンが失敗したり、オーバーロードを fast speed のままリトライしてしまっていた

変更後

CLAUDE_CODE_RETRY_WATCHDOG 環境変数が設定された環境で fast mode を使っている際に、使用クレジットの上限に達してもオーバーロードを fast speed のままリトライしてしまい、ターンが失敗しなくなった

ユーザーへの恩恵

使用クレジットの上限に達した場合でもターンが失敗せず、標準速度へのフォールバックによって処理が継続できるようになった

関連ドキュメント

v2.1.260(1件)

Fixed
エージェントチームを修正した:in-process の teammate の transcript が、長い API リトライ待ち(例: CLAUDE_CODE_RETRY_WATCHDOG 設定下)の間にリトライ通知が実際のメッセージを押し出した結果として、メッセージを失ったり空白になったりする問題を修正した。
英語原文を表示
Fixed agent teams: an in-process teammate's transcript losing messages, or going blank, during long API retry waits (e.g. under CLAUDE_CODE_RETRY_WATCHDOG) as retry notices evicted real messages

変更前

エージェントチームにおいて、長い API リトライ待ち(例: CLAUDE_CODE_RETRY_WATCHDOG 設定時)の間に、リトライ通知が実際のメッセージを置き換えてしまい、in-process モードの teammate の transcript でメッセージが失われたり表示が空白になったりしていた。

変更後

修正前は、CLAUDE_CODE_RETRY_WATCHDOG などの設定による長い API リトライ待ちの間に、リトライ通知が transcript 内の実際のメッセージを押し出してしまい、in-process の teammate の transcript でメッセージが失われたり、表示が真っ空白になったりすることがあった。修正後は、リトライ通知が実際のメッセージを置き換えなくなり、リトライ待ちの間も teammate の transcript にメッセージが保持される。

ユーザーへの恩恵

長時間の API リトライが発生しても teammate の会話履歴が消えないため、ユーザーは各 teammate が何をしていたかを確認したまま対処できる。

関連ドキュメント

v2.1.239(1件)

Changed
継続的な自動リトライモード（CLAUDE_CODE_RETRY_WATCHDOG）が有効な場合であっても、組織の利用枠上限（spend-limit）やクレジット残高不足などの回復不能な課金エラーが発生した際には、待機を続けずに即座にエラーとして終了するように変更しました。
英語原文を表示
Persistent retry mode (CLAUDE_CODE_RETRY_WATCHDOG) now fails immediately on organization spend-limit and out-of-credits errors instead of waiting indefinitely for a reset

変更前

CI サーバーなどの自動化実行で CLAUDE_CODE_RETRY_WATCHDOG=1 を設定している際、API サーバーの一時的な過負荷（429や529）だけでなく、組織の月間予算オーバーやクレジット切れといった「時間が経っても自動では復旧しない課金エラー」に対しても、無駄に最大300回・約3時間もの無限ループ待機を試みてしまい、CI ジョブを詰まらせていました。

変更後

リトライ監視ロジックがエラーレスポンスを厳密に分類し、解決に手動のアクション（請求管理者のチャージや上限変更）が必要な「429 billing_error」などを検出した場合は、1回目の試行で即座にリトライを打ち切ってプロセスをエラー終了させます。

ユーザーへの恩恵

クレジット切れなどの解決不能な問題が起きた際に、CI ビルドやバッチ処理が何時間もスタックして課金時間やキューを浪費するのを防げます。

関連ドキュメント

v2.1.199(1件)

Changed
Settings
バックグラウンド処理の堅牢性を高めるため、デフォルトのリトライ上限を 300 回に引き上げ、ハード上限の 15 回を撤廃
英語原文を表示
CLAUDE_CODE_RETRY_WATCHDOG now raises the default retry count for non-capacity transient errors to 300 and lifts the cap of 15 on CLAUDE_CODE_MAX_RETRIES

変更前

通信エラー等の際、最大リトライ回数が 15 回に制限されており、一時的な障害でセッションが失敗しやすくなっていました。

変更後

非容量性のエラーに対しては最大 300 回まで自動リトライし、かつ上限を撤廃することで粘り強く接続を維持します。

ユーザーへの恩恵

CIやリモート環境などの自動化タスクが、一時的なネットワーク断絶で失敗する確率を大幅に減らせます。

関連ドキュメント

v2.1.186(1件)

Changed
Settings
CLAUDE_CODE_MAX_RETRIES の上限が15回に変更されました。無人セッションでの利用には、代わりに CLAUDE_CODE_RETRY_WATCHDOG の使用が推奨されます。
英語原文を表示
Changed CLAUDE_CODE_MAX_RETRIES to cap at 15; for unattended sessions, use CLAUDE_CODE_RETRY_WATCHDOG instead

変更前

リトライ回数を過剰に設定できていたため、接続障害時にプロセスが長時間停止してしまうことがありました。

変更後

リトライ回数に適切な上限が設けられ、より堅牢な監視メカニズムであるウォッチドッグの利用が促されるようになりました。

ユーザーへの恩恵

エラー時の挙動が予測可能になり、特に自動化スクリプトなどでの信頼性が向上します。

関連ドキュメント