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コメントを一覧化して"

v2.1.289で claude --help を実行すると、このフラグは次のように表示されます。

claude --help | grep -A1 max-budget-usd

  --max-budget-usd <amount>             Maximum dollar amount to spend on API
                                        calls (only works with --print)

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

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

CLIリファレンスが上限到達時の動作として挙げているのは2つです。どちらもサブエージェントに対する挙動で、v2.1.217以降で強制されます。

Agent SDKの側には、結果メッセージの subtype が error_max_budget_usd になるケースがあります。このとき usage は上限を超えた応答を含まず、total_cost_usd と modelUsage は含みます。上限を一度に飛び越える応答があり得るので、金額は「ちょうどこの額で止まる」値ではなく、おおよその天井として扱います。

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

ここでいう「バックグラウンドのサブエージェント」は、セッション全体をバックグラウンドエージェントとして起動する --bg(--background)とは別の概念です。--bg は -p(--print)と組み合わせられないため、印刷モード限定の --max-budget-usd を --bg のセッションには指定できません。上限をかけたいなら、-p を使った通常の印刷モード実行を選びます。

再開した会話の支出は合算されない

--continue や --resume で前の会話に戻ると、前回までの合計は --max-budget-usd の判定に入りません。CLIリファレンスの記述は「復元された合計は上限に数えない」です。同じ会話を何度も再開するジョブでは、1回ごとに5ドルの枠が新しく与えられ、会話全体の累計が5ドルで止まるわけではありません。

一方、--output-format json の結果に入る total_cost_usd には、再開元の支出が含まれます。上限の判定対象と報告される数字の範囲が違うので、月次の支出を集計するスクリプトでは、どちらの数字を見ているかを揃えます。

Agent SDKでも同じ扱いで、maxBudgetUsd(Pythonでは max_budget_usd)はその呼び出し自身の支出だけを数えます。SDKでは /clear を挟むと予算も数え直しになります。

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

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

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

中身は multiplier(全モデルに一律で掛ける倍率。1未満は割引、1超は割増。割増はv2.1.271以降で、それより前の版は警告を出して無視します)と overrides(モデルごとの単価表)の組み合わせで、--max-budget-usd が見る金額もこの2つを適用した後の数値です。データレジデンシー(米国内推論)の対象ワークスペースでは1.1倍のプレミアムもコスト見積もりに入ります。これは --max-budget-usd の判定にも反映され、v2.1.239以降の挙動です。ただし overrides の行にあるモデルは書いた単価がそのまま使われ、ファストモードの割増や米国内推論の単価は上乗せされません。上限の計算が想定とずれるときは、管理設定とデータレジデンシーの有無から疑います。

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

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

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

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

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

--max-turns は既定で上限なしで、到達するとエラー終了します。--input-format stream-json と組み合わせた場合、上限に達したときキューに残っていたメッセージは、新しいターンとして独自の上限つきで始まります。金額の上限とは数え方が違い、長時間のストリーム処理では挙動を取り違えやすい部分です。

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のコスト管理にまとめてあります。そのうえで、ジョブへの組み込みは次の順で進めます。

まとめ

--max-budget-usd は、印刷モードの無人ジョブに置く金額の天井です。再開した会話の過去分は数えないので、会話全体の累計を縛りたいなら別の集計が要ります。