MAX_TOOL_USE_CONCURRENCYとMAX_CONCURRENT_SUBAGENTSの違い

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYとCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、どちらも「並列数の上限」を扱う環境変数です。名前にCONCURRENCYとCONCURRENTが両方含まれるため混同しやすく、片方を上げても意図したエラーは解消しません。前者はAPIのレート制限エラーへの対処、後者はサブエージェントの起動拒否エラーへの対処と、公式ドキュメント上でも別々の節で案内されています。

それぞれが制御するものの違い

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYは、読み込み専用のツールとサブエージェントが同時に実行できる最大数を決めます。既定値は10です。個別の定義はClaude Code「Tool Use Concurrency」エラーの原因と対処法にまとめています。対象は「読み込み専用のツール」と明記されているため、この上限が絞るのはRead・Grepのような参照系の並列実行とサブエージェントの起動数です。ファイルを書き換えるEditやコマンドを実行するBashのような書き込み系ツールがこの上限に含まれるかどうかは、公式ドキュメントのこの行だけからは判断できません。実務では、多数のファイルを読みながら並行してサブエージェントを起動するワークフローでこの上限に触れやすいため、書き込み系ツールの扱いが不明な間は保守的に見積もっておくのが安全です。

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、1つのセッション内で同時に実行中のサブエージェント数に上限をかけます。既定値は20で、Agentツールで起動するサブエージェントだけが対象です。詳しい挙動はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSとはに譲り、本記事では両者を突き合わせた比較に絞ります。

似た名前のもう1つの変数としてCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHもあります。こちらは並列数ではなく、サブエージェントが自分の子サブエージェントを何階層まで持てるかを制御する変数で、既定値は3です。並列数を制御する2つの変数とは軸が異なるため、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHとはで別に扱っています。

比較表で違いを一望する

上限に達したときの挙動が異なる点が実務上もっとも重要です。CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYは同時に実行できる数を絞る仕組みで、定義から推すと超過分は実行枠が空くまで後回しになると考えられます。一方CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、Agentツールが新しいサブエージェントの起動そのものを拒否する仕組みです。上限に達した状態で起動しようとすると、Concurrent subagent limit reachedというエラーが返り、Claudeにはリトライしないよう指示が添えられます。実行中のサブエージェントのどれかが完了して数が上限を下回れば、次の起動は成功します。

名前が紛らわしい理由と対処するエラーの違い

名前は似ていますが、公式ドキュメントでは別々のエラーの対処として案内されています。CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYは、APIのレート制限に達したときに返るRequest rejected (429)エラーの対処として案内されています。並列実行数が多すぎてAPIキーやBedrock/Vertexプロジェクトのレート制限に達したとき、この値を下げることが公式の対処に挙がっています。

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、この429エラーの対処としては登場しません。案内されているのはConcurrent subagent limit reachedエラーの回避だけで、値を上げることで同時に走らせられるサブエージェント数の天井を広げます。

429エラーの公式な対処はCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYを下げることだけではありません。大量のリクエストを送るスクリプト実行では、同時に走らせるサブエージェントの数自体を減らすことと、/modelでより小さいモデルに切り替えることも、あわせて挙げられています。

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを上げても、429エラーの原因であるAPI側のレート制限には影響しません。並列に動くサブエージェントが増えるほどAPIリクエストの同時発生数も増えるため、上げ方によってはむしろ429エラーに近づきます。逆にCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYを上げても、Concurrent subagent limit reachedは解消しません。この上限はAgentツールが個別に管理しており、読み込み専用ツールの並列数を広げる設定とは別の仕組みで数を数えているためです。

数値の書式にも違いがある

env-varsページの「Variables」節には、数値を扱う環境変数に共通のルールが書かれています。タイムアウトやトークン予算などの数値変数は、桁区切り(64_000)や指数表記(2e3)も普通の数字と同じように受け付けます。ただし、行に「plain digits only」の注記がある変数は例外です。

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの行には、この注記が明記されています。桁区切りや指数表記で値を書いても無視され、既定値の20に戻ります。正の整数以外の値(0・負の数・小数・文字列)を入れたときも同様に無視され、既定値のまま動きます。上限を外したいという意図で0を入れても、上限がなくなるわけではありません。

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYの行にはこの注記がありません。共通ルールに従えば、桁区切りや指数表記も通る値として扱われます。

並列数の上限、どちらが先に効くか

2つの上限は、値だけを見るとCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(既定20)のほうがCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY(既定10)より緩く見えます。ただし両者は別のタイミングで効くため、単純にどちらが先に詰まるとは言い切れません。

Agentツールで一度に15件のサブエージェント起動を試みた場合、20件というCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの上限には届かないため起動そのものは拒否されません。一方CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYの定義に従えば、同時に実行が進むのは10件までで、残り5件は実行枠が空くまで後回しになると考えられます。起動は15件とも成功したのに、体感の完了速度は10件分の速さに留まるという状況です。

逆に一度に25件の起動を試みた場合は、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの20件という天井の方が先に働きます。21件目以降はConcurrent subagent limit reachedエラーで起動自体が拒否され、実行中の何件かが完了して数が20を下回るまで新規起動はできません。公式ドキュメントはこの2つの上限が重なったときの具体例までは示していませんが、それぞれの定義を組み合わせるとこのようになります。起動する件数がどちらの既定値よりずっと少ない普段使いでは、この2つの上限を意識する場面自体がほとんどありません。件数が既定値に近づく大規模なレビューや一括処理を組むときに初めて、どちらが先に効くかを見積もる価値が出てきます。

ultracodeモードでの扱いの違い

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSには明確な例外があります。/effort ultracodeで入るultracodeモードのセッションでは、この上限そのものが強制されません。

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYがultracodeモードで免除されるかどうかは、公式ドキュメントに個別の記載がなく判断できません。

上限にカウントされないケース

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSが数えるのは、ClaudeがAgentツールで新規に起動しようとするサブエージェントだけです。それ以外の実行はスロットを消費しつつも、上限のチェック自体はスキップされます。なお、1セッションでサブエージェントを起動できる総数そのものには上限がありません。制限があるのは同時実行数と入れ子の深さ(CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH)だけです。起動総数に歯止めがない分、サブエージェントを大量に使うワークフローでは、同時実行数の上限よりも積み上がる支出の総量に注意を払う必要があります。

• /subtaskで現在の会話をフォークして走らせる実行は、動いている間スロットを1つ占有しますが、上限を超えていても常に成功します
• 一度完了したサブエージェントを再開する操作は、上限のチェックを行わずに新しいスロットを消費します。上限ぎりぎりの状態で複数のサブエージェントを再開すると、同時実行数が設定した上限を一時的に超えることがあります

片方の変数の例外事項を、もう片方にもそのまま当てはめないことが大切です。挙動に迷ったら、変数名だけで類推せず、必ず該当する変数の行を個別に確認してください。

設定のしかた

どちらもシェルの環境変数か、プロジェクトのsettings.jsonで設定します。

export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=20
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40
claude

プロジェクトで固定値を共有したい場合は、settings.jsonのenvキーに両方まとめて書けます。

{
  "env": {
    "CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "20",
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "40"
  }
}

大量のファイルを並列にサブエージェントへ処理させるワークフロー的な使い方では、両方を一緒に引き上げないと「起動は通るが実行が遅い」状態のままになりがちです。逆にCIでAPIコストの急増を抑えたい場合は、両方を既定値より下げる方向で検討します。

反映されるタイミングも、設定した場所によって変わります。シェルでexportした値はセッション起動時にしか読まれないため、値を変えたらclaudeを起動し直す必要があります。一方、settings.jsonのenvブロックに書いた値は、ファイルが変わると動作中のセッションにも再適用されます。同じ変数をシェルとsettings.jsonの両方で設定した場合は、settings.json側の値が優先されます。両方の変数をsettings.jsonにまとめて置いておけば、値を変えるたびにセッションを起動し直さずに済み、チームで同じ値を共有する用途にも向いています。

どちらを変えるか判断する早見表

2つの変数はどちらも「並列数」という言葉でくくれますが、片方は読み込み専用ツールも含めた実行スケジューラーの絞り込み、もう片方はAgentツール単体が管理するセッション内の同時実行数という、別々の仕組みに属します。設定を変える前に、直したいエラーがどちらのエラーメッセージなのかを確認すると、変えるべき変数を取り違えずに済みます。

まとめ

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYとCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、名前は似ていても対処するエラーと上限超過時の挙動が異なる変数です。前者は429のレート制限エラーへの対処として案内され、超過分は実行枠が空くまで後回しになると考えられます。後者はConcurrent subagent limit reachedエラーへの対処で、超過すると起動そのものが拒否されます。数値の書式(桁区切り・指数表記の可否)も行ごとに異なるため、設定時はenv-varsページの該当行を個別に確認するのが確実です。名前の一部が同じだからといって、挙動まで揃っているとは限りません。