Claude CodeのWeb検索の上限設定｜暴走ループを防ぐ
「無人で回しているAIジョブが、気づいたらWeb検索を延々と繰り返していたらどうしよう」——AIに調べものを任せて自動運転させ始めた人なら、誰もが一度はこの不安を抱えます。
結論から言うと、Claude Code v2.1.212 で追加された CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION（既定200）という環境変数で、1セッションあたりのWeb検索回数に天井を作れます。検索が暴走ループに入っても、上限で自動的に止まります。
株式会社Fyveの私は、毎晩Mac miniで複数のAIジョブを人が見ていない状態で回しています。その「無人運用」の現場感から、この上限をどこに、いくつで効かせるべきかを解説します。
Web検索の「暴走ループ」とは何か、なぜ怖いのか
Claude Code はWebSearchツールを使って、自分で調べものをしながら作業を進めます。便利な反面、条件次第では「検索する→結果が不十分→また検索する」を延々と繰り返す暴走ループ（runaway search loop）に陥ることがあります。
対話しながら使っているなら、おかしいと気づいた瞬間に止められます。問題は無人運用です。cronやlaunchdで定時に起動し、人が画面を見ていないジョブでは、検索が空回りし続けても誰も気づけません。翌朝ログを見て初めて、想定の何倍もの検索が走っていたと知ることになります。
Web検索は1回ごとに課金が発生する処理です。暴走が1セッションで数百回に膨らめば、それはそのまま課金事故になります。私が「無人でAIを回す」ことの最大のリスクだと考えているのは、性能でも品質でもなく、この「見ていない間にお金だけが溶ける」タイプの事故です。
やっかいなのは、暴走が「バグ」ではなく「頑張りすぎ」の顔をしてやってくる点です。AIは指示された調べものを完遂しようとして、答えが見つからないほど検索を増やします。悪意も故障もなく、真面目に空回りする——だからログを読むまで異常だと気づきにくいのです。回数の天井は、この「真面目な暴走」を機械的に打ち切るための仕組みです。
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION の正体
この設定は、2026年7月17日リリースの Claude Code v2.1.212 で追加されました。公式チェンジログには「1セッションあたりのWebSearchツール呼び出しに上限を設け（既定200・CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION で調整可能）、暴走する検索ループを止める」と明記されています。
ポイントを整理します。
- 効果範囲: 1セッション全体（session-wide）でのWeb検索回数をカウントし、上限に達したらそれ以上検索しません
- 既定値: 200回。多くの通常作業では触れない天井ですが、暴走時にはここで確実に止まります
- 調整方法: 環境変数なので、値を下げれば天井を低く、上げれば高くできます
同じ v2.1.212 では、兄弟にあたる CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION（既定200）も追加されました。こちらはサブエージェントの生成回数に上限を設け、「委任の暴走ループ」を止める設定です（このサブエージェント側の予算は /clear でリセットされます）。検索とサブエージェント、無人運用で膨らみやすい2つの処理に、同時に天井が用意されたことになります。
設定の入れ方は環境変数なので、起動用のシェルやlaunchd/cronのラッパースクリプトで export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=50 のように書くか、Claude Code の設定ファイル（settings.json）の env ブロックに書いておけば、そのジョブに恒久的に効かせられます。
ここで押さえておきたいのは、この設定が「回数」で止める仕組みだという点です。トークン量や金額の上限とは、止め方の軸が違います。金額の天井は「いくら使ったか」で止まりますが、Web検索の暴走は、1回あたりのコストは小さくても回数が積み上がって被害が出るタイプです。だから「金額の天井を張ってあるから大丈夫」とは限りません。回数で暴れる処理には、回数の天井で応じるのが素直な対策になります。
読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →私が無人ジョブでこの上限をどう決めているか
私はMac miniを常時起動のAI自動化サーバーにして、記事の執筆やAIニュースの調査といったジョブをlaunchdで定時に回しています。そのほとんどが、作業の中でWebSearchを使って最新情報を集めます。まさにこの記事も、新機能の仕様を公式チェンジログとGitHubリリースで裏取りする過程で、私自身がWeb検索を何度も回しました。
無人ジョブに上限を決めるときの私の基準はシンプルです。「そのジョブが正常なら何回くらい検索するか」を見積もり、その2〜3倍を天井にする——これだけです。
- 調べものが主役のジョブ（ニュース収集・多源リサーチ）: 正常でも数十回検索するので、既定200のままか、少し余裕を持たせます
- 調べものが脇役のジョブ（定型の記事整形・軽い確認）: 正常なら数回で済むので、天井を20〜50程度まで下げます。ここが暴走したら明らかに異常なので、早めに止めたいからです
既定の200をそのままにしない理由は、天井は「異常を早く止める非常ブレーキ」だからです。正常時に触れない高さに置いたままだと、暴走しても200回まで走ってから止まります。ジョブごとに正常値を知っている自分が、そのジョブに合った低い天井を置くことで、事故の被害を1桁小さくできます。
具体的にイメージしやすいよう、私の運用を2つ並べます。ひとつは毎朝のAIニュース調査ジョブで、複数のキーワードで横断的に検索するため正常でも十数回は検索します。ここは余裕を持たせ、天井を高めに置きます。もうひとつは、決まった素材を整形して下書きにするだけの定型ジョブで、正常なら検索は数回あるかどうか。こちらは天井を低くし、少しでも余計に検索し始めたら早期に止まるようにします。
同じ「AIを無人で回す」でも、ジョブの性格によって適正な天井はまるで違います。だからこそ、この設定は全体に一律の値を配るのではなく、ジョブ単位で持たせるのが要点です。ラッパースクリプトごとに環境変数を書き分ければ、それぞれのジョブに別々の天井を配れます。
上限に達したらどうなるか、そして値の決め方
上限に達すると、そのセッションではWebSearchツールがそれ以上呼び出されなくなります。作業自体が強制終了するわけではなく、「検索という手段だけが打ち止めになる」挙動です。つまり天井は、AIの作業を殺すのではなく、暴走した1つの処理だけを止める、外科的な非常ブレーキだと理解しておくと扱いやすくなります。
値を決めるときは、いきなり本番のジョブに低い天井を入れないことをおすすめします。私は次の順序でチューニングしています。
- まず正常値を知る: 数日そのジョブを回し、ログで「正常運転のとき何回くらい検索しているか」を把握します。ここが分からないまま天井を置くと、正常な処理を途中で切ってしまいます
- 2〜3倍を天井にする: 正常が10回なら20〜30回に設定します。正常時には絶対に触れず、暴走時にだけ働く高さを狙います
- 切られたら見直す: もし正常なジョブが天井で止まるようになったら、それは仕事量が増えたサインです。天井を上げるか、ジョブを分割するかを判断します
天井は「一度決めて終わり」ではなく、ジョブの成長に合わせて動かす数字です。無人運用で常時起動のサーバーにジョブを集約していく設計については、こちらでも触れています。
「1つの天井」に頼らない、多層の課金事故対策
大事なのは、この設定を唯一の防波堤にしないことです。Web検索の上限は、あくまで「検索という1つの処理」に効く非常ブレーキにすぎません。無人運用の課金事故は、検索以外の経路でも起きます。
私は次の3枚を重ねて、どこか1枚が破れても事故が致命傷にならないようにしています。
- 入口を絞る: そもそも高コストなモデルで回さない。無人ジョブは
--modelでモデルを明示し、定型作業は安いモデルに固定します - 回数に天井: 今回のWeb検索上限やサブエージェント上限で、暴走系の処理を回数で止めます
- 禁止事項を宣言: 課金・送信・破壊操作など「無人でやってほしくないこと」を deny 設定で最初から禁じます
無人でAIを回すコストの考え方の全体像は、こちらで整理しています。
回数ではなく「金額そのもの」に上限をかける予算設定は、次の記事が詳しいです。
検索と並んでトークンが暴走しやすい自走ループ（/loop）の抑え方は、こちらにまとめています。
まとめ
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION は、v2.1.212 で入った小さな環境変数ですが、無人運用で「見ていない間にお金だけが溶ける」事故を防ぐ実用的な一枚です。既定の200をそのままにせず、ジョブごとの正常値の2〜3倍を天井にするだけで、暴走の被害を大きく縮められます。
そして、この天井だけに頼らず、モデル明示・回数上限・deny設定を重ねること。無人でAIを回すほど、この「多層の非常ブレーキ」が効いてきます。私たちは、こうした自動化の設計と運用の仕組みづくりを支援しています。
Claude Codeを「素のまま」使うな
設定で差がつく——CLAUDE.md・権限・スキルの実物を公開（全24ページ）
素のClaude Codeは"優秀な新入社員"。仕事を教えるほど、自分専用になります。覚えさせる4点セット——会社の説明書（CLAUDE.md）・権限の柵・手順書（スキル）・フォルダの地図——を、1人会社の実運用からコピペで使える型つきで公開します。
- そのまま書き換えて使えるCLAUDE.mdの型
- お金と送信をAIに触らせない「3段階の柵」
- 1回教えたら何度でも動く、手順書のコピペ雛形
- AIが迷子にならないフォルダ構造の3原則
毎週金曜の無料ニュースレター「ひとりAI経営」の購読特典です。メール登録後すぐ、ダウンロードページのご案内が届きます。あわせて、AI活用に関するお知らせやお役に立てそうなご案内をお送りすることがあります。解除はいつでも1クリック。
御社の業務に合わせたClaude Code導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。