CLAUDE_CODE_WEBFETCH_DEADLINE_MSでWebFetchのダウンロード待機時間を変える

CLAUDE_CODE_WEBFETCH_DEADLINE_MSは、WebFetchがページのダウンロードを待つ時間の上限をミリ秒単位で変更する環境変数です。既定値は300000(5分)で、リダイレクトを含めたダウンロードがこの時間内に終わらないと、WebFetchはdeadlineエラーで失敗します。大きなPDFや応答の遅いサーバーをcurl代わりにWebFetchで取りに行くとき、5分の壁に当たって毎回同じ失敗を繰り返すケースがあります。設定できる値の範囲、既定タイムアウトとの違い、0を指定したときの挙動までをまとめます。

CLAUDE_CODE_WEBFETCH_DEADLINE_MSが変えるもの

この環境変数が対象にするのは、WebFetchが1回のページ取得にかけられる時間の上限です。取得先のサーバーへの接続からダウンロードが完了するまでの全体を対象にしており、途中で発生するリダイレクトを経由する待ち時間も含まれます。ダウンロードがこの上限に達すると完了を待たずに失敗が確定し、Claudeにはdeadlineエラーが返ります。

既定値は300000ミリ秒、つまり5分です。この変数はClaude Code v2.1.268以降でしか読み込まれず、それより古いバージョンでは設定しても無視されます。手元のバージョンが対象かどうかはclaude --versionで確認できます。指定できるのは素の数字だけで、小数やその他の書き方を渡した場合は既定値の5分のまま動作します。単位を書き添えた"300000ms"のような値も、素の数字だけという条件から外れるため既定値の5分にフォールバックします。

既定の5分は何を基準にした値か

Claude CodeのWebFetchツールの挙動を定めた公式ドキュメントは、この5分の上限を「ダウンロードが完了しないまま5分が経過すると、リダイレクトを含めてdeadlineエラーで失敗する」と説明しています。ここでいうダウンロードは、WebFetchがページを取得してMarkdownへ変換し内容を抽出するまでの一連の処理のうち、取得(ダウンロード)の段階を指します。

WebFetch全体の処理は取得・変換・抽出の3段階に分かれ、Claude Code WebFetchのキャッシュとタイムアウトで扱ったキャッシュTTL(既定15分)は取得済みの応答をどれだけ保持するかを決める別の設定です。CLAUDE_CODE_WEBFETCH_DEADLINE_MSはキャッシュとは無関係で、取得そのものが時間内に終わるかどうかだけを見ています。2つの変数を混同すると、キャッシュを短くしても遅いページの失敗が直らない、という切り分けミスが起きます。

他のタイムアウト系環境変数との違い

Claude Codeにはタイムアウトを扱う環境変数が複数あり、対象がそれぞれ異なります。

curlをBashツールから直接呼んでいる場合、BASH_DEFAULT_TIMEOUT_MS(または上限を決めるBASH_MAX_TIMEOUT_MS、既定600000ms=10分)の対象で、CLAUDE_CODE_WEBFETCH_DEADLINE_MSは関係しません。BASH_MAX_TIMEOUT_MSはモデルが1コマンドに指定できるタイムアウトの上限で、実際に効く上限はBASH_DEFAULT_TIMEOUT_MSとどちらか大きいほうです。両者は同じ「遅い取得で失敗する」症状を起こしますが、経路がWebFetchツールかBash経由のコマンドかで変えるべき変数が変わります。BASH_DEFAULT_TIMEOUT_MSの詳細はBASH_DEFAULT_TIMEOUT_MSでBashコマンドのタイムアウトを変更するにまとめています。

WebFetch内部の抽出処理(取得したページをモデルに要約させる段階)はAnthropic APIへのリクエストの一種ですが、CLAUDE_CODE_WEBFETCH_DEADLINE_MSが対象にしているのはあくまでダウンロード段階です。抽出処理側のタイムアウトについて、公式ドキュメントはWebFetch固有の挙動として明記していません。

設定方法

シェルで一時的に設定する場合は、claudeを起動する前に環境変数をexportします。

export CLAUDE_CODE_WEBFETCH_DEADLINE_MS="600000"
claude

毎回のセッションに適用したい場合は、settings.jsonのenvブロックに書きます。

cat ~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_WEBFETCH_DEADLINE_MS": "600000"
  }
}

どのファイルに書くかで適用範囲が変わります。~/.claude/settings.jsonは自分の全プロジェクトに、.claude/settings.jsonはプロジェクトの全員に、.claude/settings.local.jsonはそのプロジェクトの自分だけに適用されます。公式ドキュメントによると、envブロックの値の多くは保存時に実行中のセッションへも反映されますが、CLAUDE_CODE_WEBFETCH_DEADLINE_MSはモデル選択・タイムアウト・上限のような「安全な変数」に分類され、この分類の変数は各設定ファイルから起動時にまとめて読み込まれる方式です。CLAUDE_CODE_WEBFETCH_CACHE_TTL_MSと同様、設定を変えたらclaudeを再起動してから試します。

シェルとsettings.jsonの両方で同じ変数を設定した場合は、settings.json側の値が優先されます。シェルの環境変数はプロセス起動時に読み込まれる一方、envブロックの値はそれを上書きしてプロセス環境に書き込まれるためです。設定を打ち消したいときは値を空文字列にする方法が一般に使えますが、CLAUDE_CODE_WEBFETCH_DEADLINE_MSは空文字列も「素の数字」ではないため既定値の5分に戻るだけで、変数そのものが未設定の状態にはなりません。

上限を伸ばす前に確認すること

deadlineエラーが出たときにまずCLAUDE_CODE_WEBFETCH_DEADLINE_MSを伸ばす前に、そもそも取得先が応答しているかを切り分けます。

• 同じURLをcurl -vで直接取得してみて、5分以内に完了するかを確認する。それでも終わらないなら、上限を伸ばしてもいずれ同じ失敗に当たるだけです
• クロスホストのリダイレクトが挟まっていないかを確認する。WebFetchはホストをまたぐリダイレクトを自動でたどらず、その場合は2回目のWebFetch呼び出しが必要になるため、1回のダウンロード時間として計測すべき区間が想定と違っていることがあります
• 対象が巨大なファイル(大きなPDFやアーカイブ)かどうかを確認する。長大なページは切り詰め処理の対象になりますが、切り詰めが起きるのは取得が完了したあとの処理段階で、ダウンロード自体が終わらない場合の対処にはなりません
• 社内ネットワークのプロキシやゲートウェイが長時間の接続を途中で切っていないかを確認する。プロキシが接続を保持したまま応答を返さない場合、CLAUDE_CODE_WEBFETCH_DEADLINE_MSをいくら伸ばしても、プロキシ側のタイムアウトのほうが先に効いて同じ失敗になります

0を指定して上限を無効化する運用は、応答が来ることが分かっている遅いサーバーに限定するのが無難です。応答が返らない相手に対して無制限で待たせると、WebFetch呼び出しがハングしたように見える状態が続きます。チーム内で設定しても効かないという報告があった場合は、まず報告者のclaude --versionがv2.1.268以降かを確認します。古いバージョンでは値がまるごと無視され、5分の上限がそのまま働くため、上限そのものの見直しより先にアップデートを促すほうが早く解決します。

.claude/settings.jsonでチームの既定値をそろえる

Claude Codeはenvブロックの変数を「モデル選択・タイムアウトや上限・機能の切り替えのような、安全に分類される変数」と「チェックアウトしたリポジトリ側が触るべきでない変数」に分けて扱います。後者(CLAUDE_CONFIG_DIRやOpenTelemetryのエクスポーター設定など)はプロジェクト設定・ローカル設定からは無視されますが、CLAUDE_CODE_WEBFETCH_DEADLINE_MSはこの無視リストに含まれず、タイムアウト系の変数として起動時にすべての設定ファイルから読み込まれます。つまり.claude/settings.jsonにコミットして、チームのデフォルト値をリポジトリ側でそろえられます。ただし優先順位の高い.claude/settings.local.jsonを各自が書けば個別に上書きできるので、強制力を持つ設定ではありません(~/.claude/settings.jsonは逆に.claude/settings.jsonより優先順位が低く、これで上書きすることはできません)。個人だけの一時的な変更なら.claude/settings.local.json、自分の全プロジェクトに適用したいなら~/.claude/settings.jsonを使い分けます。

よくある質問

deadlineエラーになったWebFetch呼び出しは自動でリトライされますか

公式ドキュメントは、抽出処理がAPIの過負荷(overloaded)に当たった場合はバックオフを挟んで自動リトライすると明記していますが、ダウンロードのdeadlineエラー自体を自動でリトライするとは書かれていません。5分(または設定した上限)で失敗した場合、同じURLを再度WebFetchで取得し直すかどうかはClaudeの判断に委ねられます。

Cowork上のweb_fetchにも同じ上限が効きますか

Claude Desktop上のCoworkセッションでは、組み込みのWebFetchツールではなくmcp__workspace__web_fetchという別のツールが使われます。CLAUDE_CODE_WEBFETCH_DEADLINE_MSはClaude CodeのWebFetchツールに対する変数として文書化されており、Cowork側のweb_fetchが同じ実装・同じ上限を共有しているかは公式ドキュメントに明記されていません。

まとめ

CLAUDE_CODE_WEBFETCH_DEADLINE_MSは、WebFetchのダウンロード(リダイレクト込み)が完了するまでの待機時間の上限を変える環境変数で、既定は5分、0で無制限にできます。Claude Code v2.1.268以降が対象で、指定できるのは素の数字だけです。同じ「WebFetchが遅い・失敗する」症状でも、対象がキャッシュなのかダウンロードの上限なのかで直すべき設定は変わるため、Claude Code WebFetchのキャッシュとタイムアウトと本記事を切り分けて確認すると原因を特定しやすくなります。環境変数全体を見渡したい場合はClaude Code環境変数リファレンスも参照してください。