Web Fetchのuse_cacheでweb_fetchのキャッシュを回避する方法

web_fetchとは、指定したURLのWebページやPDFをClaudeが読み込み、内容を会話の文脈に入れるClaude APIのサーバーツールです(Web Fetchツール)。このツールは、パフォーマンス向上のため取得結果をキャッシュします。既定ではキャッシュされたコンテンツが返るため、更新頻度の高いページを何度取得してもClaudeには古い内容が渡ることがあります。この挙動を上書きするパラメータが use_cache です。web_fetch_20260309 以降のツールバージョンで使え、"use_cache": false を指定するとキャッシュを迂回して常に新しい内容を取得します。

古い内容が返るのはキャッシュが原因とは限らない

公式ドキュメントは、キャッシュの挙動を次のように説明しています。

The web fetch tool caches results to improve performance and reduce redundant requests. The content returned may not always reflect the latest version available at the URL.

キャッシュの管理方法や対象は自動で最適化され、時間とともに変わる可能性があるとも明記されています。「このURLはキャッシュされない」と決め打ちできる固定ルールはなく、保持期間の数値も示されていません。常に新しい情報が必要なら、明示的に回避する必要があります。取り込み量とトークン料金の見積もりはClaude APIのweb fetch料金にあります。

一方で、「内容が古い」「取得できない」と感じる原因はキャッシュだけではありません。次の順で切り分けると、use_cache の出番かどうかが分かります。

エラーコードのうち、再取得しても直らないものを覚えておくと無駄な再試行を避けられます。URLが250文字を超える url_too_long、robots.txt や非公開アドレスなどによる url_not_allowed、テキスト・HTML・PDF以外の unsupported_content_type は、use_cache: false にしても結果は変わりません。不正な形式のURLやHTTP(S)以外のスキームを渡したときの invalid_tool_input も同じです。HTTPエラーで取得に失敗した url_not_accessible も、キャッシュとは別の原因です。一方、too_many_requests(レート制限)と unavailable(内部エラー)は、URLや設定ではなく実行時の状況を示すコードです。

設定方法

use_cache はツール定義の中で false を指定します。ツールタイプは web_fetch_20260309 以降(web_fetch_20260318 でも有効)です。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "https://example.com/status を確認して、現在の障害有無を教えて"
      }
    ],
    "tools": [{
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }]
  }'

tools 配列の web_fetch エントリーに1行足すだけです。use_cache を書かない場合の既定値は true です。

キャッシュを回避する呼び出しと、しない呼び出し

公式ドキュメントは use_cache: false の代償を明確に書いています。

Only disable caching when the user explicitly requests fresh content or when fetching rapidly changing sources, because bypassing the cache increases latency.

キャッシュを回避すると応答が遅くなるため、すべての呼び出しに一律で false を付ける運用は、レイテンシを常に最大化する選択になります。鮮度が必要な呼び出しだけ個別に指定するのが、公式の想定する使い方です。

スクリーンショットやPDF化まで必要な取得には、Cloudflare Browser RenderingのMCPのような専用サーバーが向いています。

名前が似た3つのキャッシュを混同しない

「キャッシュ」と呼ばれる仕組みは、web_fetch周りだけで3つあります。use_cache が制御するのは、このうち1つ目だけです。

3つ目は、Claude Codeの公式ドキュメントに具体的な数値があります。WebFetchは各レスポンスを既定で15分間キャッシュし、Claude Code v2.1.233以降なら環境変数 CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS で保持時間をミリ秒単位で変えられます(既定値は 900000)。API側が保持期間を示さないのとは対照的で、設定の探し方も変わります。環境変数の詳細はWebFetchのキャッシュ保持時間を変える方法にまとめています。Claude Codeでこの話題に当たったときは、use_cache ではなくこちらを見ます。

ツールバージョンと機能の対応

use_cache の対象は web_fetch_20260309 以降です。バージョンごとに使える機能が積み上がっています。

dynamic filteringはClaude 4.6以降のモデルとClaude Mythos Previewで使えます。dynamic filteringだけが目的なら web_fetch_20260209 でも足り、use_cache は追加の要件です。response_inclusion は、コード実行の呼び出しで消費された取得結果をレスポンスから落とす "excluded" を選べるパラメータで、web_fetch_20260318 以降に限られます。

見落としやすいのがZDR(ゼロデータ保持)との関係です。ZDRの対象になるのは基本版の web_fetch_20250910 で、_20260209 以降はdynamic filteringがコード実行に依存するため、既定ではZDR対象外です。use_cache が使える最小バージョンの web_fetch_20260309 もこの範囲に入ります。ZDR下で _20260209 以降を使うには、ツール定義に "allowed_callers": ["direct"] を付けてdynamic filteringを無効にする手順が、公式のServer toolsページにあります。仕組みの詳細はweb_searchのdynamic filteringがZDR対象外になる仕組みが扱っています。

併用する設定との関係

use_cache はツール定義全体に効く設定です。tools 配列の web_fetch エントリーに1度書くもので、個々のURLごとの指定はありません。

• URL検証の制約は変わりません: 取得できるのは、ユーザーメッセージ・クライアント側ツールの結果・過去のweb_search / web_fetchの結果に出てきたURLだけです。Claude自身の出力にしか出ていないURLや、システムプロンプトだけに書いたURLは取得できず、url_not_in_prior_context になります。システムプロンプトのURLは、ユーザーメッセージにも入れれば取得できます(エラーの原因と対処)。コード実行・MCPコネクタ・ツール検索といった別のサーバーツールの結果も、取得元として認められません
• 認証情報らしき文字列を含むURLは拒否されます: APIキーやパスワードのように見える文字列を含むURLは url_not_allowed になります。その文字列がシステムプロンプトかユーザーメッセージ本文にあれば取得できますが、ツール結果にだけ現れた文字列は数えられません
• max_uses と allowed_domains は独立しています: max_uses は1リクエスト内の取得回数の上限で、失敗した取得も回数に数えられます。上限を超えると max_uses_exceeded のエラー結果になります
• 料金は変わりません: web_fetch自体に追加料金はなく、文脈に入った分だけ通常のトークン料金がかかります。公式の目安は、10kBの平均的なページで約2,500トークン、100kBのドキュメントページで約25,000トークン、500kBの論文PDFで約125,000トークンです。コストを抑えたいときは max_content_tokens で取得量の上限を決めます。この上限が効くのはテキストで、PDFのようなバイナリには適用されません。値もおおよその上限で、実際の入力トークン数は少しずれます。コード実行ツール側の費用はコード実行ツールが無料になる条件を参照してください

web_searchと組み合わせるとき

web_searchとweb_fetchを同時に有効にすると、ユーザーがURLを直接渡さなくても取得が成立します。「〇〇について調べて、詳しく分析して」という依頼では、Claudeがまずweb_searchでページを見つけ、続けてweb_fetchで内容を取得します。ニュース追跡や価格モニタリングのように同じURLを繰り返し読む用途では、web_fetch側に use_cache: false を付けないと、古いキャッシュが返る可能性があります。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "量子コンピューティングの最新記事を探して、一番関連性の高いものを詳しく分析して"
      }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3
      },
      {
        "type": "web_fetch_20260309",
        "name": "web_fetch",
        "max_uses": 5,
        "use_cache": false
      }
    ]
  }'

利用できる面

web_fetchツールはClaude APIのほか、Claude Platform on AWSとMicrosoft Foundryで利用できます。Microsoft FoundryのうちAzureでホストされたデプロイは基本版の web_fetch_20250910 のみで、use_cache が要求する web_fetch_20260309 以降には対応していません。Anthropicがホストするデプロイではすべてのバージョンが使えます。Amazon BedrockとGoogle Cloudでは、web_fetchツール自体が提供されていません。

まとめ

更新頻度の高いページを読ませる呼び出しにだけ、web_fetch_20260309 以降と "use_cache": false を組み合わせます。ZDRが要件の環境では、use_cache が使える最小バージョンが既定でZDR対象外である点を先に確認します。