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

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

v2.1.290からは、対話ターミナルのセッションでこの上限が時間とともに補充されます。補充の速さは1時間に約100回で、CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOURで変えられます。非対話(claude -p)の既定は0で、補充は働きません。補充の仕組みはWebSearchの補充レートの解説にまとめています。

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

上限に達したあとのWebSearch呼び出しは、失敗を示すエラーにはなりません。公式の説明では、再試行を誘うエラーではなく、手元の情報で作業を続けるよう促す通知が返る設計です。

画面に何も出ないため、検索が空振りしていることに気づきにくい点は押さえておく必要があります。検索結果が急に薄くなったと感じたら、回数の消化を疑う材料になります。対話セッションなら、時間が経てば補充された分だけ検索が戻ります。

v2.1.212より前は、検索バックエンドが混雑してエラーを返したとき、そのエラー文が検索結果であるかのようにClaudeへ渡ることがありました。現在は、混雑時にバックオフ付きで再試行し、それでも失敗した呼び出しはエラー結果として返ります。上限到達の通知とは別の経路です。

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

WebSearchは検索結果のタイトルとURLを返すだけで、ページ本文までは取得しません。中身を読む必要があるときは、続けてWebFetchツールを呼び出す2段構成です。上限のカウント対象は、このタイトル・URLを返すWebSearchの呼び出し側で、後続のWebFetchは別の呼び出しです。

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

WebSearchが使える面も一様ではありません。

• Claude APIとClaude Platform on AWS: 利用できます
• Google CloudのAgent Platform: Claude 4以降のモデルで動きます
• Microsoft Foundry: 利用できます
• Amazon Bedrock: サーバー側のWebSearchツール自体を提供していません

上限200回という数字は、WebSearchが使える面でなければ意味を持ちません。なお、検索バックエンドは設定で差し替えられません。別の検索プロバイダーを使いたいときは、検索ツールを公開するMCPサーバーを追加する形になります。

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

この上限はメインの会話だけでなく、セッション中に起動したすべてのサブエージェントを合算して数えます。並列でリサーチを分担させると、それだけ早く上限へ近づきます。

数十件のファイルを別々のサブエージェントに調べさせる、複数のリサーチタスクを同時に走らせる、といった構成が典型です(Claude Codeのサブエージェント完全活用で扱う並列パターンがこれにあたります)。標準搭載のワークフロー/deep-researchは、1つの質問に対してWebSearchを扇形に展開し、ソースを突き合わせて引用付きのレポートにまとめます。公式は、並列リサーチで扇形に展開した検索も同じ上限に数えると書いています。/deep-researchはその典型です。

設計時には、メインの検索回数だけでなく、配下のサブエージェントが合計で何回検索しそうかも見積もっておくと判断しやすくなります。

値を変える方法

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

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側の値が適用されます。Claude Codeがenvの各項目を、シェルから引き継いだ値を置き換える形でプロセス環境に書き込むためです。値を引き継ぐセッションの例外は、公式のenv設定の解説にまとまっています。

envが反映されるタイミングは、置き場所で異なります。ユーザー設定・--settings・管理者設定は起動時です。プロジェクト設定とローカル設定は、ワークスペースを信頼したあとです。ただしタイムアウトや上限のように安全と分類された変数は、すべての設定ファイルから起動時に適用されます。チーム全員に同じ上限を強制したい場合は、管理者設定のenvに書くと、ユーザー設定やプロジェクト設定より優先されます。

検索そのものを止めたいときは別の手段になる

回数の上限は「引き上げ」はできても「なし」にはできません。逆に、検索を使わせたくない場合、この変数で0を指定しても止まらないので、ツール自体を拒否する方向になります。v2.1.285のclaude --helpには、ツールを名前で拒否するオプションがあります。

claude --help | grep -A2 -e '--disallowedTools' -e '--tools'

該当する2項目の説明は次のとおりです(v2.1.285のclaude --helpから抜粋)。

  --disallowedTools, --disallowed-tools <tools...>
      Comma or space-separated list of tool names to deny (e.g. "Bash(git *)
      Edit")
--
  --tools <tools...>                    Specify the list of available tools from
                                        the built-in set. Use "" to disable all
                                        tools, "default" to use all tools, or
                                        specify tool names (e.g.
                                        "Bash,Edit,Read").

--disallowedToolsにWebSearchを渡す形は、公式の記述に沿っています。CLIリファレンスには、素のツール名を渡すと該当ツールがコンテキストから外れるとあります("Edit"ならEditが外れます)。権限ルールの表でも、WebSearchは指定子なしでツール全体の許可・拒否ができるとされています。ただしこの記事では実際にモデルを呼ぶ操作はしていないため、拒否したときの画面や挙動までは確認していません。settings.jsonのpermissions.denyにWebSearchを書く方法も、同じ権限ルールの仕組みに乗ります。

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

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

例外は、サブエージェントを起動できる処理が/clearのあとも生きている場合です。実行中のワークフローがこれにあたり、カウントはリセットされず持ち越されます。長時間走るワークフローの途中で会話をクリアしても、検索回数は積み上がったままです。

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

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONはv2.1.212で入りました。当時のリリースダイジェストは、これをCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONとセットで紹介しています。WebSearchの呼び出しとサブエージェントの起動は、どちらも既定200のセッション全体の上限で暴走ループを止める、という説明でした。Claude Code v2.1.212のリリースノートでも、この2つは対の変更として書かれています。

その前提は、今は成立しません。CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONはv2.1.224で削除され、設定しても何も起こらない変数になりました。削除前は、上限を超えた起動がSubagent spawn limit reachedで失敗していました。今のサブエージェントの制約は、次の2軸です。

どちらも、セッション中に生涯で何体起動できるかという総数は制限しません。回数の天井が今も残っているのは、WebSearchの呼び出しだけです。ただしv2.1.290以降の対話セッションでは、その天井も時間で補充されます。Claude Codeの設計で「起動数と検索数の両方を総数で縛れる」と考えていると、サブエージェント側は想定どおりに止まりません。

似た名前のCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY(既定10)は、読み取り専用ツールとサブエージェントをまとめて、並列に実行できる数を絞る変数です。サブエージェントだけを対象にするCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(既定20)とは、絞る対象の範囲が違います。名前だけで混同すると、意図した並列度になりません。

値を変える判断材料

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを引き上げて並列度を上げると、同時に走るサブエージェントが増え、WebSearchの消化ペースも上がります。2つは別の変数ですが、並列運用では合算の枠に向けて連動して効きます。

まとめ

並列リサーチを組むなら、同時実行数と深さの設定に加えて、合算される検索の枠を先に見積もっておくと判断しやすくなります。環境変数全体の一覧はClaude Code環境変数リファレンスにまとめています。補充レートと上限の組み合わせ方はWebSearchの補充レートで扱っています。