CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONとは — 検索回数の上限を変える環境変数

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION は、1つのセッション内でWebSearchツールを呼び出せる回数に上限をかける環境変数です。既定では200回に達すると、それ以降のWebSearch呼び出しはエラーにはならず、Claudeへ「すでに集めた情報で続けるように」という通知が返るだけになります。正の整数を指定すれば上限を引き上げられますが、無効化はできません。v2.1.212以降で使えます。

上限に達すると具体的に何が起きるか

上限に達したあとのWebSearch呼び出しは、失敗を示すエラーにはなりません。代わりに、手元の情報で作業を続けるようClaudeへ促す通知が返ります。リトライを誘うエラーとは性質が違うため、Claudeが同じ検索を無限に繰り返すことはありません。

この通知は画面に直接表示されるわけではありません。上限に達した呼び出しは、会話の中では「何も返さなかった検索」としてそのまま流れていきます。それでもClaudeがさらに検索を必要とする場合は、通知の内容に従ってユーザーへ上限の引き上げを相談することがあります。気づかないまま検索が空振りし続けている、という状態を防ぐ仕組みです。

v2.1.212より前は、この切り分けそのものがありませんでした。検索バックエンドが混雑してエラーを返したとき、そのエラー文がまるで検索結果であるかのようにClaudeへ渡ってしまうことがあったためです。上限に達したときの通知と、バックエンドが過負荷のときの再試行(バックオフ付きで自動的にリトライし、それでも失敗すればエラー結果として明示的に返す)は、v2.1.212で合わせて整理された経緯があります。

WebSearchツール自体の制限も合わせて把握する

上限の挙動を正しく見積もるには、WebSearchツールそのものの仕様も押さえておく必要があります。WebSearchは検索結果のタイトルとURLを返すだけで、ページ本文までは取得しません。中身を読む必要があるときは、続けてWebFetchツールを呼び出す2段構成になっています。1回のWebSearch呼び出しが上限のカウント対象になるのはこのタイトル・URL取得の部分で、後続のWebFetch呼び出しは別のカウント対象です。

検索範囲はallowed_domainsで対象ドメインを絞り込むか、blocked_domainsで除外するかのどちらかを指定できますが、この2つを同じ呼び出しで併用することはできません。権限ルールの側ではWebSearchという指定子なしの1行だけが有効な書き方で、ドメイン単位で許可・拒否を分けることはできません。ツールごと許可するか拒否するかの二択です。

WebSearchが使える面も一様ではありません。Claude APIとClaude Platform on AWSでは利用でき、Google CloudのAgent PlatformではClaude 4以降のモデルで動きます。Microsoft Foundryでは、Anthropicがホストするデプロイでのみ使え、Azureでホストするデプロイではサーバー側ツールに非対応のため呼び出しが失敗します。Amazon Bedrockはサーバー側のWebSearchツール自体を提供していません。同じ「上限200回」という数字も、そもそもWebSearchが使える面でなければ意味を持たない点は押さえておく価値があります。

サブエージェントの検索も同じ枠を消費する

この上限はメインの会話だけでなく、セッション中に起動したすべてのサブエージェントを合算して数えます。並列でリサーチを分担させる運用では、複数のサブエージェントがそれぞれWebSearchを呼び出すぶん、1つの会話が単独で検索するより早く上限へ近づきます。

数十件のファイルを別々のサブエージェントに調べさせる、あるいは複数のリサーチタスクを同時並行で走らせる構成が典型です(Claude Codeのサブエージェント完全活用で扱う並列パターンがこれにあたります)。こうした運用では、既定の200回はあっという間に消化されます。標準搭載のワークフローである/deep-researchは、1つの質問に対して複数のWebSearch呼び出しを扇形に展開し、集めたソースを突き合わせてから引用付きのレポートにまとめる仕組みで、このタイプの利用の典型例です。設計時にはメインの検索回数だけでなく、配下のサブエージェントが合計で何回検索しそうかも見積もっておく価値があります。

値を変える方法

シェルの環境変数として渡します。

export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=500
claude

プロジェクト単位で固定値を共有したい場合はsettings.jsonのenvキーに書きます。

{
  "env": {
    "CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION": "500"
  }
}

受け付けるのは、普通の数字だけで書かれた正の整数だけです。上限そのものに決まった上限値はなく、大きな数字を指定すればそれだけ検索を許容できます。一方で0や負の数、数字以外の文字列は無視され、既定値の200がそのまま使われます。「検索回数の制限を外したいから0を入れる」という発想は通用しません。

シェルでのexportとsettings.jsonのenvで同じ変数に別の値を設定した場合は、settings.json側が優先されます。ユーザー設定や管理者設定のenvはセッション開始時に読み込まれ、プロジェクト設定やローカル設定のenvはワークスペースを信頼した時点で反映されます。チーム全体で同じ上限を強制したいなら、各自のシェルプロファイルではなく管理者設定やプロジェクト設定のenvに書いておく方が値がぶれません。

/clearでリセットされるが、ワークフローが生きていれば持ち越す

/clearを実行すると、WebSearchの残り回数はリセットされます。会話を仕切り直して新しいタスクに入るときは、検索の予算も一緒に振り出しへ戻ると考えてよい挙動です。

ただし例外があります。実行中のワークフローのように、/clearをまたいでもサブエージェントを起動し続けられる処理が生きている場合、カウントはリセットされずそのまま持ち越されます。長時間走るワークフローの途中で会話をクリアしても、検索回数の上限だけは会話の区切りと無関係に積み上がっていく点に注意が必要です。

暴走ループ対策として生き残ったのはこの変数だけ

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONはv2.1.212で入りました。このとき公式のリリースダイジェストは、これをCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONとセットで紹介していました。WebSearchの呼び出しとサブエージェントの起動は、それぞれ既定200回・200体という同じ数字の上限を持ち、「セッション全体の上限で暴走ループを止める」という1つの仕組みとして扱われていました。Claude Code v2.1.212のリリースノートでも、この2つは対の変更として書かれています。

その前提は、今は成立しません。CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONはv2.1.224で削除され、設定しても何も起こらない無効な変数になりました。サブエージェントの起動総数そのものにセッション単位の天井はもう存在しません。

つまり、v2.1.212のリリース時点の説明をそのまま覚えていると、「WebSearchとサブエージェントの起動数は、どちらもセッション単位の総数上限で暴走を止められる」という古い前提で設計してしまいます。実際には、セッションを通じた生涯合計に天井が残っているのはWebSearchの呼び出しだけです。

似た名前でさらに紛らわしいのがCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY(既定10)です。これは読み取り専用ツールとサブエージェントをまとめて「同時に並列実行できる数」を絞る変数で、サブエージェントだけを対象にするCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(既定20)とは対象範囲が異なります。どちらも総数ではなく同時実行数を制御する点は共通ですが、絞り込む対象の範囲が違うため、名前だけで混同すると意図した並列度にならないことがあります。

値を変える判断材料

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを引き上げて並列度を上げるほど、同時に走るサブエージェントの数だけWebSearchの呼び出しペースも上がり、既定200回の枠には早く到達します。2つの上限は別の変数ですが、並列運用では実質的に連動して効いてくるという点は覚えておくとよい挙動です。

まとめ

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONは、WebSearchの呼び出し回数にセッション単位の上限をかける環境変数で、メインの会話とすべてのサブエージェントの検索を合算してカウントします。上限に達しても検索が止まって終わるわけではなく、Claudeが手元の情報で作業を続けるための通知に切り替わるだけです。導入当初はCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONと対で語られていましたが、後者はv2.1.224で撤廃され、サブエージェント側は同時実行数と深さという別の軸で制御される形に変わりました。環境変数全体の一覧はClaude Code環境変数リファレンスにまとめています。