你把 Ollama、DeepSeek 或 Llama 接到 Agent 框架，讓它讀整個 monorepo，界面卻卡住 三到八分鐘——不是崩潰，而是工具 JSON 把預填充拖垮。Mac mini M4 配 16–32 GB 統一內存時，單輪若塞進 4 萬–8 萬 token 的 npm test 輸出、SQL 轉儲或 ripgrep 結果，本地模型就會撞牆。雲端 API 按量計費；本地 GPU 則爲每個字節的注意力燒牆鍾時間。
Headroom 在內容進入模型之前壓縮工具輸出、日誌與 RAG 塊——公開負載顯示 SRE 追蹤可縮 92%，代碼搜索 73–92%。本 Type A 教程把 Headroom 接在 Ollama OpenAI 兼容 API 前，Agent 工具不變，模型卻只見 5k token 而非 50k 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 後一直轉圈 | 單條工具消息 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%，恢復原始日誌無法實現的亞分鐘級工具回合。
外部參考：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。
分步實操（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+ 建議 32 GB 以上纔有舒適 KV 餘量。
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 200優於 cat 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 頭），記錄你要消除的卡頓——數字寫入團隊 wiki。
故障排查
Agent 仍直連 11434
現象：Headroom /stats 請求數爲零。
修復：檢查進程環境（ps eww -p $(pgrep -f your-agent)）。Agent 進程的 OPENAI_BASE_URL 須爲 http://127.0.0.1:8787/v1，不能只在 shell 配置裏。
經代理 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。