Claude Code WebSearchの回数制限が1時間100回の補充式に変わった

Claude CodeのWebSearchは、v2.1.290から回数の上限が時間とともに補充される方式になりました。対話セッションでは1時間あたり約100回ずつ回復し、補充の速さは環境変数 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR で変えられます。非対話(claude -p)の既定は 0 で、補充は働きません。

何が変わったのか

v2.1.289までのWebSearchには、1セッションで200回という総量の上限がありました。メインの会話とサブエージェントの検索を合算して数え、使い切ると以後の検索は空振りします。

v2.1.290で、この上限は時間で補充される予算に変わりました。対話セッションでは200回で終わらず、1時間あたり約100回ずつ回復します。補充レートは CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR で決まり、0 にすると補充が止まります。

リリース全体の変更点はClaude Code v2.1.290のリリースノートにあります。ここでは検索の予算に絞って掘り下げます。

CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOURの仕様

環境変数リファレンスの記述は次の4点に集約できます。

• 単位は「1時間あたりの補充回数」。対話ターミナルセッションの既定値は 100
• 非対話セッションの既定値は 0。補充は切れた状態になる
• 受け付けるのは数字だけの文字列。ほかの書き方は未設定と同じ扱いになる
• v2.1.290以降で有効

「数字だけ」の縛りは見落としやすい点です。100/h や 1e2、100.0 のような書き方は未設定と読まれ、既定値に戻ります。エラーも出ないため、設定が効いているのかは挙動で確かめるしかありません。

1時間100回は何を意味するか

単純に割ると、補充は平均して36秒に1回の割合です。短時間に集中して検索すると、予算はすぐ尽きます。一方で長時間の作業なら、使い切っても少し待てば検索が戻ります。

原文の表現は「about 100 calls per hour」です。1回ずつ連続的に戻るのか、1時間ごとにまとめて戻るのかは書かれていません。この記事ではどちらとも断定しません。一方、補充の対象は「セッションの上限(既定200回)」と明記されており、次の節の CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION がその上限の高さを決めます。

補充式でも変わらない点

補充式になっても、次の挙動は従来のままです。

• 対象は対話ターミナルセッション。仕様の記述はこの前提で書かれている
• カウントはメインの会話とすべてのサブエージェントの合算
• 上限に達した呼び出しは、エラーではなく「手元の情報で続ける」よう促す通知が返る
• 通知は画面に出ず、会話上は何もしなかった検索に見える
• /clear で数え直し。ただし実行中のワークフローのようにサブエージェントを起動する可能性のある処理が生き残っていると、カウントは持ち越される

上限が尽きても、Claudeは失敗として再試行を繰り返さずに別の手段へ移ります。補充式が効くのは、そのあとです。時間が経てば、再び検索が使える状態に戻ります。

総量の上限との関係

補充レートとは別に、CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION が検索回数の上限(既定200)を決めます。2つは別の変数です。上限は正の整数なら青天井に上げられますが、無効にはできません。

上限そのものの設定はCLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONの解説にあります。両者を併用すると、「上限の高さ」と「回復の速さ」を別々に調整できます。ただし、補充分を上限を超えて貯められるかどうかは書かれていないため、この記事では「上限は CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION が決め、補充は使った分を戻す」という範囲にとどめます。

設定のしかた

シェルから渡す場合は、起動前に export します。

export CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=300
claude

プロジェクトやユーザーで値を固定するなら settings.json の env キーに書きます。環境変数リファレンスによると、この方式は claude をどう起動しても有効で、保存すると実行中のセッションにも新しい値が反映されます。

{
  "env": {
    "CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR": "300"
  }
}

値は文字列で書き、数字だけにします。補充を止めたいなら "0" です。補充レートの数値に上限は記されていません。

非対話実行(claude -p)では補充が働かない

CIやスクリプトから claude -p で呼ぶ非対話セッションは、補充レートの既定が 0 です。対話セッションと同じ感覚で「待てば回復する」とは考えられません。

非対話で調査系のプロンプトを回す運用では、補充レートを明示すると見通しが立ちます。ここで例を示します(値は説明用の仮のもので、公式が推奨する数値ではありません)。

CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=100 \
  claude -p "競合3社の最新の料金改定を調べて表にまとめて"

非対話セッションで上限(200回)そのものがどう適用されるかは、tools-referenceに書かれていません。上限の説明が「対話ターミナルセッションは200回」という前提で書かれているためです。非対話で並列のリサーチを回す設計では、検索が空振りしたときの挙動を実際に試してから運用に載せるのが確実です。

並列リサーチを組むときの考え方

予算の消化が速いのは、サブエージェントを扇形に展開するときです。サブエージェントの並列パターンや、標準の /deep-research(Claude Code deep-researchコマンドの解説)のように、1つの質問を複数のエージェントに分担させると、同じ予算を一斉に引き落とします。

予算の使い方をClaude Codeに伝えたいときは、CLAUDE.mdに検索の方針を書いておく手があります。次は書き方の一例です。

## WebSearchの使い方
- 同じ論点を複数のサブエージェントで重複して検索しない
- 検索が空振りしたら、再試行せず手元の情報でまとめ、不足点を書き出す
- 一次ソースが確定したら、追加の検索ではなくWebFetchで本文を読む

この規約が検索回数を実際に減らすかどうかは、モデルの従い方次第で、保証された挙動ではありません。確実に止めたいなら、権限ルールで WebSearch をdenyにする方法があります。このルールは指定子なしの1形式だけで、ドメイン単位の許可・拒否はできません。

上限に達したかを確かめる方法

上限に達しても、画面にはエラーも警告も出ません。通知はClaudeにだけ返り、会話上は「検索したのに何も起きなかった」ように見えます。気づき方と切り分けは次の順が目安です。

1. 同じ質問で、検索結果の引用が急に消えたり「手元の情報でまとめます」という流れに変わったりしていないかを見る
2. /clear で数え直して同じ質問を投げ、検索が戻るかを確かめる。実行中のワークフローなどが残っていると、カウントは持ち越されるので注意する
3. 戻らないなら、WebSearch を拒否するルールが入っていないか、Bedrock経由の環境でないかを確認する

サブエージェントを多用していたなら、検索の大半を子が使い切っていた可能性もあります。呼び出し回数はメインとサブエージェントで合算なので、子の検索ぶんも同じ予算から減ります。

補充レートと上限の組み合わせ早見表

使い方ごとに、触る変数を並べます。数値は説明用の例で、推奨値ではありません。

「検索を使わせない」場合は、補充を0にしても上限の範囲では検索できてしまうので、数値の変数ではなく拒否ルールで止めます。

検索バックエンドを差し替えたい場合

WebSearchの検索先はAnthropicのWeb検索バックエンドに固定されており、変更できません。別の検索プロバイダーを使いたいなら、検索ツールを公開するMCPサーバーを追加する方法があります。MCPサーバーの検索ツールはWebSearchとは別のツールなので、WebSearchの回数が足りないときの代替経路になります。ただし、そのサーバー自身の課金や回数制限は別に確認が必要です。ツールの組み合わせ方は、使うサーバーの仕様に合わせて試すことになります。

自分の環境で制限がかかるか

WebSearchはClaude API、Claude Platform on AWS、Microsoft Foundryで使えます。Google CloudのAgent PlatformではClaude 4以降のモデルで動きます。Amazon Bedrockはサーバー側のWeb検索ツールを提供していないため、Bedrock経由で使っている場合はそもそもWebSearchが使えず、回数の上限以前の問題になります。

補充式の予算が合う作業、合わない作業

よくある質問

補充レートを0にすると、検索はできなくなるのか

できなくなるわけではありません。補充が止まるだけで、上限(既定200)の範囲では検索できます。検索自体を止めたいなら、権限ルールで WebSearch を拒否します。

値を空文字や小数にするとどうなるか

数字だけの文字列以外は未設定と読まれ、既定値(対話100 / 非対話0)が使われます。エラーは出ません。

バックエンド検索が1回の呼び出しで最大8件走る分は数えられるか

WebSearchは1回の呼び出しで最大8件のバックエンド検索を内部的に発行することがあります。予算に数えられるのは呼び出しの回数と説明されていますが、内部の検索数が加算されるかどうかは書かれていません。

まとめ

v2.1.290で、WebSearchは「200回で終わり」から「時間で補充される予算」に変わりました。対話セッションでは1時間約100回が既定で、CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR で調整できます。落とし穴は2つあります。数字以外の書き方は黙って無視されること、非対話セッションの既定は0で補充が働かないことです。長時間の対話作業には追い風ですが、claude -p のバッチと短時間の並列リサーチでは、設定と挙動の確認が欠かせません。