Lokale LLMs beschleunigen: Headroom kürzt Agent-Kontext um 95 % (2026)

Sie betreiben Ollama, DeepSeek-R1 oder Llama 3 auf einem Mac mini oder leichten VPS und schalten einen Agent an, der Repos liest, Logs tailt oder Datenbanken abfragt. Der erste Tool-Aufruf liefert 50.000 Tokens JSON. Ihr lokales 7B-Modell friert 90+ Sekunden ein. Activity Monitor zeigt wenig CPU; die UI wirkt tot. Das ist kein „dummes Modell“ — Kontextaufblähung erdrückt Tokens-per-second auf kleiner Hardware.

Cloud-Agents verbergen das mit 200k-Fenstern und schnellen GPUs. Auf 8–16 GB Apple Silicon oder 2 vCPU kostet jede redundante Logzeile Prefill-Sekunden. Linux-Guides erwähnen selten reversible Tool-Output-Kompression — Lücke, die Headroom als Apache-2.0-Kontextoptimierungsschicht füllt.

Dieser Guide richtet sich an Homelab-Bauer mit lokaler Inferenz. Sie lernen, warum Tool-Latenz explodiert, die Compress-Cache-Retrieve (CCR)-Architektur und ein 8-Schritte-Runbook für den Proxy vor Ollama — mit Links zu DeepSeek-R1-Quantisierung, OpenClaw-Routing, Mac-mini-Speicher, Codebase-Mapping. ZecCloud bietet Mac-mini-Hosts für 24/7-Agents; Fokus hier: Headroom-Docs, keine Mietpreise.

Einleitung

Latenzmodell, Headroom-Architektur, Matrix, 8-Schritte-Runbook, Troubleshooting und 6 FAQ.

Warum lokale Agents bei großen Tool-Outputs „hängen“

User → LLM plans tool → Tool returns huge payload → LLM reads ALL bytes → Next token

Auf Mac mini M4 mit Llama 3.2 3B Q4 via Ollama liegen Community-Benchmarks bei 40–80 tok/s Generierung, aber 32k Token Tool-Dump-Prefill kann zehntel Sekunden dauern. Das Modell „denkt“ nicht — es verschluckt Testzeilen, doppelte JSON-Keys, grep-Wälder.

Weniger Kontext bedeutet weniger Druck auf den gemeinsamen Pool (Mac-mini-OpenClaw-Speicher-Guide).

Headroom-Architektur: Proxy, Router und CCR

Headroom sitzt zwischen Agent und LLM-Provider — Bibliothek, lokaler Proxy, MCP-Server oder headroom wrap für Claude Code / Cursor / Aider.

Agent (OpenClaw, Aider, custom)
    │  tool outputs, logs, file reads, RAG chunks
    ▼
Headroom proxy :8787  ── ContentRouter ──┬─ SmartCrusher (JSON arrays)
    │                                      ├─ CodeCompressor (AST, tree-sitter)
    │                                      ├─ LogCompressor (failures kept)
    │                                      └─ Kompress-base (prose)
    ▼
CCR store (originals cached locally, hash-addressable)
    ▼
Ollama / OpenAI-compatible API

CCR bedeutet reversible Kompression: Originale lokal gecacht; Modell ruft headroom_retrieve bei Bedarf. Öffentliche Beispiele: 60–95 % weniger Tokens bei Logs und Tool-JSON (Headroom GitHub).

Erster Lauf: ggf. ~500 MB Routing-Modelle. Platz auf 256-GB-Mac-mini neben Ollama-Gewichten planen.

Latenz-Matrix: wann Kompression gewinnt

• Agent liest Codebases/Logs >~4k Tokens/Runde → Headroom optimize.
• Nur Taschenrechner-API → überspringen.
• OpenClaw 24/7 auf 16 GB → lokal proxen; keine rohen Tool-Outputs in Ollama.

Schritt-für-Schritt-Runbook

Schritt 1 — Headroom installieren (Python 3.10+)

python3 -m venv ~/.headroom-venv
source ~/.headroom-venv/bin/activate
pip install "headroom-ai[proxy]"
headroom --version

venv auf macOS. ~1 GB für venv + Cache-Modelle.

Schritt 2 — Audit-Modus

headroom proxy --port 8787 --mode audit

Eine Testanfrage durch den Proxy (Schritt 4). Audit ändert Payloads nicht.

Schritt 3 — Optimize-Proxy starten

headroom proxy --port 8787 --mode optimize

Terminal offen lassen oder launchd auf headless Mac mini. 8787 vs. Ollama 11434.

Schritt 4 — Ollama-Client auf Headroom zeigen

export OPENAI_API_BASE="http://127.0.0.1:8787/v1"
export OPENAI_API_KEY="ollama"   # placeholder; Ollama ignores

Ollama bleibt auf http://127.0.0.1:11434. Headroom docs.

curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.2:3b","messages":[{"role":"user","content":"ping"}]}'

Schritt 5 — Coding-Agents wrappen (optional)

headroom wrap aider --model ollama/llama3.2:3b
# or: headroom wrap claude | codex | cursor | copilot

Schritt 6 — MCP-Server für Custom-Agents

headroom mcp

Für OpenClaw-Pipelines (OpenClaw Multi-Agent).

Schritt 7 — Vorher/Nachher messen

# Ollama-side: watch context size in logs
OLLAMA_DEBUG=1 ollama serve 2>&1 | tee /tmp/ollama-debug.log

# Headroom stats (when available in your version)
headroom stats

Time-to-first-token mit fettem read_file. 15k → 1,5k Tokens → oft 2–10× schneller.

Schritt 8 — Für 24/7 Mac mini härten

• Proxy unter launchd KeepAlive (SSH-Guide)
• OLLAMA_NUM_PARALLEL=1 auf 8–16 GB
• Q4-Quants aus DeepSeek-R1-Guide
• Repos mit Understand Anything vorab mappen

Troubleshooting

Proxy läuft, Agent noch langsam

Muster: Client umgeht Proxy, trifft Ollama :11434. Fix: OPENAI_API_BASE=http://127.0.0.1:8787/v1 im Agent-Prozess (launchctl getenv auf macOS).

headroom_retrieve-Schleife / fehlendes Detail

Muster: Modell holt Hashes wiederholt. Fix: einmal simulate; Tool-Prompts enger; Tool neu bei abgelaufenem CCR-TTL.

Erster Download hängt

Muster: nur Disk-Aktivität. Fix: ~500 MB erlauben; ≥5 GB APFS frei; Ethernet.

Fehlerzeile durch Kompression weg

Muster: Stacktrace verpasst. Fix: LogCompressor behält FATAL/ERROR; Headroom updaten; audit vor optimize in CI.

FAQ

Fazit

Lokale LLM-Tool-Latenz auf Mac mini ist meist ein Token-Volumen-Problem. Headroom komprimiert Tool-Outputs, Logs und Dateilesungen vor Ollama — 60–95 % kleinerer Kontext mit CCR für Originale.

headroom-ai[proxy] installieren, headroom proxy --port 8787 --mode optimize starten, Agents auf http://127.0.0.1:8787/v1. Mit DeepSeek- und OpenClaw-Speicher-Guides kombinieren.

Offiziell: Headroom GitHub · Headroom docs.