事例紹介2026年6月8日by K.hirano

Claude CodeにHeadroomは効くのか？5条件潰した実測の結論

Claude Codeの前にHeadroomを透過プロキシで挟んでも、5条件すべてで削減0%。本番Opus実測から、効く経路と無駄な経路を切り分けます。

#Claude Code#headroom#実測#コスト削減#case-study

こんにちは。湿気で押し入れの中まで気になる時期は、手元の道具の無駄も一緒に片づけたくなりますね。今回は、Claude Code のトークン（AI に読ませる文字量の単位で、料金はこれで決まります）を減らせるかもしれない道具、Headroom の話です。

先に結論を書きます。Claude Code の前に Headroom 0.23.0 を透過プロキシ（Claude Code と Anthropic の間に割り込んで、やり取りを素通しさせながら中身に手を加える中継役）として挟んでも、試した5条件すべてで削減は0%でした。この使い方で挟む実利はありません。トークンを減らしたいなら、RTK（CLI出力時）・プロンプトキャッシュ・読み込みや会話履歴の節約という別の手段を狙うのが正解です。

ただし、Headroom そのものを否定したいわけではありません。外れだったのは、Claude Code の前に透過プロキシとして挟む使い方です。関連記事としては Anthropicリーク2連発：Claude MythosとClaude Code流出で見えたKAIROS、BUDDY、Undercover Modeの正体もあわせて読むと、今回の論点とのつながりを把握しやすくなります。

公称60〜95%に期待して、本番Opusで確かめた

公称60〜95%削減という数字を見た瞬間、「これ、Claude Code の前に置けば効くのでは」と期待する気持ちは分かります。私もそう思って、実際に試しました。

やり方はこうです。Headroom 0.23.0 を ANTHROPIC_BASE_URL（Claude Code が問い合わせに行く宛先の設定）で Claude Code の前段に置き、実Claude Code / 本番Opusのやり取りをそのまま通しました。タスクは毎回同じで、lib配下の4ファイル、約67KBを読ませて要約させるものです。

効いたかどうかは、課金額ではなく、Headroom 自身の /stats が返す圧縮件数（requests_compressed）で見ました。課金額はキャッシュの温まり方で簡単に揺れるので、そこを雑に見ると Headroom の効果と Claude Code native のキャッシュ効果が混ざってしまいます。今回はそれを混ぜないようにしました。

5条件を潰しても、圧縮は一度も起きなかった

試したのは、Headroom を挟んだ5つの条件と、比較用の直結1つです。

cacheモード
tokenモード
token + code-aware（[code] 導入）
上記に加えてプロンプトキャッシュ無効（DISABLE_PROMPT_CACHING=1）
さらに HEADROOM_COMPRESS_USER_MESSAGES=1
比較用の直結（Headroomを挟まない）

結果はシンプルでした。/stats の requests_compressed は 0、圧縮率は 0%、Headroom 由来の節約は $0 です。

派手な公称値があるぶん、「どこかの設定が足りないのでは」と疑いたくなります。正直、ここは少し迷いました。設定の見落としなのか、そもそも経路が違うのか。そこでキャッシュ、token、code-aware、userメッセージ圧縮、プロンプトキャッシュ無効と一つずつ潰しましたが、どれも反応しませんでした。期待は派手でしたが、現実は静かでした。ここまでやって0%なら、原因は「設定不足」ではなく「その経路では発火しない」と見るのが自然です。

課金額は揺れたが、Headroomのおかげではない

実行ごとの課金コストは、直結で $0.67、cache で $0.87、token で $0.50 とばらつきました。token が安く見えますが、これは Headroom の効果ではありません。3連続実行で Claude Code のプロンプトキャッシュ（同じ前置きを使い回して安く読む仕組み）が温まっていったノイズです。cache_read が 64k → 94k → 158k と増えており、そこが効いています。

もう一つ、見間違えやすいところがあります。/stats に出てくる cache_savings_usd は Claude Code native のキャッシュ節約 であって、Headroom の compression_savings_usd ではありません。Headroom 側の数字は、今回ずっと 0 のままでした。課金が変わったからといって、Headroom が効いたわけではないということです。

透過プロキシで沈黙したのは、設定ではなく経路のせい

Headroom 0.23.0 の自動圧縮は、Claude Code の /v1/messages 形では発火しませんでした。 code-aware でも、user メッセージ圧縮でも、キャッシュの有無でもない。全部潰して 0% なので、原因は設定ではなく経路です。

ここからは私の推測ですが、Headroom の自動圧縮ポリシーはかなり保守的です。compression_policy.py 側でも CONSERVATIVE な扱いが見えており、telemetry を見ながら段階的に広げる設計に見えます。少なくとも、Claude Code を透過的に通すだけで勝手に圧縮が走るタイプではありません。

そして、ここが一番大事なところです。公称60〜95%という数字は、少なくとも今回の使い方、つまりClaude Code の前に透過プロキシとして挟む経路の数字ではない可能性が高いです。その数字が出る別経路としては、次の3つが濃厚です。

CLI出力の削減を RTK に委譲する経路
MCP の headroom_compress を明示的に呼ぶ経路
ログ / JSON / RAG などを、OpenAI互換や assistant 側で流す合成ベンチの経路

数字が大きいことと、Claude Code の前段でそのまま効くことは別問題です。ここを混ぜると判断を誤ります。

RTKは無力ではない。今回は対象が無かっただけ

誤解しやすいので分けて書きます。RTK は、CLI出力のような冗長なテキストでは大きく削減します（当サイトの隔離・合成ログ実測では RTK層で93%）。これは別記事で出した数字で、今回の透過プロキシ経路とは別物です。

では今回、なぜ RTK が発火しなかったのか。理由は単純で、Claude Code の Read ツール（ファイルを読む機能）は CLI出力ではなく tool_result を返す からです。RTK が整形する対象がそもそも無かった。だから効かなかっただけで、「RTK も無力」と読むのは違います。

Headroom も RTK も、万能の魔法ではありません。効く場面と効かない場面があり、今回はたまたま「透過プロキシ経由の Claude Code」が外れでした。

以前の Headroom 記事とは矛盾しない

当サイトには、Headroom の仕組みと、隔離環境での実測をまとめた記事がすでにあります。

前者では「効かない場所では静か」という話を書いていました。今回の検証は、まさにその経路、つまり Claude Code 透過プロキシ を5条件で徹底的に潰したものなので、結論はむしろ補強されています。再現できない＝効果がない、ではありません。ただし経路依存はかなり強く、Claude Code の前に透過的に挟むだけでは、少なくとも今回の条件では効きませんでした。ここが整理できていれば、過度な期待もしなくて済みます。

トークンを減らすなら、効く場所はここ

「効かなかった」で終わる記事は私も読みたくないので、次の判断材料まで置いておきます。

CLI出力が長いならRTK

CLI出力の整形・削減が主目的なら、RTK はまだ使い道があります。今回効かなかったのは対象が違ったからで、逆に言えば、CLI出力が本当に長い経路では評価対象になります。ただし RTK は非可逆（削った中身は元に戻せない）なので、個別の値がそのまま必要な用途には不向きです。判断材料だけ残ればよいログ・ビルド出力に絞るのが前提です。

プロンプトキャッシュを壊さない

今回の実測でも、キャッシュの温まり方はコストに効きました。地味ですが、実際に触るとこの差は地味に効きます。

同一プレフィックス（毎回同じ前置き）をむやみに変えない
DISABLE_PROMPT_CACHING=1 のような設定は、必要がないなら避ける
読み込みのたびに毎回違う前置きを足しすぎない

読み込み・会話履歴・ツール定義そのものを削る

一番効くのは、結局ここです。

読ませるファイルを減らす
会話履歴を肥大化させない
ツール定義を長文化させない
役に立たない前置きを入れない

透過プロキシを足すより、こちらの方が実効は大きいです。少なくとも Claude Code の前段で Headroom をひねるよりは、素直に効きます。

判断はこうでいい

Claude Code の前に Headroom を透過プロキシで挟むべきか? 答えはノーです。今回の実測では5条件すべてで削減 0% で、透過プロキシ用途では実利ゼロでした。60〜95% の数字を見かけたら、別経路の数字ではないかを疑ってください。

では何でトークンを減らすか? 答えは RTK（CLI出力時）・プロンプトキャッシュ・読込/会話/ツール定義の節約 です。

派手な数字に引っ張られたくなるのは自然ですが、実務では「どの経路で効くか」を分けて見た方が、ずっと損をしません。次にやるべきは Headroom を増設することではなく、自分の Claude Code のどの経路が膨らんでいるのかを切り分けることです。そこが見えれば、削れる場所はかなり変わります。

今回の0%が当てはまる範囲

この0%は、「Headroom 0.23.0 を Claude Code の前に透過プロキシとして挟む経路」での結果です。RTK単体・MCPの明示呼び出し・合成ログ経路では別の数字が出ます。

計測も、lib配下4ファイル（約67KB）の読み込み→要約という単一ワークロードを本番Opusで通したものです。ワークロードやモデルが変われば挙動は変わり得ます。また Headroom は Beta（v0.23.0時点）で、圧縮ポリシーやデフォルト設定は今後のバージョンで変わる可能性があります。

Codex や Cursor でも0%になるかは、今回は確かめていません。検証したのは Claude Code の透過プロキシ経路だけで、エージェントや経路が変わると結果は変わり得ます。まず自分の構成で「何が長いのか」を1本測るのが確実です。

この記事を書いた人

HW系エンジニアとして20年以上、10,000件を超える顧客訪問と2,000件を超える単独ソリューション実績。AIツールを使った個人開発やIoT農園など、Raspberry Piを使ったオートメーション化なども実践中です！エンジニア専門結婚相談所も運営中、ClaudeCodeで解決できない心の課題も解決いたします！