本地小模型飛速編碼！Headroom 壓縮 90% 工具輸出，解決 Agent 卡頓（2026）

你在 Mac mini 上用 Ollama、DeepSeek 或 Llama 3 跑編碼 Agent——讓它 grep 整個 monorepo、tail 200 MB 日誌或讀取遷移 SQL 時，介面卡住、tok/s 暴跌。8B–14B 本地模型裡，工具輸出膨脹往往比模型智商更致命：未壓縮的每一字節都走同一套統一記憶體匯流排，約 20–40 tok/s。

Headroom 是開源 上下文壓縮層（Apache 2.0），在日誌與檔案讀入進入 LLM 之前 壓縮，通常減少 60–95% token，並透過 CCR（Compress-Cache-Retrieve）按需取回原文。本文面向本地優先方案；雲 API 降本見 Hermes 軌跡壓縮。

為何本地 Agent 在大工具輸出後「卡住」

本地推理延遲主要取決於上下文長度與記憶體頻寬，而不只是模型有多「聰明」。

可引用定義： 本地 LLM 工具延遲 = 工具返回完成到模型產出下一 token 的牆鐘時間——主要由未壓縮上下文的 prefill 主導，而非工具執行本身。

Apple Silicon 上若同時跑 OpenClaw 或 MLX sidecar，請配合 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——激進壓縮但不永久刪除。

外部文件：Headroom 快速開始、CCR 可逆壓縮。

決策矩陣：Mac mini Agent 怎麼選

若在 Mac mini 跑 OpenClaw： Headroom 支援將 OpenClaw 作為 wrap 目標與 ContextEngine 外掛——無需重寫 Agent 即可壓縮閘道工具流量。

若 X，則 Y： 單次 cat 後 7B 本地模型 prefill 超過 10 秒，應先啟用 Headroom，再考慮更大 GPU 或雲回退。

場景 A — Ollama + Headroom Proxy（零改 Agent 程式碼）

把 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 秒（因倉庫而異——請自行 benchmark）。

場景 B — 家庭伺服器 OpenClaw + Headroom MCP

在 OpenClaw MCP 棧使用 headroom_compress、headroom_retrieve、headroom_stats。配合 並發上限 更有意義——token 更少，16 GB 上可從只能 1 路並發提升到 2 路。

七步上手：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 的 Headroom proxy

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

（若建置僅支援環境變數路由，按 proxy 指南 設定 OPENAI_BASE_URL。）

步驟 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 壓縮浸泡測試

同一提示跑兩遍：

1. 直連 Ollama —「搜尋倉庫中所有 TODO 並貼上全部匹配。」
2. 經 Headroom — 相同提示。

記錄 headroom perf 或 MCP headroom_stats 的 token 數。

步驟 6 — 除錯時啟用 retrieve

若模型漏掉堆疊，指示：「對 ERROR 附近日誌段使用 headroom_retrieve。」CCR 應返回快取原文。

步驟 7 — LaunchAgent 持久化（可選 24/7 閘道）

proxy 與 Ollama 分別包進 LaunchAgent；按 記憶體指南 限制 Node 堆。重啟順序：Ollama → Headroom → Agent。

排錯

症狀：啟用 Headroom 後仍然很慢

模式： headroom_stats 显示二进制/protobuf 工具压缩比很低。
修復： 先经 JSON/文本格式化；源码 dump 启用 CodeCompressor；减少并行文件读取。

症狀：模型「遺失」失敗測試行

模式： 激进日志粉碎删掉了唯一的 FAIL 行。
修復： 调用 headroom_retrieve；收紧 SmartCrusher 保留错误关键词；Agent 看到输出前用 rg --json ERROR 预过滤。

症狀：Proxy 能連但 /v1/chat/completions 回傳 404

模式： 后端环境变量错误；Ollama 未运行。
修復： 执行 curl http://127.0.0.1:11434/api/tags；按已安装版本文档用正确 --backend 重启 headroom proxy。

推薦路徑

常見問題