powered by TechFeed
表示モード
ハウツー

Claude Codeには「予算超過で自動停止」する機能がない — 暴走AIエージェントのコストを制御する3層防御の設定法

11月19日、Nirmataが「How to set budget alerts for a runaway AI agent」と題した記事を公開した。AIエージェントが意図せず大量のAPIリクエストを発行し、月数万円規模の請求が発生したという報告はRedditやHacker Newsで散見されるようになっており、コスト暴走はAIコーディングツールの実運用における現実的なリスクとなっている。Claude Codeに限らず、GitHub CopilotやCursorといったツールもバックエンドのAPIコストが使い方次第で膨らむ構造は同様だが、なかでも自律的にタスクをこなすエージェントモードを持つClaude Codeは、その性質上コスト制御の仕組みを明示的に設定しておく必要がある。本記事では、Claude Codeで暴走したAIエージェントの支出を制御するための予算アラートおよびキャップの設定方法を詳しく紹介する。

11月19日、Nirmataが「How to set budget alerts for a runaway AI agent」と題した記事を公開した。AIエージェントが意図せず大量のAPIリクエストを発行し、月数万円規模の請求が発生したという報告はRedditやHacker Newsで散見されるようになっており、コスト暴走はAIコーディングツールの実運用における現実的なリスクとなっている。Claude Codeに限らず、GitHub CopilotやCursorといったツールもバックエンドのAPIコストが使い方次第で膨らむ構造は同様だが、なかでも自律的にタスクをこなすエージェントモードを持つClaude Codeは、その性質上コスト制御の仕組みを明示的に設定しておく必要がある。本記事では、Claude Codeで暴走したAIエージェントの支出を制御するための予算アラートおよびキャップの設定方法を詳しく紹介する。


Claude Codeには「自動停止」機能がない

まず知っておくべき事実がある。Claude Codeのドキュメントには、支出に対するビルトインの予算アラートも自動キルスイッチも存在しない。

設定リファレンスにautoContinueAtUsageLimitというエントリはあるが、これは上限に達した後でセッションを再開する設定であり、停止するものではない。modelPricing設定はコスト表示の計算方法を変えるだけで、上限を設けるものではない。

75%および95%の使用量に達したとき、Claude Codeは警告を出す。しかしこの警告はエージェントを実行しているその開発者本人に届くだけで、予算を管理するチームには届かない。


多層防御で「暴走エージェント」を封じ込める

記事が提示する対策は、以下の3層を組み合わせることだ。

1. OpenTelemetryのコストカウンターでアラートを設定する(最重要)

OpenTelemetry(OTel)とは、分散システムにおけるトレース・メトリクス・ログを収集・エクスポートするためのオープンな標準仕様だ。ベンダー非依存で、PrometheusやDatadog、Grafana Cloudなど主要なモニタリングバックエンドへデータを流し込める。Claude CodeはこのOTelに対応しており、APIコストをリアルタイムにメトリクスとして外部に送出できる。

Claude Codeは2つのメトリクスをエクスポートする。

  • **claude_code.cost.usage**:USD単位のコスト
  • **claude_code.token.usage**:トークン数

どちらもAPIリクエストごとにインクリメントされる。これらを自前のモニタリングスタック(Prometheus + Grafana、Datadogなど)に流し込むことで、アラートルールを書ける。

テレメトリを有効にするには以下の環境変数を設定する:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

ポート4317はgRPC用だ。エンドポイントがhttp://の場合、プロトコルのデフォルトはhttp/protobufになるため、**OTEL_EXPORTER_OTLP_PROTOCOL=grpcを明示的に指定する必要がある。この環境変数はClaude Code v2.1.323以降**が必要。

アラートを早めに発火させたい場合はエクスポート間隔を短縮する(デフォルトは60,000ms):

export OTEL_METRIC_EXPORT_INTERVAL=10000

メトリクスバックエンドでアラートを設定する際の注意点が一つある。開発者ごとにグルーピングするときは**user.account_uuidを使うこと**。user.idはファーストラン時に生成される匿名識別子で~/.claude.jsonに保存されるため、同じ開発者が2台のマシンを使うと別々のシリーズになってしまう。

2. --max-budget-usdフラグでスクリプト実行を上限付きで動かす

プリントモード(-p)での実行にのみ使えるフラグだ。インタラクティブセッションには対応していない:

claude -p --max-budget-usd 5.00 "query"

動作上の注意点が3つある:

  • サブエージェントの支出も上限にカウントされる
  • 上限到達後にサブエージェントを生成しようとするとBudget limit reachedエラーになる
  • --continueや--resumeで復元した場合、過去の支出は上限カウントに含まれない
  • 支出が上限を超過してから停止するため、余裕を持った値を設定すること

この機能はClaude Code v2.1.217以降が必要。

3. ゲートウェイで開発者ごとにドル上限を設定する

セルフホストのClaude appsゲートウェイを使っている場合、個人・グループ・組織単位で日次・週次・月次の支出上限を設定できる。上限に達すると後続リクエストに429が返る。

ゲートウェイのドル数値はドキュメントが「サーキットブレーカー」と呼ぶ推定値であり、請求書の金額とは異なる。上限を設定する前にプロバイダーの使用量レポートと照合することが推奨されている。


各レイヤーの対応表

レイヤー 何を制限するか 利用できるコントロール
実行単位の上限 1回のプリントモード実行 --max-budget-usd
開発者ごとのドル上限 期間中の個人支出 ゲートウェイ or Team/Enterprise制限
スループット 分あたりのトークン・リクエスト Claude ConsoleのWorkspaceレート制限
ドリフト検知 事後のコスト・トークンスパイク claude_code.cost.usageなどOTelメトリクス
アラート連動の自動停止 — ドキュメントに記載なし

最後の行が肝だ。アラートが発火したときに自動で停止する仕組みは、Claude Codeのドキュメントには存在しない。 必要なら自前のオートメーションで実装し、本番投入前に実際の実行でテストする必要がある。なお表の内容はあくまで各レイヤーの役割を整理したものであり、実際の設定手順は上述の各セクションを参照されたい。


今すぐエージェントを止めたい場合

ドキュメントが示すコース修正手順は単純だ。Escapeキーを押して即座に停止する。ロールバックには/rewindコマンド、またはEscapeをダブルタップして会話とコードを以前のチェックポイントに戻す。


詳細はHow to set budget alerts for a runaway AI agentを参照していただきたい。