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

Claude Codeのトークン消費が速いときは、まず/usageでキャッシュミスの有無を、/contextでCLAUDE.mdとMCPの占有量を見ます。原因の多くは、キャッシュの有効期限切れ、サブエージェントやAgent Teamsの並走、MCPとCLAUDE.mdの肥大、Extended Thinkingの出力のどれかです。節約の具体策は、原因が絞れてから選ぶほうが外れません。

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

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

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

一方でコメント欄には、消費速度が時間帯によって大きく変わるという報告も複数ありました。投稿者の一人は、当時実施されていた利用枠倍増キャンペーンが適用されない朝の時間帯(太平洋時間5〜11時)と、上限に達する時刻が一致していると指摘しています。

別のコメントには、平日の太平洋時間5〜11時に5時間枠の減りを速めたというAnthropicの告知が引用されています。週の上限は据え置きとされていますが、これはIssueコメントでの引用で、告知の原文は示されていません。起票者のモデル欄はOpusです。

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

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

/usage

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

プラン利用枠の内訳には3つの見出しがあります。Attributionはスキル・サブエージェント・プラグイン・個別のMCPサーバーごとの割合、Behavior flagsは直近の使用量の10%以上を占める挙動(長いコンテキストやキャッシュミスなど)です。Loopsは/loopなどのスケジュールタスクを、消費の大きい順に並べた行になります(Loopsはv2.1.242以降)。

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

/context

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

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

手元のClaude Code v2.1.285で、エフォートをセッション単位で指定できることも確認しました。

claude --version
claude --help | grep -i effort

出力は次のとおりです(--helpの該当行のみ抜粋)。

2.1.285 (Claude Code)
  --effort <level>                      Effort level for the current session

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

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

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

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

export CLAUDE_CODE_PROMPT_CACHE_TTL=1h

サブエージェントはメインの会話とは別のTTLバケットに属し、サブスクリプションの利用枠内でも既定は5分です。プロセス内のチームメイト、ワークフロー、フォーク、圧縮、セッションタイトルの生成も、このバケットに入ります。多用する構成では、メインの会話よりも先にキャッシュが切れます。このバケットにもsubagentPromptCacheTtl設定とCLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL環境変数があり、APIキーで使う場合はpromptCacheTtlだけ1hにしてもサブエージェント側は5分のままです。

Prompt cache行でキャッシュ読み取りの割合が低く、Behavior flagsにキャッシュミスが出ているなら、消費急増の主因である可能性が高くなります。詳しいコマンド節約の手順はClaude Codeのトークン節約にまとめています。

セッション中の設定変更でキャッシュが切れる場合と切れない場合

TTLとは別に、キャッシュキーそのものが変わる操作があります。モデルごとにキャッシュは別なので、同じ内容でも/modelで切り替えた次のリクエストは会話全体を再計算します。ファストモードを初めてオンにする、ツールを丸ごと拒否する(Bashのような裸のツール名のdenyルール)操作も同じ扱いです。

MCPサーバーの接続・削除は、ツール定義が遅延読み込みされる既定の構成ではキャッシュを切りません。切れるのは、tool searchが使えずツール定義を最初から読み込む構成(カスタムANTHROPIC_BASE_URLのゲートウェイなど)です。プラグインもMCPサーバーを含むものだけが同じ規則に従います。

エフォートレベルの変更は、モデルで結果が分かれます。

Opus 5.5とSonnet 5.5の既定のエフォートはmediumで、ほかの対応モデルはhighです(Opus 4.7だけはxhigh)。深い推論が要らない作業で下げるときも、モデルによってはキャッシュとの引き換えになる点を頭に置いておくと、切り分けがつきやすくなります。

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

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

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

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

チームの規模を絞り込む・スポーンプロンプトを簡潔にする・作業終了後にチームメイトを明示的に終了させる、という3点が消費を抑える基本です。チームメイトにはSonnetを使う手もあります。

プロセス内のチームメイトのリクエストは、メインの会話とは別のTTLバケットに入ります。subagentPromptCacheTtlを1hにする選択肢もあります。設定の詳細はAgent Teamsのコスト管理で扱っています。

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

MCPサーバーのツール定義は既定で遅延読み込みされ、Claudeが実際にそのツールを使うまではツール名とサーバーの指示文(server instructions)だけがコンテキストに入ります。とはいえ、接続している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は既定で有効になっており、複雑な計画やマルチステップの推論タスクでの性能を大きく改善します。ここで見落とされがちなのは、思考トークンが出力トークンとして課金される点です。既定の予算はモデルによって1リクエストあたり数万トークンに達することがあります。簡単な作業でも考えさせすぎると、その分が出力の消費に上乗せされます。

固定思考予算を持つモデルではMAX_THINKING_TOKENS環境変数で予算を下げられます(公式の例はMAX_THINKING_TOKENS=8000)。適応的推論(adaptive reasoning)のモデルはゼロ以外の固定予算を無視するので、そちらでは/effortか/modelでエフォートレベルを調整します。Opus 5.5・Sonnet 5.5・Fableモデルは常にExtended Thinkingを使う設計で、無効化できません。

モデル選択も直接的な要因です。公式ドキュメントでは、Sonnetがほとんどのコーディングタスクをこなせて費用も安く、Opusは複雑なアーキテクチャ判断やマルチステップ推論に絞るとされています。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ドル未満が目安とされています。

応答のあとに次の入力を提案する短いリクエストも送られます。中心はキャッシュ読み取りで、オフにできます。

この金額の小ささを踏まえると、数十%規模の急減は、純粋なバックグラウンド処理だけでは説明しにくい規模です。公式ドキュメントは、アイドル中でも会話の全コンテキストを再送するリクエストが走る例を3つ挙げています。

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

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

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

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

ただし、実際の不具合もありました。遅延ツール、MCPサーバー、カスタムエージェントを使う環境では、v2.1.69から続く--resume直後のキャッシュ全外しの回帰があり、v2.1.90で修正されています。

だからといって、報告が的外れだったとは限りません。5時間分の利用枠を数十分で使い切る体感は、複数の要因が重なれば実際に起こり得ます。

まとめ

原因を1つに決めて待つより、/usageと/contextの内訳に上の要因を1つずつ当てる方が早く絞れます。効いている仕組みが分かれば、TTLの明示指定、チーム規模の調整、CLAUDE.mdの整理、モデルとエフォートの使い分けのどれで対処するかも決まります。