Ollama、DeepSeek、Llama を Agent フレームワークに接続し、monorepo 全体を読ませると、UI が 3〜8 分固まる——クラッシュではなく、ツール JSON がプリフィルを押し潰しています。Mac mini M4 に 16〜32 GB のユニファイドメモリを載せたローカルモデルは、1 ターンで 4 万〜8 万 token の npm test 出力、SQL ダンプ、ripgrep 結果が入ると壁に当たります。クラウド API は従量課金、ローカル GPU は各バイトへの注意計算で実時間を消費します。
Headroom は、コンテンツがモデルに入る前にツール出力・ログ・RAG チャンクを圧縮します——公開ワークロードでは SRE トレースで 92%、コード検索で 73〜92% の縮小が報告されています。本 Type A チュートリアルでは、Ollama OpenAI 互換 API の手前に Headroom を配線し、Agent のツールはそのまま、モデルには 50k token の山ではなく 5k token のビューだけを渡します。クラウドゲートウェイのコスト制御は OpenClaw + Headroom プロキシ、ゼロ API のローカル取引スタックは Ollama 上の TradingAgents を参照してください。
開示：MacHTML はオプションのクラウド Mac mini レンタルを提供しています。本マニュアルは Ollama がインストールされた任意のローカル macOS または Linux ホストで利用できます。
大きなツール出力でローカル Agent が「フリーズ」する理由
Apple Silicon 上のローカル LLM のプリフィル遅延は、おおむねコンテキスト長に線形です——CI ログ全体を流し込んでも、30 tok/s の「無限コンテキスト」魔法はありません。運用者がフリーズと誤認しがちな症状は次のとおりです。
| 症状 | 想定原因 | Headroom のレバー |
|---|---|---|
2 MB ログの read_file 後ずっとスピナー | 1 件のツールメッセージに 5 万+ token | SmartCrusher / LogCompressor |
| 初回は速いが 5 ターン目で停止 | 複数ターンのツールコンテキストが雪だるま式に増大 | CCR + IntelligentContext による破棄 |
| 16 GB Mac mini でメモリ逼迫・スワップ | KV キャッシュ + 巨大 prompt | プリフィル token を 60〜95% 削減 |
| 「GPT-4o では問題なかった」 | クラウドモデルは幅広く／シリコンが高速 | ローカルは圧縮 + より小さい実効コンテキストが必要 |
引用可能：Mac mini クラスのハードウェアでは、Agent トラフィックを 127.0.0.1:8787 の Headroom 経由で 11434 の Ollama に向けると、ツール密集の prompt を 60〜95% 削減し、生ログでは不可能だった 1 分未満のツールターンを回復できます。
外部参照：Headroom GitHub、プロキシドキュメント、Ollama API。
圧縮レイヤーアーキテクチャ
┌──────────────┐ 工具 JSON/日志 ┌─────────────────────┐ 压缩后 ┌─────────────┐
│ Agent │ ────────────────► │ Headroom 代理 │ ───────────►│ Ollama │
│ (OpenClaw、 │ OPENAI_BASE_URL │ :8787 │ 聊天 API │ :11434/v1 │
│ LangGraph、 │ = localhost:8787 │ SmartCrusher + CCR │ │ llama3 等 │
│ Aider…) │ │ │ │ │
└──────────────┘ └─────────────────────┘ └─────────────┘Headroom プロキシは OpenAI 互換の /v1/chat/completions を提供します——Ollama と同じインターフェースです。Agent クライアントを Headroom に向け、Headroom が圧縮したうえで Ollama のアップストリーム URL に転送します。MacHTML の東京ノードでも同じ配線で、Agent 側の OPENAI_BASE_URL だけを 127.0.0.1:8787 に差し替えれば動作します。
ステップバイステップ（Ollama + Headroom）
1. ホスト上のベースライン Ollama
ollama --version
ollama pull llama3.2:3b # 或 deepseek-r1:7b、qwen2.5-coder 等
curl -s http://127.0.0.1:11434/api/tags | python3 -m json.toolメモリに合わせてモデルを選びます。16 GB Mac mini の Agent ループには 3B〜8B が適切です。14B+ は快適な KV 余裕のため 32 GB 以上を推奨します。
2. Headroom プロキシスタックのインストール
python3 --version # 3.10+
pip install "headroom-ai[proxy]"
headroom --version3. Headroom を起動し Ollama を指す
export OPENAI_API_KEY=ollama-local
export OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1
headroom proxy --host 127.0.0.1 --port 8787 \
--log-file ~/.headroom/ollama-agent.jsonl検証：
curl -s http://127.0.0.1:8787/health | python3 -m json.tool4. Agent SDK を Headroom に向け、Ollama 直結を避ける
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=ollama-localOpenClaw ローカルモデル——~/.openclaw/.env で設定します。エントリーモードは OpenClaw + Ollama Webhook と組み合わせ可能です。
5. カスタム Python Agent のライブラリモード
from headroom import compress
import ollama
messages = [...] # 含臃肿 tool 角色
result = compress(messages, model="llama3.2")
response = ollama.chat(model="llama3.2", messages=result.messages)
print(response["message"]["content"])HTTP を自前で編成している場合、ライブラリモードでプロキシポートの競合を避けられます。
6. 圧縮前にツールペイロードを制限（二重の安全策）
rg -n "ERROR" logs/ | head -n 200cat logs/build.log より優れます。Headroom は粗い Skill も救えますが、200 行上限が 16 GB ホストの最悪遅延を抑えます。
7. 削減量と遅延の計測
curl -s http://127.0.0.1:8787/stats | python3 -m json.tool各ターンの tokens_before、tokens_after、実時間を記録します。初回のリポジトリ監査では 50% 以上の縮小を目標にしてください。JSON／検索系ツールダンプでは 60〜90% が一般的です。
8. オプション MCP：Claude Code + ローカル Ollama サイドカー
headroom mcp installローカルモデルを別ターミナルで動かしているとき、MCP の headroom_stats が使えます——クラウドの Hermes 記憶圧縮 とローカル Headroom を併用する際に便利です。
9. launchd でプロキシを常駐化（常時稼働 Mac mini）
~/Library/LaunchAgents/ai.headroom.ollama.plist を作成し、OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1 を設定して、Agent ゲートウェイより前に読み込みます。Ollama は別 LaunchAgent にします。起動順は Ollama → Headroom → Agent です。
10. モデル変更後のリグレッション確認
ollama pull で新タグを取得したら、肥大化したツールのフィクスチャを再実行してください。定量化だけでは圧縮に代わりません——コンテキスト長がプリフィルを支配し続けます。
Mac mini ベンチマークパターン
| フィクスチャ | 生 token（典型） | Headroom 後（典型） | 実時間目標 |
|---|---|---|---|
失敗スイート npm test stderr | 2.5 万〜4.5 万 | 3k〜8k | M4 16 GB でプリフィル <45 秒 |
find . -name '*.ts' 一覧 | 1.5 万〜3 万 | 2k〜5k | <30 秒 |
| 単一 500 KB JSON API ダンプ | 4 万〜7 万 | 4k〜10k | <60 秒 |
各フィクスチャをプロキシバイパス（x-headroom-bypass: true ヘッダー）でも 1 回実行し、解消したい停止時間を記録してチーム wiki に残してください。
トラブルシューティング
Agent が依然として 11434 直結
現象：Headroom の /stats リクエスト数がゼロ。
修正：プロセス環境を確認します（ps eww -p $(pgrep -f your-agent)）。Agent プロセスの OPENAI_BASE_URL は http://127.0.0.1:8787/v1 である必要があり、シェル設定だけでは不十分です。
プロキシ経由で Ollama が 404 モデル不存在
現象：Headroom ログにアップストリーム 404。
修正：チャットリクエストのモデル名は ollama list と一致させてください。先にローカルで pull します。Headroom はモデルファイルを管理しません。
圧縮で必要なスタック行が消える
現象：監査で行番号が欠落。
修正：Skill で CCR 取得を有効にします（「スタックが不完全なら headroom_retrieve を呼ぶ」）か、単一ターンをバイパスします。圧縮をグローバルに無効化しないでください。
Mac mini がスワップで実質停止
現象：Agent 実行中に memory_pressure が危機的。
修正：より小さい量子化（:q4_0）、並列ツールの削減、Headroom の追加を行います。16 GB では 14B + 8 万の生コンテキストを同時に走らせないでください。
よくある質問
Headroom は OpenAI クラウド専用ですか？
いいえ。プロキシは圧縮後、任意の OpenAI 互換アップストリーム——Ollama、ローカル vLLM、クラウド——に転送します。OPENAI_TARGET_API_URL をローカルサービスに向ければ十分です。
95% 圧縮は現実的ですか？
一部の Agent ワークロードで公開値は最大 92% です。混合リポジトリでは 60〜80% が一般的です。/stats で実測してください——毎ターン、マーケティング上限を前提にしないでください。
GPU 過熱の緩和になりますか？
巨大な生 prompt と比べれば、プリフィル作業量の低下で発熱は減ります——ただし継続的なツールループは CPU/GPU を消費し続けます。Mac mini では powermetrics を確認してください。
Headroom と Hermes の trajectory_compressor の違いは？
Hermes は長い会話記憶を縮小します。Headroom は HTTP／ライブラリ層でツールと RAG ペイロードを縮小します。クラウドとローカルのハイブリッドでは両方併用できます。
クラウド Anthropic を使う場合も Headroom は必要ですか？
コスト制御なら任意です。ローカルモデルでは、使えるかフリーズかの分岐点になることが多いです。プロバイダー混在は クラウド OpenClaw Headroom を参照してください。
クラウド Mac mini で Ollama + Headroom を構築
Apple Silicon 上で SSH/VNC 経由でプロキシと Ollama を稼働——Agent ループを本番投入する前に、ポート、LaunchAgent の順序、肥大ツールのベンチマークを検証してください。