Claude Codeのトークン使用量を減らす：Context ModeとHeadroom

Claude Codeのトークン使用量を減らすには、まず何がコンテキストを埋めているかを確認し、不要なツール出力が会話に入るのを防ぎます。最初はClaude Codeの標準機能を使い、必要な情報だけを処理して圧縮後も作業を続けたい場合はContext Mode、ローカルプロキシ経由で出力を圧縮したい場合はHeadroomを試してください。推論や失敗した試行の繰り返しが使用量の大半を占めるなら、どちらかを導入する前に、タスクの範囲とモデルの選び方を見直します。

2026-10-21時点のClaude Codeの現行リリースは2.1.306です。以下のHeadroomの導入手順では、バージョンを0.41.0に固定しています。

Claude Codeのトークンは何に使われているか

コンテキストの占有状況は/context、使用量と推定費用は/usageで確認します。この2つのコマンドで分かることは異なります。

確認したいこと	確認方法	分かること
なぜ会話のコンテキストが埋まるのか	/context	指示、メッセージ、ツール、その他の情報が占める領域
このセッションでどれだけ消費したか	/usage	トークンの分類別使用量とセッションの推定費用
サブスクリプションの利用枠に近づいているか	/usage内のプラン情報	プランの使用状況。APIの請求とは別の指標
実際にいくら請求されたか	課金を行うプロバイダーの利用明細	そのプロバイダーの料金と課金ルールを適用した請求額

現在のClaude Codeでは、/costは/usageの別名です。ドル表示の金額は推定値であり、ProやMaxの利用枠に含まれるリクエストのたびに、その金額が追加請求されるという意味ではありません。この違いはClaude Codeの費用に関するドキュメントに説明されています。

大きなログ、ブラウザーのスナップショット、依存関係のファイル、繰り返し返されるツールの結果は、コンテキストの多くを占めることがあります。過去のメッセージも後続のリクエストに含まれますが、プロンプトキャッシュによって、再利用する入力は新規の入力より安くなる場合があります。したがって、目に見える内容を50%減らしても、請求額が自動的に50%下がるわけではありません。

圧縮ツールを追加する前に標準機能を使う

無駄が生じる原因に合わせて対策を選びます。不要な出力が多いなら取得範囲を絞り、無関係な作業に移るなら新しい会話を始め、長いタスクを続けるならコンテキストを要約するコンパクションを使います。

Claudeには正確なファイルパス、失敗しているテストの名前、具体的な検証コマンドを渡してください。小さな変更の前にリポジトリ全体を理解するよう頼むより、問題のあるモジュールを1つ指定して調べてもらう方が、通常は不要な作業を減らせます。

無関係なタスクに切り替えるときは、必要な使用量の数値を記録してから/clearを使います。同じタスクを続ける場合は、残す情報を指定して/compactを実行します。

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

上の指示では、現在の目標、変更したファイル、失敗しているテストの名前、正確なエラー内容、次に実行する検証コマンドを残すよう求めています。

これらは文書化されたコンテキスト管理の実践方法です。ただし、コンパクションで残るのは要約であり、過去の情報を正確に保管するアーカイブではありません。重要な受け入れ条件は、継続して参照できるプロジェクトの指示やタスクのメモにも残してください。

やり取りのたびにコンパクションを実行するのは避けます。要約用のリクエストが発生し、それまでのメッセージ履歴が置き換わるため、次のリクエストでは短くなった共通の先頭部分を改めてキャッシュする必要があります。頻繁に実行すると、コンテキストを節約する代わりに、要約の処理やキャッシュの再構築が増えることがあります。

推論の労力を調整できるモデルで単純なタスクを行うなら、/effort lowを試してください。設定を下げると推論の処理を減らせますが、ツールがすでに返したログのサイズは小さくなりません。コマンドで変更した設定は選択中のモデルに対して保持されるため、比較後は普段の設定に戻します。対応する設定とモデルのエイリアスは、モデル設定のドキュメントで確認できます。

サブエージェントも標準機能による分離手段です。独立したコンテキストで作業し、要約を返すため、親の会話に情報がたまりにくくなります。ただし、サブエージェント自身のリクエストでもトークンは消費します。

Context ModeとHeadroomはどちらを試すべきか

Claudeに返す前にデータを絞り込めるならContext Mode、既存のツール呼び出しを圧縮レイヤーに通したいならHeadroomを選びます。

ボトルネック	最初に試すもの	変わること
ローカルで検索や処理ができる大きなファイルやログ	Context Mode	Claudeが実行・検索ツールを使い、必要な結果を選んで受け取る
コンパクション後に作業状態の一部が失われる	Context Mode	ライフサイクルのフックがイベントを記録し、作業再開に必要な情報を復元する
既存のツールを使う作業で大量の出力が返る	Headroom	ローカルプロキシが対象のツール出力を圧縮してからリクエストを転送する
推論や再試行の比重が大きい短いタスク	標準機能による作業範囲、推論の労力、モデルの調整	新しい構成要素を追加する前に、処理する仕事の量を変える

結果の変化をどのツールによるものか判断できるよう、1つずつ試してください。

公表されている削減率は、そのまま比較できません。Context Modeのベンチマーク資料は、選ばれた例の出力バイト数を測定しています。一方、Headroomの21%–57%という数値は、固定シードを使うオフラインのツール出力ワークロードから得られたものです。どちらもClaude Codeの請求総額がどれだけ下がるかを示す数値ではなく、圧縮後もタスクを正しく完了できるかの確認に代わるものではありません。

Context Modeでファイル全体ではなく処理結果を返す

Context Modeが役立つのは、入力データのすべてをClaudeの会話に入れなくても、ローカルの処理で答えを得られる場合です。プラグインは選択したセッションイベントをSQLiteに記録し、フックを使ってコンパクション後に作業を続けるための情報を復元します。

現在のパッケージにはNode.js 22.5.0以降が必要です。Bashでインストール済みのバージョンを確認してください。

claude --version
node --version

Claude Code内では、プロジェクトが案内しているマーケットプレイスからの導入手順を使います。

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Claude Codeを再起動してから、次を実行します。

/context-mode:ctx-doctor

診断コマンドは、実行環境の対応状況、プラグインの登録、フック、SQLiteの検索機能などを確認します。関連するエラーを解消してから、プラグインが有効になったと判断してください。MCPサーバーだけを導入しても、同じライフサイクルフックとの連携は得られません。

具体的な動作確認には、形式のバージョンが2または3のpackage-lock.jsonがすでにあるnpmプロジェクトを使います。Claudeに、path: "package-lock.json"、language: "javascript"と次のコードを渡して、ctx_execute_fileを呼び出すよう依頼してください。

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

ツールはFILE_CONTENTを通じてファイルの内容を渡します。想定される結果は、ロックファイル全体ではなく、指定した3つのフィールドを含む小さなJSONオブジェクトです。実際の数値はプロジェクトによって異なり、数えているのはロックファイルのエントリーであって、重複を除いたパッケージ名の数ではありません。

lockfileVersionはファイルの形式、packageEntriesはルートを除くエントリー数、entriesMarkedDevは開発用としてマークされたエントリー数です。この例は集計結果を返すためのもので、依存関係の内容すべてをClaudeに読ませる必要はありません。packagesフィールドがなければ、コード内の英語メッセージが返ります。

続けて、次を実行します。

/context-mode:ctx-stats

統計コマンドにContext Modeの使用状況が表示されることを確認します。呼び出しがないと表示された場合は、指定した経路で処理が行われたことを確認できていません。ここに表示される出力の削減率は、請求額を計算したものではありません。

ログにも同じ方法を使えます。件数をローカルで集計し、関係するエラーを選び、出典の位置を添えて正確な抜粋を返します。Claudeがコードそのものを正確に読む必要がある小さなソースファイルは、直接読む方法を残してください。

Context ModeのライセンスはElastic License 2.0です。また、実行環境の分離は、OSレベルの完全なセキュリティサンドボックスではありません。実行ツールがファイルシステムへのアクセス権を引き継ぐ場合があるため、エージェントがコマンドを実行する際に普段使っている権限設定とサンドボックスの制御を維持してください。

Headroomで対象のツール出力をローカルプロキシに通す

Headroomは、通常のClaude Codeのツールを使い続けながら、圧縮対象の出力をプロキシで小さくしたい場合に向いています。コーディング向けの標準動作ではキャッシュの安定性も考慮されるため、すべてのソースファイルやリクエストが圧縮されるわけではありません。

この例ではAnthropic ConsoleのAPIキーを使うため、Claudeのサブスクリプションとは別にAPI料金が発生します。uvとClaude Codeがインストール済みで、Headroomのプロキシがまだ動いておらず、競合する独自ゲートウェイやクラウドプロバイダーの設定が有効になっていないことが前提です。組織の既存ゲートウェイを使う場合は、その構成に合った連携手順が必要です。

Headroomの導入ガイドに従い、Bashでバージョンを指定したプロキシパッケージをインストールします。

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

バージョン確認では0.41.0と表示されるはずです。キーを画面に表示せずに読み込み、Enterを押してからラッパーを起動します。

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Claudeが確認を求めたらカスタムAPIキーの使用を承認し、/statusで現在の認証情報とモデルを確認します。以前にキーの使用を拒否した場合は、Claudeの認証ドキュメントにある、/config内の「Use custom API key」設定を確認してください。

ラッパーはローカルプロキシを起動または再利用して、そのプロキシ経由でClaudeを起動し、Headroomの情報取得用MCPサーバーをClaude Codeの設定に登録します。--code-memory noneは追加のSerena連携を省略する指定で、Headroomによる情報取得は引き続き利用できます。この手順に--no-mcpを追加すると、圧縮された内容のマーカーから元の情報を取得する経路がなくなるため、追加しないでください。これらのオプションは0.41.0のラッパー実装で定義されています。

環境変数による指定は、ローカルのテレメトリー収集を有効にし、任意のアップロード用ビーコンを無効にします。モデルへのリクエストは、引き続き設定済みのプロバイダーに送信されます。

起動時に表示されたプロキシのアドレスを記録してください。通常のポートは8787ですが、ラッパーが別の空きポートを選ぶ場合もあります。別のBashターミナルで、必要に応じて実際のポートに置き換えて実行します。

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

次に、既存の十分な大きさのtest.logを使って、ラッパー経由で起動したClaudeに範囲を絞ったタスクを渡します。ファイルは変更せず、失敗したテストを重複なく一覧にし、各テストの最初のエラーを正確に引用するよう依頼してください。終了後、HTTPエンドポイントの/statsをもう一度リクエストします。

ヘルスチェックが正常なら、プロキシが動作していることを確認できます。requests.totalの増加は、完了したリクエストが集計処理まで到達したことを示します。requests.failedとrequests.rate_limitedは別々に確認してください。各フィールドはメトリクスのドキュメントに説明されています。短いデータや圧縮対象から保護されたデータで削減量がゼロでも、それだけでルーティングの失敗とは判断できません。

認証が失敗した場合は、再試行する前にANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、プロバイダー設定の競合を確認します。リクエストが記録されない場合は、表示されたポートと、起動したセッションが通る経路を確認してください。

Headroomの圧縮・キャッシュ・再取得の仕組みでは、Claudeが省略された詳細を必要としたとき、保持されている元の内容を取得できます。ただし、再取得にも処理が発生し、元の内容の保持期間には限りがあります。すでに取得できない場合は、元のファイルを参照するか、コマンドを再実行します。

ラッパー経由のClaudeを終了したら、元のターミナルで、同じプロジェクトから試行用の設定を片付けます。ポートは実際に使われた値に合わせてください。

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

UnwrapはHeadroomが管理する設定を削除し、該当するプロキシの停止を試みます。キーをunsetすると、この試行のためにエクスポートしたAPI認証情報が環境から削除されます。普段の認証方法で作業を再開する前に、/statusを確認してください。

範囲の明確なサブタスクに低価格モデルを使う

低価格モデルは、渡したログから失敗を抽出するなど、結果を少ない手間で検証できるタスクに使います。これは処理の単価を変える方法であり、トークン数が減ることを保証するものではありません。

標準機能だけで比較の基準を作るには、.claude/agents/log-summary.mdを作成します。

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

この設定ではモデルのエイリアスをhaikuにし、使えるツールをRead, Grep, Globに絞っています。指示の対象はタスクで渡されたログだけです。失敗したテスト名、エラーの正確な抜粋、ファイルや行への参照を返し、判断が不確かな点や根拠が足りない点も報告するよう求めています。ファイルの変更は指示で禁止しています。

エージェント用ディレクトリを作成したらClaude Codeを再起動し、既存のログを指定してサブエージェントを呼び出します。

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

上の依頼では./test.logを調べ、最初に失敗したテストと正確なエラーを返して、要約が終わった時点で停止するよう指定しています。調査対象と終了条件を明示した呼び出しです。

実行中に/tasksを確認し、サブエージェントが実際に使っているモデルを調べます。返された抜粋も元のログと照合してください。maxTurnsが制限するのはターン数であり、ドル金額やトークン数ではありません。上限に達すると、結果が未完成のまま終わることがあります。設定フィールドと起動時の動作は、サブエージェントのリファレンスで確認できます。

haikuはエイリアスなので、実際に使われるモデルはプロバイダーの設定で決まります。難しい設計判断や原因の曖昧な不具合調査には、その問題を安定して解決できるモデルを使ってください。単価の安いサブエージェントでも、何度も修正を指示する必要があれば、全体の費用が高くなることがあります。

BetterTokenで従量課金のモデルアクセスを利用する場合は、Claude Codeの設定手順に従います。Anthropic互換のベースURLはhttps://bettertoken.aiで、/v1は付けません。ANTHROPIC_DEFAULT_HAIKU_MODELとほかのエイリアスの割り当てを確認してください。すべてのエイリアスに同じモデルIDを割り当てていると、haikuを選んでも別の安いモデルには切り替わりません。対応するIDを意図的に選び、現在のモデル料金とキャッシュ料金を比較して、記録されたモデルと請求額を確認します。BetterTokenのAPI課金はClaudeのサブスクリプションとは別です。また、これは上記のAnthropicに直接接続するHeadroomの試行とは別のプロバイダー設定として扱ってください。

タスク全体の費用と結果の正確さで判断する

圧縮ツールを使い続けるかどうかは、キャッシュへの影響、サブエージェント、情報の再取得、再試行まで含めて、タスク完了時の結果が改善するかで判断します。

比較するときは、リポジトリの状態、プロンプト、実際のモデル、推論の労力の設定、検証コマンドをそろえてください。各実行がキャッシュのある状態とない状態のどちらで始まるかも記録します。条件を混ぜると比較結果がゆがむためです。最終的なパッチや回答だけでなく、そこで示された根拠が正確かどうかも確認します。

Anthropic APIの集計では、input_tokens、cache_creation_input_tokens、cache_read_input_tokensは別々の分類です。input_tokensだけでは入力全体の量を表せません。出力トークンも計算に含めてください。100万トークン当たりの料金で比較する場合は、すべてのリクエストを対象にsum(token_count × category_rate / 1,000,000)を計算します。保持期間によって書き込み料金が異なるキャッシュは分けて集計し、トークン以外に必ず発生する料金も加えます。

Claude Codeでメインの会話のキャッシュ情報を表示するには2.1.251以降が必要で、この表示にはサブエージェントが含まれません。プロキシの削減量カウンターは診断には役立ちますが、支出の比較には課金プロバイダーの利用明細を使ってください。

省略されたエラーが原因で追加調査が必要になる、サブエージェントが何度も助けを必要とする、再取得によって元と同じ量のコンテキストが戻ってくる、といった場合は、圧縮を弱めるかタスクの切り分けを変えます。目指すのは、課金対象になる処理全体を減らしながら、正しい結果を得ることです。