ローカル LLM 高速化：Headroom で Agent コンテキスト 95% 削減（2026）

Mac mini で Ollama、DeepSeek、Llama 3 をコーディング Agent に向け、monorepo の grep や 200 MB ログの tail を頼むと UI が固まり、tok/s が落ちます。8B–14B ローカルではツール出力の膨張がモデル性能より効きます。未圧縮の 1 バイトごとが統一メモリバスを ~20–40 tok/s で占有します。

Headroom は OSS のコンテキスト圧縮レイヤー（Apache 2.0）で、LLM に入る前にツール出力・ログ・ファイル読取を通常 60–95% 削減。CCR で原文をオンデマンド取得できます。本稿はローカル優先向け。クラウド課金削減は Hermes Trajectory Compressor を参照してください。

巨大なツール出力でローカル Agent が「止まる」理由

ローカル推論の遅延はコンテキスト長とメモリ帯域に強く依存し、「賢さ」だけでは決まりません。

引用定義： ローカル LLM ツール遅延＝ツール返却から次トークン生成までの実時間。未圧縮コンテキストの prefill が支配的で、ツール実行時間そのものではありません。

Apple Silicon では OpenClaw や MLX サイドカーも使う場合、8 GB メモリ予算と併用してください。

Headroom アーキテクチャ：prefill 前に圧縮

Agent (Cursor, OpenClaw, custom) │ tool results · file reads · logs ▼ ┌──────────────────────────────┐ │ Headroom (local) │ │ CacheAligner → ContentRouter │ │ ├─ SmartCrusher (JSON) │ │ ├─ CodeCompressor (AST) │ │ └─ Kompress-base (text) │ │ CCR store (reversible) │ └──────────────────────────────┘ │ compressed messages + headroom_retrieve ▼ Ollama / llama.cpp / MLX API

README ベンチ（python -m headroom.evals suite で再現）：

CCR: 原文はディスクに保持。必要時 headroom_retrieve で完全ファイルを取得—永久削除なしの積極圧縮。

外部：クイックスタート、CCR。

決定マトリクス：Mac mini Agent で何を使うか

Mac mini で OpenClaw： Headroom は OpenClaw を wrap 対象・ContextEngine プラグインとしてサポート—Agent 書き換え不要。

If X, do Y： 7B で cat 1 回の後 prefill が 10 秒超なら、GPU 増設やクラウドより先に Headroom を有効化。

シナリオ A — Ollama + Headroom proxy（コード変更ゼロ）

Agent の OpenAI base URL を Headroom に向け、Headroom が Ollama に転送。

構成： Mac mini M2/M3/M4、Ollama qwen2.5-coder:7b または deepseek-r1:8b、Headroom proxy 8787。

期待値： コミュニティ報告：7B で JSON/ログ圧縮後、ツール多めのターンが 45–90 秒 から 8–15 秒 へ（リポジトリ依存—自前ベンチ推奨）。

シナリオ B — ホームサーバー OpenClaw + Headroom MCP

OpenClaw MCP で headroom_compress 等を使用。並列上限が効きやすく—16 GB で 2 並列が可能に。

7 ステップ：Mac mini で Headroom + Ollama

ステップ 1 — Headroom インストール（Python 3.10+）

brew install python@3.12 pip install "headroom-ai[proxy,mcp]" headroom --version

ステップ 2 — Ollama とコーディングモデル

ollama pull qwen2.5-coder:7b-instruct-q4_K_M ollama serve # default :11434

ステップ 3 — Ollama 向け proxy 起動

export OLLAMA_HOST=http://127.0.0.1:11434 headroom proxy --port 8787 --backend ollama

（env のみの場合は proxy ガイド参照。）

ステップ 4 — Agent を localhost:8787 に

OpenAI 互換クライアント例：

export OPENAI_API_BASE=http://127.0.0.1:8787/v1 export OPENAI_API_KEY=ollama # placeholder for local

Cursor / Aider：base URL を http://127.0.0.1:8787/v1 に。

ステップ 5 — ベースライン vs 圧縮ソーク

同一プロンプトを 2 回：

1. 直 Ollama — TODO 検索して全マッチ貼付
2. Headroom 経由 — 同じ

headroom perf または headroom_stats を記録。

ステップ 6 — デバッグ時 retrieve

スタック欠落時：「ERROR 付近は headroom_retrieve で」と指示。CCR が原文を返します。

ステップ 7 — LaunchAgent（任意 24/7）

proxy と Ollama を別 LaunchAgent に。メモリガイドで Node ヒープ上限。順序：Ollama → Headroom → Agent。

トラブルシューティング

症状：Headroom 後も遅い

パターン： バイナリ/protobuf で圧縮率が低い。
対処： JSON/テキスト整形を先に；CodeCompressor；並列読取を減らす。

症状：失敗テスト行が「消えた」

パターン： 唯一の FAIL 行が削除された。
対処： headroom_retrieve；SmartCrusher でエラー語保持；rg --json ERROR 事前フィルタ。

症状：proxy は繋がるが /v1/chat/completions が 404

パターン： バックエンド env 誤り；Ollama 未起動。
対処： curl http://127.0.0.1:11434/api/tags；正しい --backend で再起動。

推奨パス

FAQ