本地小模型飞速编码！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 轨迹压缩。国内环境建议用 pip 镜像安装依赖，避免 npm/pip 拉取过慢拖垮首轮测试。

为何本地 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。

推荐路径

常见问题