Claude Code RETRY_WATCHDOGとは｜設定

「夜中に回しているClaude Codeの自動処理が、使用上限に当たって朝まで止まっていた」「再試行させたいが、待ち続けて次のジョブとぶつかるのも困る」——claude -p を cron や launchd で無人実行している人ほど、この2つの間で迷います。

結論から言うと、CLAUDE_CODE_RETRY_WATCHDOG は、無人実行のときに「待てば直る失敗」を回数の上限なしで待つ再試行モードです。2026年10月15日公開のClaude Code 2.1.301で、このモードに使用上限の解除を待つ時間の上限（CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS）が加わりました。10月8日の2.1.295で入った混雑（429・529）を待つ時間の上限と合わせて、「次の実行まで」から逆算した2つの待ち時間を決めておくのが、無人で回すときの正しい使い方です。

株式会社Fyveは、社内のMac miniでClaude Codeの無人ジョブを毎日10本あまり回しています。この記事では、公式の更新履歴とドキュメントを照らし合わせて設定の意味を整理したうえで、私たちの3か月半・約1,090回の実行記録で実際に起きた4回の停止に当てはめ、待ち時間の上限をどう決めるかまでを具体的に書きます。

CLAUDE_CODE_RETRY_WATCHDOGとは｜無人実行のための再試行モード

まず2.1.301の更新履歴の原文です。

Added CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS so unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) ends a request at a usage limit that resets too far away instead of waiting

日本語にすると「無人の再試行モード（CLAUDE_CODE_RETRY_WATCHDOG）が、解除が遠すぎる使用上限に当たったとき、待たずにその要求を終えるための設定を追加した」という内容です。npmへの公開時刻は2026年10月15日 14:34（UTC）でした。

ここで出てくる「無人の再試行モード」が CLAUDE_CODE_RETRY_WATCHDOG です。公式ドキュメント（環境変数のページ）の説明を要約すると、次のとおりです。

• 値に 1 を入れると有効になる。想定する用途は評価用のハーネス、CIのジョブ、リモートの作業機など、人が見ていない実行
• 混雑や一時的な制限を表す 429・529のエラーを、回数の上限なしで再試行する（通常は CLAUDE_CODE_MAX_RETRIES の回数で諦める）
• 再試行の間隔は最大5分まで伸びる。応答に制限の解除時刻が含まれていれば、解除時刻まで待つ。つまり使用上限に当たった実行は、残りの時間をまるごと待つ
• サーバーエラー・タイムアウト・切断など、ほかの一時的な失敗の再試行回数も、既定で300回（およそ3時間分）に引き上げる

何も設定しない場合との違いを表にすると、こうなります。

再試行モードは、言い換えると「待てば直る失敗」を待つための設定です。人が見ている対話型のセッションなら、止まったら人が打ち直せば済みます。無人実行では打ち直す人がいないので、待つか諦めるかを先に決めておく必要があります。

版ごとの変遷｜「待ち続ける」から「上限を決めて待つ」へ

このモードは2026年6月に入ってから、更新履歴の上で少なくとも5回、振る舞いが変わっています。主な変更を版順に並べます（公開日はnpmの公開時刻・UTC）。

このほかにも、長い応答の途中で失敗したあと何時間も再試行し続ける不具合（2.1.288で修正）や、429・529の待ちが続いた後の最初の5xxで失敗してしまう不具合（2.1.281で修正）など、「待ち方」に関する修正が何度も入っています。

流れを1行でまとめると、最初は「とにかく待ち続ける」モードだったものに、「何を待たないか」「どこまで待つか」が順に足されてきた、ということです。8月の2.1.239で「お金の上限は待たない」が決まり、10月の2.1.295と2.1.301で「混雑」と「使用上限」のそれぞれに待ち時間の天井を付けられるようになりました。

この記事を読んでいるあなたへ無料プレゼントClaude Codeを「素のまま」使うな設定で差がつく——CLAUDE.md・権限・スキルの実物を公開（全24ページ）

そのまま書き換えて使えるCLAUDE.mdの型お金と送信をAIに触らせない「3段階の柵」1回教えたら何度でも動く、手順書のコピペ雛形

無料でダウンロード

中身のプレビューを見る ↓登録すると、過去の特典もまとめて受け取れます（PDF 17点・合計440ページ ＋ すぐ使えるzip素材 3点）

エラーの種類で振る舞いが違う｜429・529・使用上限・支出上限

設定を決める前に、どの失敗をどの設定が縛るのかを1枚にまとめておきます。

429・529は「混雑」で、使用量には数えられない

529はAPI側が混み合っているときのエラーです。公式のエラー解説には「529は使用上限ではなく、使用量にも数えられない」と書かれています。待てば解消することが多い種類の失敗で、再試行モードが最も効くのはここです。

使用上限は「解除時刻まで」待つ。週間枠なら数日先のことも

サブスクリプションで使っている場合、使用量には5時間ごとの枠と週ごとの枠があります。公式のエラー解説に載っている表示例は次のとおりです。

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am

再試行モードは、この解除時刻まで待ちます。5時間枠なら長くても数時間ですが、週間枠に当たった場合は、次の月曜まで待ち続けることになります。その間、ジョブはプロセスとして生き続け、ログにも結果が出ません。2.1.301で入った上限は、まさにこの「解除が遠すぎる」ケースで待つのをやめるためのものです。

支出上限・クレジット切れは待たない

組織の支出上限やクレジット残高の不足は、待っても解消しません（解除日が決まっている支出上限でも同じ扱いです）。2.1.239より前の再試行モードはこれも待ち続けていましたが、今は即座に失敗します。ここは設定不要です。

サーバーエラー・切断は「回数」で縛る

見落としやすいのがここです。再試行モードでは、サーバーエラー（5xx）やタイムアウト、切断の再試行が既定で300回、時間にしておよそ3時間分まで伸びます。後で説明する2つの待ち時間の上限は429・529と使用上限の話なので、こちらを縮めたいなら CLAUDE_CODE_MAX_RETRIES を明示するしかありません。再試行モードの下では、この値に15の上限はかかりません。

2つの待ち時間の上限｜MAX_WAIT_MS と MAX_USAGE_LIMIT_WAIT_MS の違い

CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS（2.1.295〜）

公式ドキュメントの説明は次のとおりです。

• 再試行モードのとき、1つのAPIリクエストが429・529を待つのに使える時間の上限（ミリ秒）
• その時間を使い切った後、次に同じ種類のエラーが来たらリクエストを終える
• 正の整数を数字だけで書く。ドキュメントの例は 1800000（30分）
• 設定しなければ、待ち時間に上限はない

CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS（2.1.301〜）

こちらは2026年10月16日時点で、公式ドキュメントの環境変数の一覧にまだ載っていません。情報源は冒頭に引いた更新履歴の1行だけです。そこから読み取れるのは次の点です。

• 対象は使用上限に当たったとき
• 解除が「遠すぎる」場合は、待たずにその要求を終える
• 名前の末尾が _MS なので、ほかの2つと同じくミリ秒で指定すると読める

一方で、既定値と、MAX_WAIT_MS との関係（使用上限の待ちが MAX_WAIT_MS の時間にも数えられるのか）は、更新履歴にもドキュメントにも書かれていません。この記事では推測で埋めません。実務上は、両方を明示的に設定しておけば、どちらの解釈でも待ち時間は自分の決めた値の内に収まるので、それで足ります。

2つの違いを一言で

私たちの無人ジョブで起きた4回の停止

ここからは自社の記録です。私たちはMac miniで、記事の素材集め・SEO記事の執筆・Xの投稿判断などを claude -p の無人ジョブとして回しています。実行のたびに結果を1行ずつ記録していて、2026年7月7日から10月15日までの約3か月半で、記録は約1,090回ありました。

このうち終了コードが0以外（失敗）だったのは5回です。1回はX側のAPIのクレジット切れでClaude Codeとは無関係なので、Claude Code側の失敗は次の4回でした。

4回とも、再試行モードの対象になる種類の失敗でした。そして4回とも、私たちは再試行モードを使っていませんでした。

7月21日：20分待てば済んだ使用上限

一番わかりやすいのが7月21日です。05:00に始まった朝の素材集めが、使用上限（5時間枠）に当たってその場で終わりました。表示された解除時刻は05:20、つまりあと20分待てば続けられた失敗です。

実害は、そのジョブ1本では済みませんでした。この素材を前提に、08:00・12:30・17:30にXへの投稿判断を行う後続のジョブがありますが、その日は3回とも「当日の素材がない」として投稿を見送っています。1本の失敗が、その日の後続3回分をまとめて空にした形です。

7月30日：同じ朝に2本続けて529

7月30日は、05:00の素材集めと06:00の記事執筆が、どちらも529（API側の混雑）で失敗しました。既定の10回の再試行では足りなかったということです。さらに、素材集めが落ちたことで、14:00の記事執筆も「新しい種がない」として何も書かずに終わりました。

この2件は、再試行モードを入れていれば混雑が引くまで待ったはずです。ただし、どのくらい待てば通ったのかは記録に残っておらず、わかりません。だからこそ、待つ時間に上限を付けたうえで有効にするのが筋になります。

「入れればいい」で終わらない理由

では再試行モードを入れて終わりかというと、無人のジョブを何本も回している環境では、そう単純ではありません。私たちのジョブは、同じ作業場所を書き換えるため1本ずつ順番に動かしています。前のジョブが動いている間、次のジョブは最大50分待ち、それを過ぎたら実行を見送る作りです。

ここで1本が使用上限の解除を何時間も待つと、その間、後ろに並んだジョブが順に見送られていきます。上限なしで待たせるのは、1本の失敗を、後ろのジョブをまとめて止める失敗に変えかねません。待たせるなら、どこまで待たせるかを先に決めておく必要があります。

待ち時間の上限の決め方｜「次の実行まで」から逆算する

私たちの7月21日の例に当てはめて、決め方を図にしました。

手順1：猶予を測る

まず、そのジョブの結果を使う処理（または、同じ場所を使う次のジョブ）がいつ動くかを確認します。そこからこのジョブ自体にかかる時間を引いた残りが、待ってよい時間の上限です。

7月21日の例なら、後続の投稿判断が08:00に動くので、05:00からの猶予は3時間です。処理に最長1時間かかると見積もれば、待ってよいのは2時間までになります。

手順2：使用上限の待ちを猶予より短くする

使用上限の待ち（CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS）は、手順1の猶予より短い値にします。例では余裕を見て90分（5400000）です。こうしておけば、5時間枠の解除が20分後なら待って続け、週間枠のように解除が数日先なら待たずに終わります。

手順3：混雑の待ちを決める

429・529の待ち（CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS）も、猶予の範囲で決めます。例では公式ドキュメントの例示値と同じ30分（1800000）にしました。2つの待ちの関係が公式に書かれていない以上、2つを足しても猶予に収まる値にしておくと安全です（例では90分＋30分＝2時間）。

手順4（任意）：その他の失敗の回数と、ジョブ全体の時間

サーバーエラーや切断の再試行は既定で300回（およそ3時間）まで続きます。猶予が3時間より短いジョブなら、CLAUDE_CODE_MAX_RETRIES を明示して回数を減らします。

そのうえで、ジョブ全体に外側から制限時間をかけておくと、想定外の待ちにも天井ができます。公式ドキュメントによると、claude -p の実行をSIGTERMで止めると終了コード143で終わり、実行中だったターンは結果を残しません。SIGINTで止めた場合はターンを終えてから終了します。止めた後で「何をやりかけていたか」を追えるよう、外側の制限時間は最後の保険として使うのがよいと考えています。

設定の渡し方｜cron・launchd・GitHub Actions

3つとも環境変数なので、無人ジョブを起動する側で渡します。

cron

0 5 * * * CLAUDE_CODE_RETRY_WATCHDOG=1 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=5400000 /usr/local/bin/claude -p "（指示）" --model claude-sonnet-5-5 >> "$HOME/logs/morning-job.log" 2>&1

launchd（macOS）

plist の EnvironmentVariables に書きます。

<key>EnvironmentVariables</key>
<dict>
  <key>CLAUDE_CODE_RETRY_WATCHDOG</key><string>1</string>
  <key>CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS</key><string>1800000</string>
  <key>CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS</key><string>5400000</string>
</dict>

GitHub Actions

- name: Run Claude Code
  env:
    CLAUDE_CODE_RETRY_WATCHDOG: "1"
    CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS: "1800000"
    CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS: "5400000"
  run: claude -p "（指示）" --model claude-sonnet-5-5

GitHub Actions ではジョブ自体の制限時間（timeout-minutes）が手順4の外側の保険になります。待ち時間の上限は、この制限時間より短くしておきます。

settings.json の env に書くのは避ける

settings.json の env にも環境変数は書けますが、そこに書くと対話型のセッションにも同じ設定がかかります。再試行モードは無人実行のための設定で、待ち時間の適正値もジョブごとに違います。ジョブを起動する側で、ジョブごとに渡すのが扱いやすいと考えています。

版を確認する：stable チャネルにはまだ来ていない

2026年10月16日時点のnpmの配布チャネルは、latest が2.1.301、stable が2.1.292です。stable で使っている場合、MAX_WAIT_MS（2.1.295〜）も MAX_USAGE_LIMIT_WAIT_MS（2.1.301〜）もまだ入っていません。古い版では、知らない環境変数は単に無視されると考えられ、設定したつもりで効いていない状態になります。

claude --version
npm view @anthropic-ai/claude-code dist-tags

私たちの作業機も、この記事を書いている時点では2.1.296で、使用上限の待ちを縛る設定はまだ使えない版でした。版を上げてから設定する、が順番です。

上限で終わったことに気づける形にする

待ち時間に上限を付けるということは、「上限まで待っても直らなければ、失敗として終わる」ということです。無人実行で一番困るのは、終わったことに誰も気づかないことなので、最後に通知の形を決めておきます。

終了コードで分ける

公式ドキュメントによると、claude -p は成功すれば終了コード0、失敗すれば0以外で終わります。認証切れのような実行中の失敗は、結果として標準出力に書き出されます。まずは「0以外なら通知する」を起動スクリプトに入れます。私たちの4回の停止も、この終了コードで拾えていました。

結果の文面で分ける

終了コードだけでは「なぜ止まったか」がわからないので、結果の文面を固定の文字列で探して通知を分けると、朝の判断が早くなります。たとえば次のような分け方です。

• hit your session limit / hit your weekly limit → 使用上限。解除時刻も同じ行に出る
• 529 Overloaded → 混雑。待ち時間の上限を使い切った可能性
• spend limit / Credit balance is too low → お金の上限。待っても直らないので人が対処する

私たちは、ジョブの終了後に実行ログを固定の文字列で走査して、引っかかればSlackに通知する仕組みを持っています。以前、ジョブ自体は正常終了のまま中身だけが失敗していて、気づくのが遅れたことがあり、それ以来「AIの自己申告に頼らず、文字列で機械的に拾う」形にしました。ただ、今回あらためて見直したところ、その走査の対象は認証切れの文言だけで、使用上限や529の文言は入っていませんでした。再試行モードを入れるなら、走査する文言もあわせて足すべきだと考えています。

再試行の途中経過を残す

出力形式を --output-format stream-json にしている場合、再試行のたびに system/api_retry というイベントが出ます。何回目の再試行か（attempt）、次まで何ミリ秒待つか（retry_delay_ms）、HTTPステータス（error_status）、エラーの分類（rate_limit・overloaded など）が含まれるので、ログに残しておけば「どのくらい待って通ったか」を後から数えられます。7月30日の529のように、待てば通ったのかどうかが記録に残っていない状態を避けられます。

無人実行の止まり方そのものについては、エラーが出ずに静かに止まる型を別の記事にまとめています。

Claude CodeAIの無人実行が止まる原因3つ｜エラーが出ない停止の見つけ方

サブエージェントの数や検索回数、予算など、待ち時間以外の上限設定は次の記事で整理しています。

Claude CodeClaude Code無人運用｜暴走を防ぐ上限設定まとめ

よくある質問

対話型のセッションでも CLAUDE_CODE_RETRY_WATCHDOG を使うべきですか

公式ドキュメントは、評価用のハーネスやCIのジョブなど、人が見ていない実行を想定した設定として説明しています。公式のエラー解説（Usage limits の節）によると、claude.ai のサブスクリプションでログインした対話型のセッションには、使用上限の解除を待って作業を自動で続ける別の仕組み（/config の「Continue automatically at usage limit」）があり、同じ節に「v2.1.234より前はこの待ちを提供していなかった」と書かれています。対話型ではそちらを使い、再試行モードは無人のジョブだけにかけるのが素直です。

CLAUDE_CODE_MAX_RETRIES を増やすだけではだめですか

再試行モードを使わない場合、CLAUDE_CODE_MAX_RETRIES は2.1.186から15で頭打ちです。既定の10回でも、指数的に間隔を伸ばしながら再試行するとはいえ、待てる時間は限られます。私たちの7月30日の529は、既定の回数では足りずに失敗しました。長く待たせたいなら、再試行モードを使ったうえで待ち時間に上限を付けるほうが、意図どおりに動きます。

使用上限の待ちを縛る設定の既定値はいくつですか

2026年10月16日時点で、更新履歴にも公式ドキュメントにも既定値は書かれていません。設定しない場合にどこまで待つかは確認できていないので、無人で回すなら明示的に値を入れておくことをおすすめします。

待っている間も使用量や料金はかかりますか

待っている間はリクエストを送っていないので、そのぶんのトークンは発生しないと考えられます。ただし、公式ドキュメントにこの点を明記した記述は見当たりませんでした。また、APIキーで使っていて429が出ている場合は、自分のキーのレート制限に当たっている可能性があります。公式のエラー解説は、同時実行数を減らす・小さいモデルに切り替えるといった対処を案内しています。

Fallback Models と何が違いますか

Fallback Models は、下の記事で解説しているとおり、指定したモデルが混雑しているときに別のモデルへ切り替える設定です。再試行モードは、同じモデルのまま待つ設定です。成果物の品質をモデルで揃えたい無人ジョブなら待つ、止まらないことを優先するなら切り替える、という選び方になります。

Claude CodeClaude「モデルが混雑しています」の対処法｜Fallback Modelsで止めない設定

まとめ

• CLAUDE_CODE_RETRY_WATCHDOG は、無人実行で429・529と使用上限を、回数の上限なしで待つ再試行モード。支出上限・クレジット切れは待たない（2.1.239以降）
• 2.1.295で混雑の待ち時間の上限（…_MAX_WAIT_MS）、2.1.301（2026年10月15日公開）で使用上限の待ち時間の上限（…_MAX_USAGE_LIMIT_WAIT_MS）が加わった。後者は10月16日時点で公式ドキュメント未掲載・既定値の記載なし
• 待ち時間の上限は、次の処理が動くまでの猶予から、ジョブ自体の所要時間を引いて逆算する。2つの待ちを足しても猶予に収まる値にしておく
• サーバーエラー・切断は既定300回（およそ3時間）まで再試行されるので、必要なら CLAUDE_CODE_MAX_RETRIES も明示する
• stable チャネル（10月16日時点で2.1.292）には2つの上限がまだ入っていない。版を確かめてから設定する
• 上限で終わったときに気づけるよう、終了コードと結果の文面で通知を分ける。私たちの約1,090回の実行では、Claude Code側の失敗4回がすべて再試行モードの対象になる種類だった

無人で回すClaude Codeは、動かし始めるより「止まったときにどうなるか」を決めるほうに手間がかかります。株式会社Fyveでは、こうした運用の決め事を自社のジョブで確かめながら、Claude Codeを業務に入れる会社の環境づくりもお手伝いしています。

参考にした情報源

• Claude Code CHANGELOG（2.1.186・2.1.199・2.1.239・2.1.281・2.1.288・2.1.295・2.1.301）
• Claude Code Docs：Environment variables
• Claude Code Docs：Errors（Automatic retries・Usage limits）
• Claude Code Docs：Run Claude Code programmatically（終了コード・api_retry イベント）
• Claude Code Docs：Settings reference（env）
• npm：@anthropic-ai/claude-code（公開時刻・配布チャネル）

※2026年10月16日時点の情報です。環境変数の名前や既定値は版によって変わることがあるため、最新の公式ドキュメントと更新履歴で確認してください。