AI 開発のトークンコストを 20% 削減した話 ― ローカル圧縮プロキシ「Headroom」導入の実測レポート

ccf代表
2 日前
読了時間: 4分

AI コーディングエージェントの API コストを、開発体験を変えずに削減する。

背景：AI コーディング常用で見えてきた「文脈コスト」

社内では日常的に AI コーディングエージェント（Claude Code）を開発に組み込んでいる。生産性は確実に上がる一方で、エージェントが ツール実行結果・ビルドログ・会話履歴 を繰り返し LLM へ送り込む構造上、入力トークンが膨らみやすい。実装そのものより「文脈の運搬コスト」が積み上がっていく――これが今回の最適化の出発点である。

Headroom とは

Headroom は、LLM へリクエストを送る前にコンテキストを圧縮するローカルプロキシ。エージェントと API エンドポイントの間に挟むだけで、ツール出力やログといった「冗長だが意味は保てる」テキストを縮めてから上流へ渡す。

動作位置：http://127.0.0.1:8787 でローカル待受。/v1/messages を Anthropic、/v1/chat/completions 系を OpenAI へ中継。
圧縮エンジン：ONNX モデル（kompress-base）をローカル実行。初回のみモデルを取得・キャッシュし、以降はオフラインで高速動作。
認証：クライアントの認証ヘッダ（x-api-key / Authorization Bearer）をそのまま上流へ透過。サブスク / OAuth でもそのまま使える。
導入：pipx install --python python3.13 "headroom-ai[proxy]" の 1 行。検証時のバージョンは v0.22.4。

構成：オンデマンド運用にした理由

常駐サービス（launchd）化はせず、使いたいときだけ起動する手動運用を選んだ。エージェント側の安全機構と相性が良く、経路を意識的に制御できるためだ。

hr-proxy start     # プロキシ起動（起動済みなら何もしない）
hr-proxy status    # 稼働状態 + 圧縮サマリ
claude-hr          # プロキシを自動起動し、その経由で Claude Code を起動
hr-proxy stop      # 停止

ラッパー claude-hr がプロキシ起動とエージェント起動をまとめて面倒を見るので、日々の操作は「claude の代わりに claude-hr を叩く」だけに収まる。

実測結果

運用開始からの累計（対象モデル：claude-opus-4-8）。数値はプロキシの統計エンドポイントから取得した実測値。

指標	値
API リクエスト総数	2,349
圧縮を実行したリクエスト	1,603
平均圧縮率	9.9%
最大圧縮率（単一リクエスト）	56.4%（12,326 → 5,375 tokens）
削減した入力トークン	約 2,878 万 tokens
コスト削減額	$691.35 → $550.92（−$140.44 / 20.3%）

平均 9.9% という数字は控えめに見えるが、これは「圧縮余地のない小さなやり取り」まで分母に含めた値だ。大きなツール出力を含むリクエストでは 50% 超まで縮む（最大 56.4%）。総量で見れば送信前トークン約 3.5 億のうち 約 2,878 万 tokens を上流に渡さずに済んだ計算になる。

開発フローもプロンプトも一切変えず、プロキシを 1 枚挟んだだけで 2 割のコスト削減。投資対効果としては破格だった。

効くところ・効かないところ

正直に言うと、Headroom は万能ではない。効く局面とそうでない局面がはっきり分かれる。

よく効く：ビルドログ、テスト出力、巨大な diff、長い検索結果など「冗長なツール出力」。
効かない / 対象外：短いやり取り（圧縮余地なしで 0%）、キャッシュ固定済みの prefix、明示的なパススルー。実測でも、未圧縮リクエストの内訳は prefix 固定 588・対象テキストなし 140・小さすぎ 13・パススルー 14 と、「縮める意味がない」ものが大半だった。

つまり 無理に縮めず、効くところだけ縮める設計になっている。これが品質劣化の体感がない理由でもある。

運用上の注意点

CLI 専用：デスクトップアプリ版エージェントは BASE_URL 上書きを尊重せず公式エンドポイントへ直結するため、プロキシを経由できない。Headroom が効くのは CLI 起動（claude / claude-hr）のみ。
ロールバックが容易：環境変数で経路を指定しているだけなので、素の起動に戻せばプロキシは経由しない。恒久ルーティングを設定していないため「戻し作業」は不要。
初回コスト：圧縮モデルの初回ダウンロードのみネットワークが要る。以降はローカル完結。

まとめ

AI コーディングを本格的に業務へ組み込むほど、「文脈の運搬コスト」は無視できなくなる。 Headroom はそこへ 開発体験を変えずに・低リスクで切り込める実用的な選択肢だった。結果は 累計で約 2 割、$140 のコスト削減。同じように AI エージェントを多用しているチームには、一度試す価値があると感じている。