Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

CLAUDE_CODE_RETRY_WATCHDOG が、キャパシティ起因ではない一時的なエラーに対するデフォルトのリトライ回数を300回まで引き上げ、CLAUDE_CODE_MAX_RETRIES に設定されていた上限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

概要 ​

CLAUDE_CODE_RETRY_WATCHDOG は、CIジョブなど無人で動かすセッション向けに、429・529 のキャパシティエラーを CLAUDE_CODE_MAX_RETRIES の回数で諦めずに無期限にリトライし続けるための環境変数です。v2.1.199からはこれに加えて、サーバーエラーやタイムアウト、接続切断といった「キャパシティ起因ではない」一時的なエラーについても、デフォルトのリトライ回数が10回から300回（バックオフを含めておよそ3時間分）に引き上げられ、さらに CLAUDE_CODE_MAX_RETRIES を明示的に設定した場合でもv2.1.186以降適用されていた上限15回が解除されるようになりました。

基本的な使い方 ​

環境変数を 1 に設定するだけで有効になります。

bash
export CLAUDE_CODE_RETRY_WATCHDOG=1
claude -p "run the full test suite and fix any failures"

実践例 ​

CI/CDパイプラインで無人実行時のリトライを強化する ​

夜間バッチやCIジョブなど、人が張り付いていない環境では、一時的なサーバー障害やネットワーク断でセッションが失敗するのを避けたいことがあります。

yaml
# .github/workflows/nightly-agent.yml の一部
env:
  CLAUDE_CODE_RETRY_WATCHDOG: "1"
steps:
  - run: claude -p "run migrations and report status"

これにより、429/529 のキャパシティエラーは無期限にリトライされ、その他の一時的なエラー（サーバーエラー・タイムアウト・接続切断など）もデフォルトで300回までリトライされます。

CLAUDE_CODE_MAX_RETRIES と組み合わせてさらに調整する ​

CLAUDE_CODE_RETRY_WATCHDOG=1 を設定した状態で CLAUDE_CODE_MAX_RETRIES を明示的に指定すると、v2.1.199からは15回という上限が解除されるため、より大きな値を指定できます。

bash
export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_MAX_RETRIES=1000

対話セッションでは基本的に設定しない ​

対話的に使っている通常のセッションでは、リトライに長時間かかると単に応答が返ってこないように見えてしまうため、CLAUDE_CODE_RETRY_WATCHDOG はCIやバッチ処理など無人実行のケースに限定して使うことが推奨されます。

注意点 ​

  • CLAUDE_CODE_RETRY_WATCHDOG を設定しない場合、デフォルトのリトライ回数は10回で、CLAUDE_CODE_MAX_RETRIES の上限はv2.1.186以降15回です。
  • CLAUDE_CODE_RETRY_WATCHDOG=1 を設定すると、429/529 のキャパシティエラーは無期限にリトライされます。
  • v2.1.199からは、キャパシティ以外の一時的なエラー（サーバーエラー・タイムアウト・接続切断など）のデフォルトリトライ回数も300回に引き上げられ、CLAUDE_CODE_MAX_RETRIES を明示的に設定した場合の15回という上限も解除されます。
  • 300回のリトライはバックオフを含めておよそ3時間分に相当します。
  • TLS証明書検証エラーなど、リトライしても解決しないクラスのエラーはこの対象外で、最初の試行で即座に失敗します。

関連情報 ​