Claude Codeのトークン消費が異常に速いときの原因の切り分け方

Claude Codeで「数分でクォータが尽きる」報告が相次いだ経緯

2026年3月24日、Claude CodeのGitHub Issueに「トークン計算とクォータ管理に重大な問題がある」という報告が投稿されました。数日で20件のコメントが付き、投稿者自身がRedditなど他のコミュニティでも幅広く議論になっていると書いています。

報告の中心は3つです。小さなプロンプトでも5時間分の利用枠を数十分で使い切る、Maxプランでも同様の現象が起きる、そしてセッションをアイドルにしていてもクォータが減っているように見える、というものです。あるコメントでは「いつもの4か月間は一度も上限に達したことがなかったのに、今日は突然作業ができなくなった」と書かれています。

一方でコメント欄には、消費速度が時間帯によって大きく変わるという報告も複数ありました。投稿者の一人は、当時実施されていたオフピーク時間帯の利用枠倍増キャンペーンの終了時期と、消費が跳ね上がる時間帯が重なっていた可能性を指摘しています。時間帯による変動は公式ドキュメントで仕組みを確認できません。

切り分けは/usageと/contextの実行から始める

原因を推測する前に、まず自分のセッションで何が起きているかを数字で確認します。/usageはセッション内のトークン内訳とコスト見積もりを表示するコマンドです。

/usage

/usageのSessionブロックには、モデルごとの入力・出力・キャッシュ読み取り・キャッシュ書き込みトークン数が表示されます。Pro・Maxプランの利用者にとってこの金額表示自体は課金対象ではありませんが、どの操作がどれだけのトークンを使ったかを見る材料にはなります。Claude Code v2.1.251以降では、これに加えてPrompt cache (main)という行が表示され、直近のリクエストのうち何%がキャッシュから読まれたか、何回キャッシュミスが起きたか、そのキャッシュが今も温かい(warm)状態かどうかが分かります。

さらに/usageの内訳には、直近の使用量をスキル・サブエージェント・プラグイン・個別のMCPサーバー別に分解した「Attribution」と、使用量の10%以上を占める挙動を検出する「Behavior flags」、/loopなどのスケジュールタスクごとの消費を並べた「Loops」も含まれます(それぞれClaude Code v2.1.242以降)。放置中の減少は、Loops行にスケジュールタスクの消費が出ていないかで切り分けられます。

コンテキストウィンドウの内訳を見るには/contextを使います。

/context

/contextを実行すると、CLAUDE.mdの内容やMCPツール定義がコンテキストのどれだけを占めているかを確認できます。セッションを開いた直後からトークン消費が速いと感じる場合は、まずここでCLAUDE.mdの行数やMCPサーバーの数を疑います。

もう一段深く、直近のセッションの使い方そのものを分析したい場合は/insightsが使えます。1回の実行で未分析の最大200セッションを解析し、作業内容や詰まりやすいポイントをまとめたHTMLレポートを生成します。ただしこの解析自体もトークンを消費し、対象はこのマシン上のセッションに限られます。

キャッシュミスとTTLの短縮が消費を跳ね上げる仕組み

Claude Codeは会話全体を毎リクエスト送信します。プロンプトキャッシュはその再送コストを抑える仕組みで、キャッシュが効いている限り、同じ内容は安いキャッシュ読み取り価格で再処理されます。問題はキャッシュが切れた瞬間です。

キャッシュの生存期間(TTL)には5分と1時間の2種類があり、Claude Codeはリクエストの種類ごとにどちらを使うかを自動で決めています。

サブスクリプションの利用枠内で使っている間はメインの会話に1時間のTTLが適用されますが、プランの利用上限を超えて追加使用量(usage credits)に切り替わった瞬間、Claude Codeはより安価な5分のTTLに自動的に切り替えます。長時間セッションを開いたままにしていて、途中で追加使用量に入った利用者ほど、それ以降はキャッシュが切れやすくなり、休憩から戻るたびに全履歴が非キャッシュ価格で再処理される計算になります。1時間のTTLを維持したい場合は、promptCacheTtl設定か環境変数で明示的に指定します。

export CLAUDE_CODE_PROMPT_CACHE_TTL=1h

サブエージェントはメインの会話とは別のTTLバケットに属し、サブスクリプションの利用枠内であっても既定は5分です。サブエージェントを多用する構成では、メインの会話よりも先にキャッシュが切れることになります。

/usageのPrompt cache行が「% of input tokens from cache」の低下や、ミスの直後に再キャッシュされたトークン数を示している場合、キャッシュミスが消費急増の主因である可能性が高くなります。詳しいコマンド節約の手順はClaude Codeのトークン節約にまとめています。

サブエージェントとAgent Teamsが消費を積み増す要因

サブエージェントは親のセッションとは別に、自分専用のシステムプロンプトとツールセットを持つ会話を新しく開始します。最初のリクエストは親のキャッシュを読めないため、非キャッシュ価格でウォームアップし、以降は自分自身のキャッシュを積み上げていきます。サブエージェントを何本も並行して起動する構成では、親のセッション1本分だけでなく、サブエージェントの数だけコンテキストウィンドウが並走することになります。

Agent Teamsはこれをさらに拡張した機能で、複数のClaude Codeインスタンスをチームメイトとして同時に立ち上げます。公式ドキュメントは、チームメイトが計画モード(plan mode)で動作している場合、Agent Teamsは通常セッションのおよそ7倍のトークンを消費すると明記しています。理由は単純で、各チームメイトが自分専用のコンテキストウィンドウを持ち、独立したClaude Codeインスタンスとして動くためです。

チームメイトはCLAUDE.md・MCPサーバー・スキルを自動で読み込みます。スポーンプロンプトに書いた内容もすべて、その時点からチームメイトのコンテキストに積み上がります。さらに、稼働中のチームメイトは作業が終わって終了するかセッションが終わるまでトークンを消費し続けます。作業が終わったのに立ち上げっぱなしのチームメイトが残っていないか、/usageのattributionで確認する価値があります。

チームの規模を絞り込む・スポーンプロンプトを簡潔にする・作業終了後にチームメイトを明示的に終了させる、という3点が消費を抑える基本です。設定の詳細はAgent Teamsのコスト管理で扱っています。

MCPサーバーとCLAUDE.mdの肥大がコンテキストを圧迫する

MCPサーバーのツール定義は既定で遅延読み込みされ、Claudeが実際にそのツールを使うまではツール名とサーバーの説明文だけがコンテキストに入ります。とはいえ、接続しているMCPサーバーの数が多いほど、この「名前と説明文だけ」の部分も積み上がります。/contextを実行すると、この内訳が実際にどれだけのスペースを占めているかを確認できます。

/usageのattributionには、MCPサーバーごとの使用割合も表示されます。ただしClaude Code v2.1.222より前のバージョンには既知の不具合があり、あるMCPサーバーへの呼び出しが1回発生すると、それ以降のすべてのリクエストがそのサーバーに帰属してしまい、実際の使用割合を過大に見せていました。古いバージョンを使っている場合、attributionの数字を鵜呑みにする前にバージョンを確認します。

CLAUDE.mdはセッション開始時に毎回コンテキストへ読み込まれます。特定のワークフロー(PRレビューやデータベースマイグレーションなど)向けの詳細な手順をCLAUDE.mdに書いていると、それと無関係な作業をしているときもそのトークンは常に存在し続けます。公式ドキュメントは、CLAUDE.mdを200行程度に抑え、特定のワークフロー向けの知識はオンデマンドで読み込まれるスキルに移すことを勧めています。MCPサーバーのトークンオーバーヘッドを抑える具体的な設定はMCPのトークンオーバーヘッドを抑える設定にまとめました。

Extended Thinkingとモデル選択が出力トークンを押し上げる

Extended Thinkingは既定で有効になっており、複雑な計画やマルチステップの推論タスクでの性能を大きく改善します。ここで見落とされがちなのは、思考トークンが出力トークンとして課金される点です。デフォルトの思考予算はモデルによって数万トークンに達することがあり、単純なタスクであってもこの予算が丸ごと使われれば、それだけで出力トークンの消費が跳ね上がります。

固定思考予算を持つモデルではMAX_THINKING_TOKENS環境変数で予算を下げられますが、適応的推論(adaptive reasoning)を採用しているモデルはゼロ以外の固定予算を無視するため、そちらでは/effortや/modelでエフォートレベルを調整します。Fableモデルは常にExtended Thinkingを使う設計になっており、無効化はできません。

モデル選択も直接的な要因です。Issueの起票者もモデルにOpusを使っていました。公式ドキュメントは、Sonnetがほとんどのコーディングタスクをこなせて費用も安く、Opusは複雑なアーキテクチャ判断やマルチステップ推論に絞って使うことを勧めています。サブエージェントの設定でmodel: haikuを指定できる単純作業には、より軽いモデルを割り当てる余地もあります。

Compaction自体が大きなリクエストになる落とし穴

コンテキストウィンドウがauto-compactの閾値に近づくと、Claude Codeは古い履歴を要約してスペースを空けます。この圧縮(compaction)は、要約対象の会話全体を読み込んだうえで要約を生成するリクエストであるため、それ自体が大きなAPIリクエストになります。

特に影響が大きいのは、長い休憩のあとに大きなセッションを再開したときです。休憩がキャッシュの生存期間を超えていると、キャッシュに残っているものがないため、圧縮リクエストは会話全体を非キャッシュ価格で再処理します。Pro・Maxプランでは、長時間放置した大きなセッションを再開する際にサマリーからの再開を提案する仕組みがありますが、これを使わずにTTLを超えた休憩のあとに手動で/compactを実行すると、会話全体を非キャッシュ価格で読み直す処理になります。圧縮を会話の途中で明示的に止めてトークン予算を守る実装パターンはCompactionの一時停止で合計トークン予算を強制する実装パターンで扱っています。

なお/compactに何を残すかを指示するカスタム圧縮指示(/compact Focus on code samples and API usageのような形、あるいはCLAUDE.mdの# Compact instructionsセクション)を設定しておくと、圧縮そのものの精度は上がりますが、圧縮リクエスト自体が大きくなる問題は解消しません。無関係な作業に切り替えるときは、圧縮よりも/clearの方がコストがかかりません。

アイドル中の消費は本当にゼロにならない

GitHub Issueで報告された「アイドルにしているのにクォータが減る」という現象について、公式ドキュメントはバックグラウンド処理による消費の存在を認めています。Claude Codeはアイドル中でも一部のバックグラウンド機能のためにトークンを使っており、この消費は1セッションあたり0.04ドル未満が目安とされています。

この金額の小ささを踏まえると、報告にあったような数十%規模の急減は、純粋なバックグラウンド処理だけでは説明しにくい規模です。/usageのLoops行を確認すると、/loopやその他のスケジュールタスクが定期的に実行されていないかが分かります。セッションを開いたまま気づかないうちにスケジュールタスクを走らせていた、というケースはここで切り分けられます。

症状別に原因を絞り込む早見表

どの原因を優先して疑うべきかは、症状によって変わります。

報告の背景にあるのは単一のバグより仕組みの重なり

GitHub Issueに集まった報告を仕組みの側から読み直すと、単一の欠陥というより、複数の正常な挙動が同じタイミングで重なった結果に見えるケースが多くなります。長時間開いたセッション、追加使用量への切り替わりによるTTLの短縮、Opusでの利用、稼働したままのサブエージェント。これらは個別に見ればすべて公式ドキュメントに明記されている仕様どおりの動作です。

だからといって、報告そのものが的外れだったとは限りません。5時間分の利用枠を数十分で使い切るという体感は、複数の要因が重なったときには実際に起こり得ます。重要なのは、原因を「バグ」と決めつけて待つのではなく、/usageと/contextで自分のセッションの内訳を見て、どの仕組みが効いているかを特定することです。原因が分かれば、TTLの明示指定・チーム規模の調整・CLAUDE.mdの整理・モデルの使い分けのどれかで対処できます。

まとめ

Claude Codeのトークン消費が急に速くなったと感じたら、まず/usageでキャッシュのヒット率とattributionを、/contextでコンテキストの内訳を確認します。キャッシュミス(特にTTLが5分に切り替わっている場合)、サブエージェントやAgent Teamsの並走、MCPサーバーとCLAUDE.mdの肥大、Extended Thinkingや高価なモデルの選択、そして圧縮そのものの再処理コストが、公式ドキュメントで確認できる主な要因です。アイドル中の消費については、純粋なバックグラウンド処理は小さいため、/loopなどのスケジュールタスクが動いていないかを合わせて確認します。単一の原因を探すより、これらを一つずつ/usageの内訳と突き合わせる方が、実際の切り分けには近道です。