Claude Codeの使用量上限を再確認する間隔をRECHECK_MSで決める

CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MSは、CLAUDE_CODE_RETRY_WATCHDOGを設定した無人セッションが使用量上限のリセットを待っているあいだに、上限がすでに解除されていないかを見に行く間隔を決める環境変数です。Claude Code v2.1.305で加わりました。

解除が確認できた時点で、待っていたリクエストはすぐ送られます。設定しなければ確認は行われず、従来どおりリセットまで待ちます。

何を再確認し、何が変わるのか

CLAUDE_CODE_RETRY_WATCHDOG=1のセッションは、429と529の容量エラーを再試行し続けます。サブスクリプションの上限に当たった場合は、レスポンスにリセット時刻があればそこまで待ちます。環境変数の説明にも、使用量上限に当たったセッションは残りのウィンドウを待つと書かれています。

待っているあいだに上限が先に解除される場面があります。変更履歴の説明は、この変数で無人のリトライモードが「リセットの前に解除された使用量上限」に気づけるようになる、というものです。

説明文の言葉は「最小間隔」です。設定した値ごとにきっかり確認する約束ではなく、その間隔より短くは確認しない下限と読めます。実際に何分ごとに確認が走るかまでは書かれていません。

確認が行われる条件と、行われない条件

この変数には、効く場面がかなり絞られています。環境変数のページによると、確認は次の条件がそろったときだけです。

• 待っているのが、claude.aiサブスクリプションのセッション上限または週次上限である
• 使用クレジット(usage credits)を使っていない
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICが設定されていない

逆に言えば、次の構成では値を入れても何も起きません。

「設定したのに効いていない」ときは、まずこの3条件を疑います。値の書き間違いと並んで、最も多い原因になるはずです。

値の範囲を外すとどうなるか

範囲は60000から10800000で、書き方は「プレーンな数字の整数」と指定されています。範囲の外では確認が行われません。エラーで起動が止まるのか、黙って無視されるのかは、環境変数のページに書かれていません。

つまり、次のような書き方はどれも「確認なし」と同じ結果になる可能性があります。

換算で迷うときは、分に60000を掛けます。

間隔はどう決めるか

最短が1分、最長が3時間なので、選ぶのは「解除を早く拾いたいか」と「確認の回数を抑えたいか」のバランスです。リセット時刻はYou've hit your session limit · resets 3:45pmのようにエラーに出ますが、解除がその前に起きる場合に備えるのがこの変数の目的です。

考え方の軸を3つ挙げます。

1. 待ち時間が短いと見込めるとき: 短い値にする。リセットまで30分なら、3時間の間隔は一度も確認しないまま終わる値に近い
2. 待ち時間が長いとき(週次上限など): 数十分から1時間程度にする。1分刻みで確認する意味は薄い
3. 同じ組織の複数ジョブが同時に待っているとき: 全ジョブが最短間隔にそろえる必要はない。用途ごとに値を変えてよい

ここで挙げた例は目安で、公式が推奨する値ではありません。公式は範囲だけを定めていて、推奨値を示していません。

一つ注意があります。説明文は「最小間隔」としか書かないため、待ち始めてから最初の確認がいつ走るかは分かりません。値が待ち時間より長いと、確認の機会がそもそも少なくなるはずです。初回の確認のタイミングが仕様に書かれていない以上、待ち時間の見込みより長い値は避けるのが安全です。

セッション上限と週次上限で、待ち方の事情が違う

エラーに出るリセット時刻は、上限の種類で距離感が大きく変わります。

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

セッション上限は同じ日のうちに戻ることが多く、週次上限は曜日をまたぎます。使用量はセッション枠と週次枠の両方に同時に数えられるため、大きなワークフローの一斉実行は、セッション枠が戻る前に週次枠を使い切ることがあります。

この違いが、間隔の決め方に響きます。週次上限で何十時間も待つジョブでは、1分刻みの確認に意味は薄く、10分から1時間程度の間隔で十分です。セッション上限で数十分の待ちが見込まれるジョブでは、短めの値のほうが解除を拾える機会が増えます。どちらの上限に当たったかは、無人実行のログに残るエラー文から読み取れます。

ジョブへの置き方

GitHub Actionsなら、ジョブのenvにwatchdogと再確認の間隔を並べます。

jobs:
  nightly-review:
    runs-on: ubuntu-latest
    timeout-minutes: 240
    env:
      CLAUDE_CODE_RETRY_WATCHDOG: "1"
      CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS: "600000"
    steps:
      - uses: actions/checkout@v4
      - run: claude -p "未完了のタスクを続けて"

この構成は、使用量上限で待つときに10分以上の間隔で解除を確認します。外側のtimeout-minutesは、待ち続けるジョブを止める保険です。連携の全体像はGitHub Actionsへの組み込み、claude -pの使い方は非対話モードの解説にあります。

シェルから起動するならexportで足ります。

export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=600000
claude -p "未完了のタスクを続けて"

環境変数は設定ファイルのenvキーにも書けます。プロジェクトの.claude/settings.jsonに置くと、チームの全員に同じ値が適用されます。

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1",
    "CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS": "600000"
  }
}

設定ファイルの値はシェルを通らず、書いたとおりに環境へ入ります。数字は文字列として"600000"の形で書きます。ただしwatchdogは無人実行向けの設定です。チーム共有の設定ファイルに入れると、人が使う対話セッションにもCLAUDE_CODE_RETRY_WATCHDOGが及ぶので、CIのジョブ側のenvに置くほうが範囲を絞れます。

打ち切りの変数とは役割が逆

同じwatchdogには、待つ時間を切る変数があります。CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MSは429と529を待つ時間にリクエスト単位の上限を置く変数で、決め方はMAX_WAIT_MSの記事にあります。使用量上限の待ちを切る変数は使用量上限待ちの打ち切り設定で扱っています。

整理すると、向きが違います。

再確認は待つ長さを変えません。リセットが先にあるまま、解除済みなら前倒しで再開するだけです。そのため、待ちの総量を抑えたいなら打ち切り側の変数と組み合わせます。再確認だけでは、解除が起きない場合の待ち時間は従来と同じです。

対話セッションの自動再開とは別の仕組み

対話セッションでは、claude.aiのサブスクリプションで上限に当たると、開いたままのセッションがリセット後に続きを自動で再開します(v2.1.234以降)。画面にはUsage limit reached · limit resets 3:45pmのように、リセット時刻と再開の予定が出ます。

こちらは人が画面の前にいる場合の機能で、watchdogの変数とは別物です。取り消しはescで行え、/configの「Continue automatically at usage limit」で切れます。詳しい操作は上限リセット後の自動再開にあります。無人のジョブで解除を拾いたいときだけ、この記事の変数を使います。

なお、上限の種類の見分け方は利用上限のメッセージ別の対処に整理しています。セッション上限と週次上限は全モデル共通で、モデルを替えても戻りません。Opus上限とSonnet上限は該当モデル系統だけが対象です。この変数の確認対象に含まれると明記されているのは、セッション上限と週次上限です。

設定が届いているかを確かめる

再確認が走ったかどうかは、普段は見えません。設定の確認は、環境変数がclaudeのプロセスまで届いているかを見るのが最初の一歩です。

env | grep CLAUDE_CODE_RETRY_WATCHDOG

ジョブの先頭にこの1行を置いておくと、ログに値が残ります。出力にCLAUDE_CODE_RETRY_WATCHDOG=1と..._USAGE_LIMIT_RECHECK_MS=600000の2行が並んでいれば、少なくとも値は渡っています。そのうえで、前節の3条件を満たす構成かを見ます。

使用量上限に実際に当てて確かめるのは現実的ではありません。どの段階で確認が働いたかを知る手段として、公式の説明に挙げられているものはありません。運用では、待ったあとのジョブの所要時間をログで見て、想定より早く再開したかを後から確かめる形になります。

よくあるつまずき

• 秒で書く: 600と書くと、範囲外の値として確認が行われない。末尾の_MSに合わせて桁を数える
• 値だけ設定してCLAUDE_CODE_RETRY_WATCHDOGを忘れる: この変数はwatchdogを設定しているときの動作を決めるもので、単独では意味を持たない
• APIキーのジョブに入れる: 確認の対象はサブスクリプションの上限だけなので効かない
• 使用クレジットを有効にしている: クレジットを使っている間は確認されない
• 非必須通信を止めたランナーで期待する: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICがあると確認は止まる

この変数のバージョンの背景は、v2.1.305のリリースノートにあります。環境変数全般の探し方と効かないときの切り分けは、環境変数リファレンスが受け持ちます。