你把 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。