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

TL;DR: 結論から言うと、Claude Codeの前にHeadroom 0.23.0を透過プロキシとして挟んでも、6条件すべてで削減は0%でした。挟む実利はありません。トークンを減らしたいなら、RTK（CLI出力時）・プロンプトキャッシュ・読み込みや会話履歴の節約という別の手段を狙うのが正解です。

結論

Claude Codeの前にHeadroomを透過プロキシで挟んでも、6条件すべてで削減0%でした。挟む実利はありません。トークンを減らしたいなら、狙うべきは別の手段です。

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

ここで大事なのは、Headroom全体を否定しないことです。否定したいのは、Claude Codeの前に透過プロキシとして挟む使い方です。

何を確かめたのか

今回見たかったのは、次の一点です。

Claude Codeの前にHeadroomを透過プロキシとして挟んだとき、実際に圧縮削減が出るのか。

検証では、Headroom 0.23.0 を ANTHROPIC_BASE_URL で Claude Code の前段に置き、実Claude Code / 本番Opusのやり取りを通しました。対象は、lib配下の4ファイル、約67KBを読んで要約する同一タスクです。

評価は、Headroom自身の /stats が返す 圧縮件数 を信号にしました。生コストの増減そのものではなく、Headroom由来の圧縮が発火したかを見ています。

この切り方にした理由は単純で、課金額はキャッシュの温まり方で簡単に揺れるからです。そこを雑に見ると、Headroomの効果とClaude Code nativeのキャッシュ効果が混ざります。今回はそこを混ぜないようにしました。

6条件、全部0%でした

試した条件は6つです。

cacheモード
tokenモード
token + code-aware（[code] 導入）
上記に加えてプロンプトキャッシュ無効（DISABLE_PROMPT_CACHING=1）
さらに HEADROOM_COMPRESS_USER_MESSAGES=1
それらの組み合わせ違いを含む総当たり

結果はシンプルでした。

/stats の requests_compressed は 0
圧縮率は 0%
Headroom由来の節約は $0

これは驚きの結果というより、期待していた側からすると少し肩透かしです。派手な公称値があるぶん、「どこかの設定が足りないのでは」と疑いたくなります。そこで条件を一つずつ潰しましたが、どれも反応しませんでした。

正直、ここは少し迷いました。設定の見落としなのか、そもそも経路が違うのか。そこで、キャッシュ、token、code-aware、userメッセージ圧縮、プロンプトキャッシュ無効まで潰しても0%だったので、原因は「設定不足」ではなく「その経路では発火しない」と見るのが自然です。

課金額は揺れたが、Headroomの効果ではない

実行ごとの課金コストは、直結で $0.67、cache で $0.87、token で $0.50 とばらつきました。

ただし、これは Headroom の効果ではありません。3連続実行で Claude Code のプロンプトキャッシュが温まっていったノイズです。cache_read が 64k → 94k → 158k と増えており、そこが効いています。

ここは足元を見ておきます。/stats の cache_savings_usd は Claude Code native のキャッシュ節約 であって、Headroom の compression_savings_usd ではありません。今回そこはずっと 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透過プロキシ を6条件で徹底的に潰したものです。

なので、結論はむしろ補強されています。

再現できない = 効果がない、ではない
ただし、経路依存 はかなり強い
Claude Code の前に透過的に挟むだけでは、少なくとも今回の条件では効かなかった

この整理ができると、過度な期待もしなくて済みます。

では、何でトークンを減らすのか

ここで終わると、ただの「効かなかった報告」になります。そういう記事は読みたくないので、次の判断材料まで置いておきます。

1. CLI出力が長いならRTKを使う

CLI出力の整形・削減が主目的なら、RTK はまだ使い道があります。

今回RTKが効かなかったのは、対象が違ったからです。逆に言えば、CLI出力が本当に長い経路 では評価対象になります。

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

今回の実測でも、キャッシュの温まり方はコストに効きました。

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

キャッシュは地味ですが、実際に触ると、この差は地味に効きます。

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

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

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

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

判断はこうでいい

読者が知りたいのは、たぶんこの2点です。

Claude Codeの前にHeadroomを透過プロキシで挟むべきか?

答えはノーです。今回の実測では、6条件すべてで削減 0% でした。透過プロキシ用途では実利ゼロです。

では何でトークンを減らすか?

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

この2問に対して、今回の結論はぶれません。

まとめ

Headroom は、使う経路を選ぶツールでした。少なくとも Claude Code の前に透過プロキシとして挟む だけでは、今回の本番 Opus 実測では 6 条件すべて 0%。

だから、購入判断としてはかなり明快です。

Claude Code の前段に Headroom を足しても、透過プロキシ用途では期待しない
60〜95% の数字は、別経路の可能性を疑う
トークン削減は、RTK・キャッシュ・入力設計で詰める

派手な数字に引っ張られたくなるのは自然ですが、実務では「どの経路で効くか」を分けて見た方が、ずっと損をしません。

必要なら次にやるべきは、Headroom を増設することではなく、自分の Claude Code のどの経路が膨らんでいるのかを切り分けること です。そこが見えれば、削れる場所はかなり変わります。

注意点・制約

今回の0%は「Headroom 0.23.0 を Claude Code の前に透過プロキシとして挟む経路」での結果です。RTK単体・MCPの明示呼び出し・合成ログ経路では別の数字が出ます。
計測は lib配下4ファイル（約67KB）の読み込み→要約という単一ワークロードを本番Opusで通した結果です。ワークロードやモデルが変われば挙動は変わり得ます。
Headroom は Beta（v0.23.0時点）で、圧縮ポリシーやデフォルト設定は今後のバージョンで変わる可能性があります。

どのように検証したか

Headroom 0.23.0 を ANTHROPIC_BASE_URL で実Claude Code（本番Opus）の前段に置き、同一タスク（lib配下4ファイル≒67KB読込→要約）を通しました。
効果の信号は課金額ではなく、Headroom自身の /stats が返す圧縮件数（requests_compressed）にしました。課金額はプロンプトキャッシュの温まりで揺れるため、Headroom由来の圧縮が発火したかだけを見ています。
cache/tokenモード・code-aware・プロンプトキャッシュ無効・userメッセージ圧縮を含む6条件を総当たりし、すべてで圧縮0件・Headroom由来の節約$0を確認しました。

よくある質問

結局、Claude Codeのコストを下げるには何をすればいいですか？

読ませるファイル・会話履歴・ツール定義を減らし、プロンプトキャッシュを壊さない（同一プレフィックスを保つ）のが一番効きます。透過プロキシを増設するより実効が大きいです。

RTK単体なら効果はありますか？

CLI出力の整形・削減が目的なら使い道があります。ただしRTKは非可逆なので、個別の値がそのまま必要な用途には不向きです。判断材料だけ残ればよいログ・ビルド出力に絞るのが前提です。

Codex や Cursor でも0%ですか？

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

この記事を書いた人

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

結論