headroomでトークンを削減した話

こんにちは、ナナオです。

突然ですが、AIコーディングエージェントのトークン消費って本当に気になりますよね。

普段は Claude CodeとOpenCode Goを併用しているんですが、両方とも長時間セッションを回しているとあっという間にトークン消費が伸びていきます。

「これ、無駄な部分削れないかな」と思って調べたら headroom を見つけたので、試しに入れてみました。

※この記事の作成にはMiniMax-M3を大いに活用しています。

headroomとは

GitHub - headroomlabs-ai/headroom: Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server. · GitHub

Introduction | Headroom

headroom は、AIエージェントが読み取るコンテキスト（ツール出力、ログ、RAG 結果、ファイル、会話履歴）を LLM に渡す前に圧縮するレイヤーです。

公式の説明では「the context compression layer for AI agents」と書いてあって、Python実装のコアに Rust 製トランスフォーマーを組み合わせた構成になっています。

2026年7月時点で57k starがついており、わりと有名なんじゃないかと思います。

インストールとプロキシ起動

Docker イメージをそのまま使います。

docker pull ghcr.io/chopratejas/headroom:latest

docker run -d --name headroom -p 8787:8787 \
  ghcr.io/chopratejas/headroom:latest

これで 8787 番ポートにプロキシが立ちます。コンテナ内で headroom proxy が立ち上がっている状態です。

動作確認はコンテナに入って:

docker exec -it headroom headroom doctor

ルーティングが効いていれば通ります。

Claude Code での設定

Claude Code は ANTHROPIC_BASE_URL でエンドポイントを変えられます。プロキシに向けて起動。

ANTHROPIC_BASE_URL=http://localhost:8787 claude

これで Claude Code の API リクエストが headroom 経由で upstream に届くようになります。普段遣いするときはエイリアスや direnv に書いておくと楽です。

OpenCode での設定

OpenCode は opencode.json に provider を追加します。@ai-sdk/openai-compatible を使って headroom の /v1 に向ける構成。

{
  "provider": {
    "headroom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Headroom Proxy",
      "options": {
        "baseURL": "http://localhost:8787/v1"
      },
      "models": {
        "claude-sonnet-4-6": {},
        "gpt-4o": {}
      }
    }
  }
}

モデル名は upstream 側（Anthropic / OpenAI）で普段使っているものをそのまま使えます。opencode を起動してこの provider を選べば、プロキシ経由で動作します。

実際のトークン削減量

公式 README に載っているベンチマークが以下。

ワークロード	Before	After	削減
コード検索（100 件）	17,765	1,408	92%
SRE インシデント調査	65,694	5,118	92%
GitHub issue トリアージ	54,174	14,761	73%
コードベース探索	78,502	41,254	47%

出典: 公式 README の “Proof” セクション

自分の環境でも測ってみました。以下のようなプロンプトを投げた結果は以下の通りです。

> headroomでのトークン削減効果は現在何パーセントくらいですか？

> /stats を叩いた結果、永続カウント(lifetime)は:
- リクエスト数: 2,727
- 節約トークン: 3,196,591 / 入力 55,943,025 → 約 5.7%(トークン比)
- コスト: $159.95 入力 → $22.10 節約 → 約 13.8%(金額比)
- 最終更新: 2026-07-06 06:57 UTC

大体5.7％は節約になっているようです。いいですね。

注意点 —— 独立ベンチマークでの指摘

ここまで「headroom を入れたらトークンが減った」という話をしてきましたが、実は「それ、headroom のおかげじゃないよ」と指摘する独立した検証が出ています。

要点はこうです。

トークンが減ったのは Headroom 本体（Proxy）の効果ではなく、headroom wrap がついでに有効化している ENABLE_TOOL_SEARCH=true という環境変数の効果だった。headroom を使わず ENABLE_TOOL_SEARCH=true claude と打つだけで同じ削減が再現できる。

ENABLE_TOOL_SEARCH=true は、Claude Code が「ツールの定義を最初に全部読み込まず、必要になったときだけ読む」ようにする設定です。headroom はこれを裏で勝手にオンにしてくれていて、トークンが減った本当の主役はこっちだった、という話ですね。

検証結果を平たく言うと、こんな感じでした。

cache モード（headroom は素通し）: ENABLE_TOOL_SEARCH=true だけを有効にした状態と比べて、削減量はほぼ差なし（誤差レベル）
token モード（headroom が本気で圧縮する）: 素の状態より逆に +57.5% もトークンを食っていた
脆弱性の検出精度自体は、どちらも 12 件中 12 件でズレなし

ただ、この検証は「Claude Code で大きなコードベースのセキュリティ監査をする」という 1 パターンだけを測ったものです。プロンプトキャッシュを使わない環境や、CLI 以外の使い方だと結果は変わってくるかもしれません。

なので個人的な結論としては、まず ENABLE_TOOL_SEARCH=true 相当の設定だけ試してみて、それでも物足りなければ headroom の圧縮機能に手を出す、という順番が安全かなと思います。

まとめ

headroom は Proxy を Docker で 1 つ立てて、各エージェントの baseURL をそこに向けるだけで導入できるので導入コストがとても低いと思います。

Claude Code も OpenCode も、エージェント側の設定は 1 行（環境変数）か数十行（opencode.json の provider 追加）で済みます。

「トークン削減」という側面だけで見ると、節約の主因が ENABLE_TOOL_SEARCH の効果だったというベンチ結果も出ています。

proxy の数値だけで判断せず、自分の環境で headroom perf を回して判断するのが一番確実です。

headroom dashboard を表示しながら普段どおり Claude Code / OpenCode を使うと、入力側・出力側それぞれで何% 削れているかが見えて面白いです。

今回はローカルに建ててみましたが、次回は自宅のk3s環境に建ててみたいと思います。

ということで今回はこれで👍

headroomとは#

インストールとプロキシ起動#

Claude Code での設定#

OpenCode での設定#

実際のトークン削減量#

注意点 —— 独立ベンチマークでの指摘#

まとめ#