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

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

WebFetchが5分で失敗する原因になる待機時間の上限を、CLAUDE_CODE_WEBFETCH_DEADLINE_MSで変更する方法と挙動をまとめます。

読了目安 約9分

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

CLAUDE_CODE_WEBFETCH_DEADLINE_MSが変えるもの

対象は、WebFetchが1回のページ取得にかけられる時間の上限です。ダウンロードの待機全体が数えられ、リダイレクトの待ち時間も含まれます。上限に達すると完了を待たずに失敗が確定し、Claudeにはdeadlineエラーが返ります。

指定できるのは素の数字だけです。小数や"300000ms"のような単位つきの値、空文字列は、どれも既定値の5分のまま動作します。

v2.1.268の前後でWebFetchの待ち方はどう変わったか

changelogには、応答を開いたまま終わらないサーバーでWebFetchが固まり続ける問題を直し、300秒で失敗するようにしたとあります。設定したのに効かないときは、まずclaude --versionでv2.1.268以降かを見ます。それより古いバージョンでは、この変数は読み込まれません。

あゆみ

WebFetch周りの変数が入ったバージョン

  1. v2.1.233(2026年8月14日)キャッシュ保持時間を変える変数を追加

    CLAUDE_CODE_WEBFETCH_CACHE_TTL_MSで、取得済みの応答を覚えておく時間(既定15分)を変えられるようになりました。

  2. v2.1.268(2026年9月10日)300秒の期限と変更用の変数を追加

    CLAUDE_CODE_WEBFETCH_DEADLINE_MSで上限を変えられるようになりました。同じバージョンで、localhostのようなドットのないホスト名へのエラーも、汎用のInvalid URLから理由を書いたメッセージに変わっています。

  3. v2.1.285WebFetchそのものを止める変数を追加

    CLAUDE_CODE_DISABLE_WEB_FETCH=1でWebFetchを無効にできます。WebSearchは使えるままです。

キャッシュが決めるのは、ダウンロードが終わったあとの応答の保持です。詳しくはClaude Code WebFetchのキャッシュとタイムアウトにあります。CLAUDE_CODE_WEBFETCH_DEADLINE_MSが見るのは、取得そのものが時間内に終わるかどうかだけです。キャッシュを短くしても、遅いページの失敗は直りません。

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

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

変数対象既定値
CLAUDE_CODE_WEBFETCH_DEADLINE_MS対象WebFetchのダウンロード待機時間の上限(リダイレクト込み)既定値300000ms(5分)
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS対象WebFetchの応答キャッシュの保持時間既定値900000ms(15分)
BASH_DEFAULT_TIMEOUT_MS対象Bashツールが実行する1コマンドの既定タイムアウト既定値120000ms(2分)
API_TIMEOUT_MS対象Anthropic APIへのリクエスト全般のタイムアウト既定値600000ms(10分)

curlをBashツールから呼んでいる場合は、BASH_DEFAULT_TIMEOUT_MSとBASH_MAX_TIMEOUT_MSの対象です。WebFetchの変数は関係しません。BASH_MAX_TIMEOUT_MSの既定は600000ms(10分)で、モデルが1コマンドに指定できる上限で、実際に効く天井はBASH_DEFAULT_TIMEOUT_MSとの大きいほうです。

どちらも「遅い取得で失敗する」症状を起こしますが、経路がWebFetchかBash経由かで変える変数が変わります。Bash側はBASH_DEFAULT_TIMEOUT_MSでBashコマンドのタイムアウトを変更するにまとめています。

WebFetchの内部では、取得したページをモデルに要約させる抽出の段階がAPIリクエストになります。CLAUDE_CODE_WEBFETCH_DEADLINE_MSが数えるのはダウンロード段階だけで、抽出段階のタイムアウトは、tools-referenceのWebFetchの節に載っていません。

deadlineエラーと見分けたいWebFetchの失敗

WebFetchが何も返さないとき、原因が待ち時間とは限りません。エラー文言で系統を分けると、触る設定が決まります。

まとめ

WebFetchの失敗は文言で見分ける

  • deadlineエラー

    直すのはCLAUDE_CODE_WEBFETCH_DEADLINE_MSです。

  • WebFetch cannot fetch localhost or other hostnames without a dot

    URLのホスト名にドットがないと、WebFetchは通信を始める前に断ります。社内のhttp://wiki/も対象で、エラーはBashのcurlを使うようClaudeに伝えます。待ち時間の設定を変えても変わりません。

  • The safety check for domain ... is rate-limited

    取得の前に、WebFetchはホスト名をapi.anthropic.comへ送ってドメインの安全性を調べます。この検査が完了しない失敗で、メッセージは繰り返しのリトライや待機をしないようClaudeに指示します。api.anthropic.comへ出られない環境では、settingsのskipWebFetchPreflight: trueで検査を省けます。

  • 別ホストへのリダイレクト

    ホストをまたぐリダイレクトは自動では追わず、元のURLと転送先を書いたテキストが返ります。Claudeが2回目のWebFetchで転送先を取りに行くので、deadlineの原因ではありません。

安全性検査の失敗には2種類あります。rate-limitedは、検査先がHTTP 429を返した場合です。同じネットワークからの検査が多すぎると起き、数分続くことがあります。もう一方のUnable to verifyは、検査の通信が失敗したか、時間切れか、別のエラーステータスが返った場合です。

失敗した検査はキャッシュされないので、同じドメインを次に取りに行くと検査がもう一度走ります。rate-limitedのメッセージは、ループで再試行したり待機したりせず、そのページなしで作業を続けるようClaudeに指示します。

抽出の段階でAPIが過負荷だった場合は、バックオフを挟んで自動でリトライされ、それでも失敗するとエラー結果が返ります。ダウンロードのdeadlineエラーに自動リトライがあるとは、tools-referenceのWebFetchの節に書かれていません。

値の目安と、WebFetchで取りに行かない選択

指定する値はミリ秒なので、分に直して決めます。

待たせたい時間指定する値
5分(既定)指定する値300000
10分指定する値600000
30分指定する値1800000
無制限指定する値0

WebFetchは、HTMLをMarkdownに変換し、抽出用のプロンプトに沿った結果だけをClaudeへ渡す作りです。tools-referenceは、この仕組みを情報が落ちるものと位置づけています。加工前のページがほしいときの手段として挙げているのは、Bashからのcurlです。

巨大なファイルをそのまま取りたいなら、待ち時間を伸ばしてWebFetchに任せるより、curlで手元に保存するほうが筋に合います。curlの待ち時間は、WebFetchの変数ではなくBashツール側のタイムアウトで決まります。

名前の似たエラーにも注意します。Download timed out: exceeded the total deadlineは、Claude Code本体の更新ダウンロードが10分で失敗したときの文言です。WebFetchとは別の経路で、この変数では変わりません。こちらはタイムアウトしてもClaude Codeが再試行しない仕様です。接続が遅すぎて期限内に終わらない回線は、すぐに再試行しても終わらないためです。

設定方法

シェルで一時的に設定するなら、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はそのプロジェクトの自分だけです。環境変数の全体像はClaude Code環境変数リファレンスにあります。

envブロックの値を書き換えても、実行中のセッションに反映されないことがあります。そのときはclaudeを再起動してから試します。

シェルとsettings.jsonの両方で設定した場合は、settings.jsonの値がシェルのexportを上書きします。例外はClaude Desktopアプリや自己ホスト型環境のrunnerから起動したセッションです。こちらは起動環境が先に変数を持っていると、envの値は無視されます。

上限を伸ばす前の切り分け

deadlineエラーが出たら、伸ばす前に、取得先が応答しているかを見ます。

手順

deadlineエラーが出たときの順番

  1. 1

    curlで同じURLを取る

    Bashツールを通さず、手元のシェルで同じURLの所要時間を測ります。

  2. 2

    経路の途中を疑う

    社内プロキシやゲートウェイが長い接続を途中で切っていないかを見ます。プロキシが先に切るなら、この変数を伸ばしても同じ失敗になります。

  3. 3

    待たせる前提を決める

    応答が来ると分かっている相手だけ、値を伸ばすか0にします。

1つ目の手順では、次のように所要時間とステータスだけを出します。5分を超えても終わらないなら、WebFetchの上限を伸ばしてもいずれ同じ失敗に当たります。

curl -sS -o /dev/null -w 'status=%{http_code} time=%{time_total}s\n' "https://example.com/large.pdf"

巨大なファイルでは、長いページの切り詰めが効く場面もあります。ただし切り詰めは取得が終わったあとの処理で、ダウンロード自体が終わらない場合の対策にはなりません。

.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より優先順位が低く、これで上書きすることはできません。

まとめ

待ち時間を伸ばして直るのは、エラー文言がdeadlineのときだけです。それ以外の文言では、この変数を触っても結果は変わりません。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →