Claude Codeの--max-budget-usdでAPI課金額に上限を設ける

--max-budget-usd は、印刷モード(-p を付けた非対話実行)でのAPI課金額に上限をかけるCLIフラグです。サブエージェントの支出も合算して判定し、上限に達すると新しいサブエージェントの起動が失敗、実行中のバックグラウンドサブエージェントも止まります。この強制の挙動はClaude Code v2.1.217以降で有効です。

使い方

指定するのはドル建ての金額です。小数も渡せます。

claude -p --max-budget-usd 5.00 "リポジトリ内のTODOコメントを一覧化して"

対応する環境変数は無く、指定できるのはこのCLIフラグだけです。CIのワークフローファイルやシェルスクリプトの実行コマンドに直接書き込む形になります。毎回同じ上限を使うジョブなら、コマンドをラップするシェル関数やMakefileのターゲットにまとめておくと書き漏れを防げます。

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

公式ドキュメントが具体的に挙げている挙動は2つです。

1. 新しいサブエージェントの起動が Budget limit reached というエラーで失敗する
2. その時点で実行中のバックグラウンドサブエージェントが停止する

この2点はどちらもサブエージェントに対する挙動で、メインのエージェントループそのものを上限到達時にどう止めるかは、フラグの短い説明以上には踏み込んで書かれていません。「stopping」という言葉自体はフラグの説明文冒頭にありますが、明記されているのは上のサブエージェント2点だけです。単一のサブエージェントを使わない単発の問い合わせで運用している場合、上限に達した瞬間の挙動を試す前提で金額を決めておくほうが安全です。

サブエージェントの支出はメインセッションの支出と合算されます。並列でサブエージェントを何本も走らせるワークフローほど、上限に早く到達します。個々のサブエージェントの支出だけを個別に制限したい場合、このフラグでは対応できません。

ここでいう「バックグラウンドのサブエージェント」は、セッションそのものをバックグラウンドプロセスとして起動する --bg(--background)フラグとは別の概念です。--bg はセッション全体を非対話のジョブとして走らせるフラグで、公式ドキュメント上 -p(--print)とは併用できません。--max-budget-usd は印刷モード限定のフラグなので、--bg で起動したセッションには直接指定できず、上限をかけたいなら -p を使った通常の印刷モード実行を選ぶ必要があります。

契約単価(modelPricing)がある場合はそちらで判定される

組織が契約単価をmodelPricingという管理設定で登録している場合、--max-budget-usd の上限判定もリスト価格ではなく契約単価で行われます。公式ドキュメントは、この設定が反映される先として /usage・ステータスライン・Agent SDKの total_cost_usd・--max-budget-usd の上限・OpenTelemetryのコスト指標を並べて挙げています。modelPricing は管理設定(managed settings)なので、開発者個人の settings.json や --settings フラグでは上書きできません。

つまり、同じ「5ドル」という指定でも、組織にボリュームディスカウントの契約があれば、実際に使えるトークン量はリスト価格前提より多くなります。日次バッチのようにチーム全体で同じコマンドを使い回す構成では、上限の金額を決める前に自分の組織が modelPricing を設定しているかを確認しておく価値があります。

modelPricing はスコープがmanaged限定の設定で、managed-settings.json やMDMポリシーのような組織側の配布経路でしか有効になりません。個人のプロジェクト設定や --settings フラグに同じキーを書いても無視されます。中身は multiplier(全モデルに一律で掛ける割引率)と overrides(モデルごとの単価表)の組み合わせで、--max-budget-usd が見る金額もこの2つを適用した後の数値です。自分の上限がどう計算されているか確認したい場合、設定できるのは組織の管理者側であり、開発者個人のトラブルシューティングでは「管理設定が反映されているか」を疑うところから始めることになります。

対話モードでのコスト確認は別の仕組み

対話セッションには --max-budget-usd のような支出の強制上限はありませんが、支出そのものが見えないわけではありません。ステータスラインに cost.total_cost_usd を表示させれば、セッション開始からの推定コストをリアルタイムで確認できます。同じ数値は /usage コマンド(エイリアスは /cost と /stats)でも確認でき、セッションのコストに加えてプランの利用上限に対する消費状況もまとめて見られます。ただしこの数値は modelPricing が有効でなければリスト価格ベースの見積もりで、実際の請求額とずれることがあり、/clear で新しいセッションが始まると0にリセットされます。上限を強制したいなら印刷モードで --max-budget-usd を使い、対話中はステータスラインや /usage で様子を見ながら手動で止める、という役割分担になります。

/usage が表示するもう1つの数字、Pro・Max・Teamプランの利用上限は --max-budget-usd とは別物です。こちらはドル建てではなく、セッション枠・週次枠のような時間で区切られた消費枠で、上限に当たるとリセット時刻まで待つ挙動になります(自動再開の設定はClaude Codeの利用上限リセット後に自動再開する設定にまとめています)。--max-budget-usd はAPI従量課金の支出そのものに上限をかけるフラグで、サブスクリプションの利用枠を管理する仕組みではない点を混同しないようにします。

似た名前のフラグ・設定との違い

暴走を止める仕組みはこれだけではありません。何を基準に止めるかで使い分けます。

3つは互いに独立しており、どれか1つを設定してもほかの2つは効きません。無人実行を安全に回すには、金額・ターン数・同時実行数のうち何が読めなくなると困るかを考え、必要なものを組み合わせます。たとえば1回あたりの上限金額を決めたうえで、暴走的なツール呼び出しの繰り返しも止めたいなら、--max-budget-usd と --max-turns を同じコマンドに両方渡します。どちらか早く上限に達したほうの挙動が先に発生し、もう一方は評価されません。

claude -p --max-budget-usd 3.00 --max-turns 20 "query"

Claude APIのtask_budgetとは別物

Claude APIには task_budget という、エージェントループ全体のトークン消費の目安をClaudeに伝える機能もあります。名前は似ていますが性質が違い、task_budgetは強制されないadvisoryであり、Claudeが完了間際だと判断すれば予算を超えて処理を続けることがあります。対して --max-budget-usd はClaude Code側でドル建ての実支出を監視し、上限に達すればサブエージェントの起動そのものを機械的に止めるハードな上限です。「予算」という言葉が指すレイヤーが、APIリクエスト内のトークン配分(task_budget)なのか、Claude Codeのセッション課金額(--max-budget-usd)なのかを区別しておくと、どちらの設定を触ればよいか迷わずに済みます。

無人実行での組み込み方

CI・バッチ処理にClaude Codeを組み込む場合、金額の上限は「想定外に高額な請求が発生しない」ための最後の砦になります。Claude Codeのコスト管理で契約形態別の可視化を済ませたうえで、個々のジョブには --max-budget-usd で1回あたりの上限を明示しておくと、想定より複雑なタスクに当たってサブエージェントが増殖した場合でも支出が青天井にならずに済みます。

Claude Code v2.1.217では、この上限強制がバックグラウンドのサブエージェントにも及ぶよう修正されました。それ以前のバージョンでは、上限に達しても実行中のバックグラウンドサブエージェントが動き続けることがあり、フラグを設定していても支出が止まりきらないケースがありました。無人実行に --max-budget-usd を使うなら、v2.1.217以降で動かしているかを確認しておく価値があります。

よくある質問

上限に達した時点までの編集内容は残りますか

残ります。上限が止めるのはこれから先の新しいサブエージェント起動と、実行中のバックグラウンドサブエージェントの継続だけです。それまでにファイルへ加えた変更やコミットは、通常の中断と同様にそのままディスクに残ります。

上限金額はチームで共有した設定ファイルに書けますか

公式ドキュメントで確認できる指定方法はCLIフラグのみで、settings.json の env に書けるような対応する環境変数はありません。チームで同じ上限を使い回すには、コマンドを呼び出すスクリプトやCIのワークフロー定義側に埋め込む必要があります。

支出の内訳を後から確認できますか

印刷モードの実行結果そのものには内訳は出ません。対話セッションで事前に実測値を取りたい場合は、ステータスラインに cost.total_cost_usd を表示するか /usage を実行し、同じタスクを流したときにどれくらいの金額になるかを見てから --max-budget-usd の値を決めるのが確実です。

まとめ

--max-budget-usd は印刷モード限定でAPI課金額に上限をかけるCLIフラグで、サブエージェントの支出も合算対象です。上限到達時に公式が明記しているのは、新規サブエージェント起動の失敗と実行中バックグラウンドサブエージェントの停止の2点で、この強制はv2.1.217以降有効です。契約単価(modelPricing)がある組織では、上限判定もその単価で行われます。ターン数を止めたいなら --max-turns、同時実行数を絞りたいなら CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS と、止めたい対象で使い分けます。