Claude Code WebFetchのキャッシュとタイムアウト — 15分の既定TTLと5分のダウンロード上限

WebFetchが数分前に更新したはずのページを古いまま返す、あるいは特定のURLだけ失敗する。原因を探って「タイムアウト値を伸ばせばいいのでは」と考えがちですが、効くのはキャッシュの寿命、変換と抽出での情報欠落、リダイレクト、ダウンロード上限、取得前のドメイン判定のどれかです。v2.1.267以前には、ダウンロード上限を変える環境変数もありませんでした。

症状ごとにどこを見るかを先に決めておけば、設定をいじる前に原因を絞れます。

時間に関わる設定は3種類だけ

WebFetchの時間に関わる値は、寿命と上限の性格が違います。

数字が似ていても、キャッシュは取得結果、上限は1回のダウンロード、判定の保持は許可の可否にそれぞれ効きます。

数分前の更新が反映されない — キャッシュは既定15分

WebFetchは同じURLへの応答を既定で15分間キャッシュします。ページ側を更新した直後に確認しても、有効期限内なら更新前の内容が返り続けます。古い情報が返る原因のうち、まず疑うのがこれです。

Claude Code v2.1.233以降は、環境変数CLAUDE_CODE_WEBFETCH_CACHE_TTL_MSでミリ秒単位に変更できます。既定値は900000です。指定できるのは素の数字だけで、0・小数・その他の書き方は既定値のままになります。0で無効にはできず、短くする方向でしか回避できません。

一時的に1分へ縮めるなら、起動時に渡します。

CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=60000 claude

常用するならsettings.jsonのenvにも書けます。

{
  "env": {
    "CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS": "60000"
  }
}

「書かれていない」と返る — 変換と抽出で情報が落ちる

WebFetchはURLと「何を抽出したいか」のプロンプトを受け取り、取得、Markdown変換、抽出の順に処理します。サーバーがHTMLを返した場合はMarkdownへ変換し、ほとんどの取得ではその内容に対してプロンプトを別のモデル呼び出しで実行します。Claude Codeが受け取るのは元のページではなく、その結果です。変換ステップは設定で変えられません。

つまりWebFetchは設計上、情報が欠落します。「このページには◯◯の記載がない」と返ってきても、抽出プロンプトがそれを尋ねていなかっただけの場合があります。具体的なプロンプトで取得し直すか、Bash経由のcurlで生のページを取ります。

取得リクエストにはClaude-Userで始まるUser-Agentと、HTMLよりMarkdownを優先するAcceptヘッダーが付きます。Markdownを直接返せるサーバーなら、HTMLからの変換を経ずに済みます。

大きなページは、処理に入る前に固定の文字数で切り詰められます。長いドキュメントの一部しか反映されないときは、ページを分けて取得するか、該当箇所のURLを直接指定します。

途中で失敗する — ダウンロード上限・リダイレクト・過負荷

ダウンロードが5分以内に終わらないページは、deadlineエラーで失敗します。リダイレクトをたどる時間も含みます。v2.1.268以降はCLAUDE_CODE_WEBFETCH_DEADLINE_MSで変更でき、0にすると上限が外れます。素の数字だけが有効で、小数などは既定の5分のままです。設定方法はCLAUDE_CODE_WEBFETCH_DEADLINE_MSでWebFetchのダウンロード待機時間を変えるにまとめています。

別ホストへのリダイレクトは、WebFetchが自動ではたどりません。元のURLとリダイレクト先を書いたテキストを結果として返し、Claudeがそのリダイレクト先に2回目のWebFetchを発行します。ホストをまたぐ1回の呼び出しでは完結しません。

抽出リクエストがAPIの過負荷に当たると、バックオフを挟んで自動でリトライします。それでも失敗すればエラー結果が返ります。v2.1.212より前は、APIのエラーテキストがページの内容として渡る不具合がありました。v2.1.212より前のバージョンで文脈と噛み合わない結果が返るなら、まずここを疑います。

取得前に止まる — ドメイン安全性チェックと組織ポリシー

許可・拒否ルールとは別に、WebFetchは取得の前に必ずドメイン安全性チェックを通ります。ホスト名だけをapi.anthropic.comへ送り、Anthropicが管理するブロックリストと照合する仕組みで、パスやページ内容は送りません。通過したホスト名は5分間キャッシュされ、ブロックされた・失敗したホスト名は次のリクエストで再判定されます。

このチェックはモデルプロバイダーを問わず実行され、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICでも止まりません。社内ネットワークがapi.anthropic.comを遮断していると、許可ルールに関係なく取得前に失敗します。対処はapi.anthropic.comの許可、またはsettings.jsonのskipWebFetchPreflightをtrueにすることです。ただし無効化するとブロックリストを参照せずに取得するので、ドメイン単位の許可ルールと併用して取得先を絞ります。

チェックが完了しないときは、ツール結果に次の2種類の文言が入ります。

失敗したチェックはキャッシュされないので、後続の取得では再度判定されます。v2.1.285より前は、rate-limitedもUnable to verifyとして報告されていました。v2.1.286より前のrate-limited文言は、約1分後の再試行を促す別の文面でした。

ホスト名にドットが無いURLは、リクエスト前に拒否されます。

WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.

http://localhost:3000やhttp://wiki/のような社内の短い名前が対象で、メッセージがcurlを使うよう指示するため、通常は対処不要です。v2.1.268より前は、同じURLに汎用のInvalid URLが返っていました。

もう1つ、Team・Enterpriseのclaude.aiアカウントでLLMゲートウェイを経由せずに使う場合、WebFetchは組織のポリシーに依存します。ポリシーは起動時にapi.anthropic.comから取得され、読み込めない間はClaude CodeがWebFetchを出さずに待ちます。セッション内で/statusを実行し、Organization policyの行がポリシー未読み込みを示していれば原因はここです。セッション外ではclaude doctorが同じ行を出します。読み込みに成功すれば、再起動なしでツールが戻ります。

権限プロンプトの出方と、サンドボックスとの関係

ManualとacceptEditsの権限モードでは、WebFetchは取得前に確認を求めます。すでに許可・拒否ルールがあるドメインと、組み込みで事前承認された公式ドキュメント系のドメインは確認なしです。ただし明示的なWebFetch(domain:...)ルールは事前承認より優先されるため、事前承認ドメインを止めることもできます。

確認の選択肢は3つです。「Yes」はその1回だけを許可し、次のWebFetchでまた確認が出ます。「Yes, and don't ask again for <domain>」は、そのドメインのWebFetch(domain:...)許可ルールをリポジトリの.claude/settings.local.jsonに保存します。「No」は取得を拒否します。allowManagedPermissionRulesOnlyを組織が設定していると、この2つ目の選択肢は表示されません。autoとbypassPermissionsは確認を省きますが、明示的なaskルールに一致するドメインでは確認が残ります。

サンドボックスとの関係は一方通行です。サンドボックス内のコマンドは、WebFetchの事前承認ドメインを引き継ぎません。サンドボックスのネットワーク許可リストにドメインを足しても、WebFetchの確認は止まりません。WebFetchはサンドボックスの許可リストを読まないためです。逆に、WebFetch(domain:...)の許可ルールはサンドボックス側にも効きます。ドメイン許可の書き方全体はClaude Codeのサンドボックス設計にあります。

WebFetchを止める・出さない

v2.1.285以降は、環境変数CLAUDE_CODE_DISABLE_WEB_FETCHを1にするとWebFetchが無効になります。WebSearchは残ります。検索側の挙動はClaude Web検索の使い方にまとめています。

CLI側にも手段があります。以下の挙動はclaude --versionで自分のバージョンを確かめてから照らし合わせてください(下はv2.1.287の出力例です)。v2.1.287のclaude --helpでは、--disallowedToolsが「拒否するツール名のカンマまたはスペース区切りの一覧」として載っており、WebFetchを渡せば拒否できます。--restrictedは、コマンドやコードを実行する組み込みツールとWebFetchを取り除き、ユーザー・プロジェクト・ローカルの設定ファイルも無視するモードです。--toolsで名前を挙げた場合だけWebFetchが残ります。

claude --version
# 2.1.287 (Claude Code)

症状から原因を切り分ける

上から順に当てはめると、設定を触る前に切り分けが済みます。

バージョンごとの変化

WebFetch周りの変更は複数のバージョンに散らばっています。

Claude Desktop上のCoworkセッションでは、組み込みのWebFetchでなくmcp__workspace__web_fetchが使われます。WebFetch全体へのdenyルールはこちらにも適用されます。本稿のキャッシュと変換の話は、Claude CodeのWebFetchツールについてのものです。

まとめ

古い、欠ける、失敗する、そもそも出ない。この4つは原因の層が別で、直す設定も別です。環境変数全体はClaude Code環境変数リファレンスにあるので、時間の設定を触る前に、症状がどの層のものかを先に決めてください。