Manage costs effectively

概要

Claude Code は API のトークン消費で課金される。トークン使用量の確認方法、組織単位の支出管理、トークン使用量を減らす仕組みを扱う。

仕様

`/usage` コマンド

/usage 上部の Session ブロックが現在のセッションのトークン使用統計を表示する
ドル額はトークン数を標準の list rate で価格付けしてローカル計算したもの。プロモーション価格や契約割引は反映されず、実際の請求と異なりうる。正式な請求は Claude Console の Usage ページ
/clear で新しいセッションを始めると合計がリセットされ、次のセッションの total cost は $0 から始まる。v2.1.211 より前は Claude Code プロセスの生存中 /clear をまたいで積算されていた
Session ブロックは API ユーザー向け。Claude Max / Pro のサブスクリプションでは使用量が契約に含まれるため、セッションのコスト額は請求上は関係しない

表示例:

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

plan usage breakdown

Pro / Max / Team / Enterprise プランでは、プラン上限に対する内訳も表示される。

Attribution: 直近の使用量を skill / subagent / plugin / 個々の MCP サーバーに帰属させ、それぞれ全体に対する割合で表示する。MCP サーバーの取り分は、そのツール結果を消費したリクエストのみを数える。v2.1.222 より前は、あるサーバーを 1 回呼ぶと以降のすべてのリクエストをそのサーバーに帰属させ、割合を過大表示していた
Behavior flags: long context や cache miss などの挙動が直近使用量の 10% 以上を占める場合にフラグを立てる
d / w キーで直近 24 時間と直近 7 日を切り替える
数値は概算で、このマシンのローカルセッション履歴から計算する。他デバイスや claude.ai の使用量は含まれない
VS Code 拡張では同じ内訳が Account & usage ダイアログに Day / Week トグル付きで表示される。v2.1.174 以降が必要

使用量取得に失敗した場合

プラン上限の取得に失敗した場合（多くは usage endpoint のレート制限）、このマシンで直近 60 分以内に読み込んだ最後の usage バーと Showing last-known usage の注記（取得からの経過時間付き）を表示する
r で再試行する。成功すると新しいデータに置き換わる
直近 60 分のスナップショットが無い場合は、usage endpoint がレート制限されている旨を報告し、同じ再試行ショートカットを提示する
v2.1.208 より前は、まだ usage を読み込んでいないセッションでレート制限されると常にバー無しのエラー表示だった

`/usage-credits`

/login で claude.ai のサブスクリプションにサインインした後に使える。API キー認証では使えない。

役割	`/usage-credits` の動作
Pro / Max subscriber	ブラウザで課金設定を開く
課金権限のある Team / Enterprise メンバー	ブラウザで組織の usage 設定を開く
課金権限のない Team / Enterprise メンバー	確認を求めたうえで組織の管理者にリクエストを送る。v2.1.211 より前は確認なしに送信していた

課金権限の無い Team / Enterprise メンバーの確認は対話セッションでのみ表示される。-p の非対話モードと Remote Control ではリクエストを送らず、対話セッションで実行するよう伝える
先のリクエストが管理者待ちの間に再実行すると、重複送信せず送信済みである旨を伝える。管理者が却下した後に再実行すると新しいリクエストを送る。v2.1.222 より前は却下されたリクエストも新規送信をブロックしていた
Pro / Max プランで usage credit が残っている状態で spend limit に達すると、CLI から離れずに上限を引き上げ・解除するプロンプトが出る

組織単位の支出管理

構成	支出の確認	上限の設定	ユーザー別レポート
Claude for Teams / Enterprise	org analytics の spend report	admin settings の spend limits	spend report CSV、Enterprise では Enterprise Analytics API
Claude Console (API)	Console の usage ページ	workspace spend limits	Console dashboard、Claude Code Analytics API
Amazon Bedrock / Google Cloud's Agent Platform / Microsoft Foundry	各クラウドの課金コンソール	各クラウドの予算管理	OpenTelemetry または LLM gateway

Teams / Enterprise プランでは各メンバーの seat allowance から消費される。Console とクラウドプロバイダではトークン単位で組織に課金される
組織内でサインイン方式が混在する場合、各開発者は認証した方式に従って計測される
OpenTelemetry export はどの構成でも使え、ユーザー別のトークン・コスト指標をほぼリアルタイムに自前の observability スタックへ流せる唯一の選択肢

Claude for Teams / Enterprise

各メンバーの使用量は per-seat allowance から引かれ、5 時間のローリングウィンドウと週次ウィンドウでリセットされる
allowance は Claude chat と Cowork と共有され、大きさは seat tier（Standard / Premium）に依存する
管理は claude.ai の admin console 側（Claude Console ではない）
spend report はユーザー別・モデル別の推定支出を日次更新で示し、CSV エクスポートできる。usage credit の支出を対象とし、usage credit を有効にすると表示される。seat allowance 内の使用量はドル計測されない
Enterprise では Enterprise Analytics API がユーザー別の使用量・コストを返す。Primary Owner が read:analytics スコープのキーを作成する

Claude Console

Claude Console アカウントで初めて認証すると "Claude Code" という workspace が自動作成される。この workspace の API キーは作成できず、Claude Code の認証と使用専用
カスタムレート制限のある組織では、この workspace の Claude Code トラフィックが組織全体の API レート制限に算入される。workspace の Limits ページで workspace rate limit を設定できる

レート制限の推奨値（ユーザーあたり）:

チーム規模	TPM per user	RPM per user
1-5 users	200k-300k	5-7
5-20 users	100k-150k	2.5-3.5
20-50 users	50k-75k	1.25-1.75
50-100 users	25k-35k	0.62-0.87
100-500 users	15k-20k	0.37-0.47
500+ users	10k-15k	0.25-0.35

これらのレート制限は個人単位ではなく組織単位で適用される

クラウドプロバイダ

Amazon Bedrock / Google Cloud's Agent Platform / Microsoft Foundry ではクラウドアカウントにトークン単位で課金され、支出管理はクラウド側の課金コンソールで行う
Claude Code はクラウドからのメトリクスを Anthropic に送らないため、analytics ダッシュボードと Claude Code Analytics API はこの使用量を扱わない
ユーザー別のコスト帰属手段: OpenTelemetry、self-hosted の Claude apps gateway、LLM gateway

上限メッセージの種類

You've hit your session limit / You've hit your weekly limit: サブスクリプションプランの seat ベースの使用ウィンドウ。全モデル共通のため /model でモデルを切り替えてもアクセスは戻らない。ただしモデル固有の You've hit your Opus limit の後は作業を続けられる。メッセージにはウィンドウのリセット時刻が表示される
context / auto-compact の警告: 使用量の上限ではない。会話がセッションの auto-compact ウィンドウに近づいた状態
API / クラウドプロバイダプランでの想定外の高額支出: 長時間クリアしていないセッション、または Opus を既定モデルのままにしていることに起因することが多い

トークン使用量を減らす仕組み

Claude Code は prompt caching（システムプロンプトなど繰り返し内容のコスト低減）と auto-compaction（コンテキスト上限に近づいたときの会話履歴の要約）で自動的にコストを最適化する
コンテキスト管理: /usage で現在の使用量を確認する。status line に継続表示する設定もある。/clear で無関係な作業に切り替える。/rename してから clear すると後で /resume で戻れる
compaction への指示: /compact Focus on code samples and API usage のように保持対象を指定する。新規セッションでは要約する履歴が無いため Not enough messages to compact. を出力する。CLAUDE.md に # Compact instructions の節を書いても指定できる
モデル選択: /model でセッション中に切り替える、/config で既定を設定する。単純な subagent タスクには subagent 設定で model: haiku を指定する
MCP のオーバーヘッド削減: MCP のツール定義は既定で deferred で、Claude が特定のツールを使うまでツール名だけがコンテキストに入る。/context で消費を確認し、/mcp で未使用サーバーを無効化する。CLI ツール（gh / aws / gcloud / sentry-cli など）はツール一覧を追加しないぶんコンテキスト効率が高い
code intelligence plugin: 型付き言語でシンボルナビゲーションを提供し、不要なファイル読み取りを減らす。導入した language server は編集後に型エラーを自動報告する
hook / skill への切り出し: hook は Claude が見る前にデータを前処理できる。skill はドメイン知識を与えて探索を減らす
CLAUDE.md から skill への移動: CLAUDE.md はセッション開始時にコンテキストへ読み込まれる。skill は呼び出し時にのみ読み込まれる。CLAUDE.md は 200 行未満を目安にする
extended thinking の調整: 既定で有効。thinking トークンは output token として課金され、既定の予算はモデルによっては 1 リクエストあたり数万トークンになりうる。/effort または /model で effort level を下げる、/config で thinking を無効化する、fixed thinking budget のモデルでは MAX_THINKING_TOKENS 環境変数で予算を下げる（例: MAX_THINKING_TOKENS=8000）。adaptive-reasoning のモデルは 0 以外の予算を無視するため effort level を使う。Fable 5 では thinking の無効化はできない（常に extended thinking を使う）
subagent への委譲: テスト実行・ドキュメント取得・ログ処理などの冗長な出力を subagent のコンテキストに閉じ込め、要約だけをメイン会話に返す
plan mode: Shift+Tab で plan mode に切り替える

agent team のコスト

agent team は複数の Claude Code インスタンスを起動し、それぞれが独自のコンテキストウィンドウを持つ。トークン使用量はアクティブな teammate の数と稼働時間に比例する
teammate が plan mode で動く場合、標準セッションのおよそ 7 倍のトークンを使う
teammate は CLAUDE.md、MCP サーバー、skill を自動で読み込む。spawn prompt の内容は最初からコンテキストに加算される
各 teammate は終了するかセッションが終わるまでトークンを消費し続ける
agent teams は既定で無効。settings.json または環境変数で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定すると有効になる

バックグラウンドのトークン使用

アイドル時でも次の用途でトークンを使う。通常は 1 セッションあたり $0.04 未満。

Conversation summarization: claude --resume のために過去の会話を要約するバックグラウンドジョブ
Command processing: /usage など一部のコマンドが状態確認のリクエストを発生させる

長時間セッションで使用量が増える理由

Long context: 毎リクエストで会話全体を送り、ツール使用のたびにツール結果を含む別のリクエストを送る。prompt caching により履歴は cached token rate で再読される
Cache misses: cache lifetime を超える中断後の最初のメッセージはキャッシュを外し、コンテキスト全体を再処理する。lifetime はサブスクリプションでは 1 時間、usage credit を使い始めると 5 分に下がる。API キーやクラウドプロバイダでは既定 5 分。ENABLE_PROMPT_CACHING_1H=1 を設定すると usage credit 使用中も 1 時間の lifetime を保てる
Scheduled tasks: セッションがアイドルでも間隔ごとに発火し、そのたびにコンテキスト全体を送る
Cross-session messages: 他セッションからのメッセージがアイドル時に新しいターンとして配信され、そのたびにコンテキスト全体を送る。crossSessionInbound を hold にすると配信せず保留する
Agent teammates: アクティブな teammate は終了するまでトークンを消費し続ける
Compaction: /compact は要約対象の会話を読むため、大きなコンテキストの compact 自体が大きなリクエストになる。/clear はコストがかからない

設定

hook で Claude が見る前に出力を絞り、コンテキスト消費を減らす例（テスト出力から失敗だけを残す PreToolUse hook）:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

制約・注意点

エンタープライズ導入全体での平均コストは、開発者 1 人あたりアクティブ日で約 $13、月あたり $150-250。ユーザーの 90% はアクティブ日あたり $30 未満
claude --version で現在のバージョンを確認する。バージョンによりコスト報告を含む挙動が変わりうる