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

Ollama、DeepSeek-R1、Llama 3 を Mac mini や軽量 VPS で動かし、リポジトリ読み取り・ログ tail・DB クエリを行う Agent を接続した経験はありませんか。最初のツール呼び出しが 50,000 トークン の JSON を返すと、7B ローカルモデル が 90 秒以上 固まります。Activity Monitor では CPU は低いのに UI が 無反応 に見えます。これは「モデルが弱い」のではなく、コンテキスト肥大が小規模ハードの tokens-per-second を押し潰している状態です。

クラウド Agent は 200k ウィンドウと高速 GPU で痛みを隠します。8–16 GB Apple Silicon や 2 vCPU ボックスでは、冗長なログ行や重複ファイルチャンクが prefill の秒数を増やします。Linux 向けガイドは 可逆的なツール出力圧縮 にほとんど触れません — そのギャップを Headroom が Apache-2.0 のオープンソース コンテキスト最適化レイヤー で埋めます。

本ガイドはローカル推論をすでに運用している ホームラボ構築者 向けです。ツール遅延が跳ねる理由、Headroom の Compress-Cache-Retrieve（CCR） アーキテクチャ、Ollama や OpenAI 互換クライアントの前にプロキシを置く 8 ステップ runbook を解説します。関連記事：DeepSeek-R1 量子化、OpenClaw ルーティング、Mac mini メモリ調整、コードベース可視化。ZecCloud は 24/7 Agent 向け Mac mini ホスト（東京ノード含む）を提供しますが、本記事は Headroom 公式ドキュメント に焦点を当て、レンタル料金は扱いません。

はじめに

本記事では遅延モデル、Headroom アーキテクチャ、レイテンシマトリクス、8 ステップ runbook、トラブルシューティング、FAQ 6 問を扱います。

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

User → LLM plans tool → Tool returns huge payload → LLM reads ALL bytes → Next token

Mac mini M4 で Ollama 経由の Llama 3.2 3B Q4 を動かすと、コミュニティベンチマークは生成で 40–80 tok/s 程度ですが、32k トークン のツールダンプの prefill だけで最初の回答トークンまで 数十秒 かかることがあります。モデルは「考えている」のではなく、テスト通過行・重複 JSON キー・grep 結果の山を 飲み込んでいる だけです。

統合メモリ帯域は Apple Silicon 概要 を参照。コンテキストが少ないほど、モデル予算と同じプールへの圧力が減ります（Mac mini OpenClaw メモリガイド）。

Headroom アーキテクチャ：プロキシ、ルーター、CCR

Headroom は Agent と LLM プロバイダの間 に位置します — ライブラリ、ローカルプロキシ、MCP サーバー、または Claude Code / Cursor / Aider 向けの headroom wrap です。

Agent (OpenClaw, Aider, custom)
    │  tool outputs, logs, file reads, RAG chunks
    ▼
Headroom proxy :8787  ── ContentRouter ──┬─ SmartCrusher (JSON arrays)
    │                                      ├─ CodeCompressor (AST, tree-sitter)
    │                                      ├─ LogCompressor (failures kept)
    │                                      └─ Kompress-base (prose)
    ▼
CCR store (originals cached locally, hash-addressable)
    ▼
Ollama / OpenAI-compatible API

CCR（Compress-Cache-Retrieve） は圧縮が 可逆 であることを意味します。原文はローカルにキャッシュされ、モデルは詳細が必要なとき headroom_retrieve を呼べます。公開例ではログとツール JSON で 60–95% のトークン削減を示しつつ、エラーと異常は保持します（Headroom GitHub）。

初回実行メモ： Headroom は初回にルーティング用 ML モデル 約 500 MB をダウンロードする場合があります。256 GB Mac mini では Ollama ウェイトと並べてディスク余裕を確保してください。

レイテンシマトリクス：圧縮が効く場面

• Agent が 1 ターンあたり ~4k トークン超 のコードベースやログを読む → optimize モードで Headroom を実行。
• 電卓 API だけ → スキップ。
• OpenClaw 24/7 on 16 GB → ローカルでプロキシし、生ツール出力を Ollama に流さない。

ステップバイステップ runbook

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

python3 -m venv ~/.headroom-venv
source ~/.headroom-venv/bin/activate
pip install "headroom-ai[proxy]"
headroom --version

macOS では Homebrew Python を汚さないよう venv を使います。venv + キャッシュモデルで 約 1 GB を確保してください。

ステップ 2 — audit モード（リスクなく削減を確認）

headroom proxy --port 8787 --mode audit

テスト 1 件だけプロキシ経由（ステップ 4）。ログの「would compress X → Y tokens」を確認。audit はペイロードを変更しません。

ステップ 3 — optimize プロキシを起動

headroom proxy --port 8787 --mode optimize

ターミナルを開いたままにするか、ヘッドレス Mac mini では launchd で常駐化。デフォルト 8787 は Ollama 11434 と区別しやすいです。

ステップ 4 — Ollama クライアントを Headroom に向ける

OpenAI 互換クライアント向け：

export OPENAI_API_BASE="http://127.0.0.1:8787/v1"
export OPENAI_API_KEY="ollama"   # placeholder; Ollama ignores

Ollama 本体は http://127.0.0.1:11434 のまま。Headroom は設定に従い上流へ転送 — Headroom docs を参照。

テスト：

curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.2:3b","messages":[{"role":"user","content":"ping"}]}'

ステップ 5 — コーディング Agent を wrap（任意）

headroom wrap aider --model ollama/llama3.2:3b
# or: headroom wrap claude | codex | cursor | copilot

wrap は Agent コードを書き換えずに圧縮を注入します。

ステップ 6 — カスタム Agent 向け MCP サーバー

headroom mcp

headroom_compress、headroom_retrieve、headroom_stats を MCP クライアントに公開 — 独自 OpenClaw ツールパイプラインに有用（OpenClaw マルチエージェント）。

ステップ 7 — 前後比較を計測

# Ollama-side: watch context size in logs
OLLAMA_DEBUG=1 ollama serve 2>&1 | tee /tmp/ollama-debug.log

# Headroom stats (when available in your version)
headroom stats

太い read_file フィクスチャで同じプロンプトの time-to-first-token を記録。15k → 1.5k トークンなら最初のトークンは 2–10 倍 速くなることが多いです。

ステップ 8 — 24/7 Mac mini 向けに堅牢化

• プロキシを launchd の KeepAlive で実行（SSH 運用ガイド）
• 8–16 GB ホストでは OLLAMA_NUM_PARALLEL=1
• DeepSeek-R1 ガイド の Q4 quant と併用
• Understand Anything でリポジトリを先にマップし、盲目再取り込みを防ぐ
• 東京ノードで 24/7 ホストする場合も、HF 初回ダウンロードは有線 LAN で安定させると安全です

トラブルシューティング

プロキシ起動後も Agent が遅い

パターン： クライアントがプロキシを迂回し Ollama :11434 直叩き。修正： Agent プロセス環境で OPENAI_API_BASE=http://127.0.0.1:8787/v1 を確認（macOS は launchctl getenv）。export 後に Agent を再起動。

headroom_retrieve ループ / 詳細欠落

パターン： モデルがハッシュ取得を繰り返す。修正： 一度 simulate モードで圧縮形状を確認。ツールプロンプトを絞る（「上位 20 件のみ」）。CCR TTL 切れならツールを再実行。

初回ダウンロードで停止

パターン： インストール後にディスクアクティビティのみ。修正： 初回 optimize で 約 500 MB を許可。APFS 空き ≥ 5 GB。有線 Ethernet を推奨。

圧縮でエラー行が消えた

パターン： Agent がスタックトレースを見逃す。修正： LogCompressor は FATAL/ERROR を保持するはず — Headroom をアップグレード。CI では audit で比較してから optimize。

FAQ

まとめ

Mac mini や軽量サーバーでの ローカル LLM ツール遅延 は多くの場合 トークン量 の問題であり、GPU の謎の不具合ではありません。Headroom はツール出力・ログ・ファイル読み取りを Ollama に入る 前 に圧縮し、公開ワークロードでは 60–95% 小さなコンテキストと CCR による原文取得を実現します。

headroom-ai[proxy] をインストールし、headroom proxy --port 8787 --mode optimize を起動、Agent を http://127.0.0.1:8787/v1 に向け、最悪のツールで time-to-first-token を計測してください。DeepSeek と OpenClaw メモリ ガイドの量子化・RAM 予算と併用を。

公式：Headroom GitHub · Headroom docs。