Lokale LLMs beschleunigen: Headroom reduziert Agent-Kontext um 95 % für flotte Tool-Antworten

Sie haben Ollama, DeepSeek oder Llama an ein Agent-Framework angeschlossen, das ganze Monorepos lesen lassen — und die Oberfläche hing drei bis acht Minuten fest: kein Crash, sondern Prefill, ertrunken im Tool-JSON. Auf einem Mac mini M4 mit 16 bis 32 GB Unified Memory stoßen lokale Modelle an ihre Grenze, wenn ein einziger Turn 40.000 bis 80.000 Tokens aus npm test, SQL-Dumps oder ripgrep-Ergebnissen liefert. Cloud-APIs berechnen nach Nutzung; die lokale GPU verbrennt Echtzeit für Attention pro Byte.

Headroom komprimiert Tool-Ausgaben, Logs und RAG-Blöcke bevor sie ins Modell gelangen — veröffentlichte Workloads zeigen 92 % Reduktion bei SRE-Traces und 73–92 % bei Codesuche. Dieses Type-A-Tutorial setzt Headroom vor die OpenAI-kompatible API von Ollama: Agent-Tools bleiben unverändert, das Modell sieht nur 5.000 Tokens statt eines Berges von 50.000 Tokens. Kostenkontrolle über Cloud-Gateway: OpenClaw + Headroom-Proxy; lokaler Trading-Stack ohne API: TradingAgents auf Ollama.

Hinweis: MacHTML bietet optionale Cloud-Mac-mini-Miete; dieser Leitfaden gilt für jeden lokalen macOS- oder Linux-Host mit installiertem Ollama.

Warum lokale Agenten bei großen Tool-Ausgaben „einfrieren“

Auf Apple Silicon ist die Prefill-Latenz lokaler LLMs ungefähr linear zur Kontextlänge — es gibt keine „unbegrenzter Kontext“-Magie bei 30 tok/s, wenn man ein ganzes CI-Log injiziert. Symptome, die Betreiber oft mit einem Freeze verwechseln:

Symptom	Wahrscheinliche Ursache	Headroom-Hebel
Spinner nach read_file auf 2-MB-Log	Über 50.000 Tokens in einer Tool-Nachricht	SmartCrusher / LogCompressor
Erster Turn schnell, Hänger beim 5. Turn	Kontext schneit über mehrere Tool-Turns	CCR + IntelligentContext drops
Speicherdruck, Swap auf Mac mini 16 GB	KV-Cache + Riesen-Prompt	60–95 % weniger Prefill-Tokens
„Mit GPT-4o ging es“	Größeres Cloud-Modell / schnelleres Silizium	Lokal braucht Kompression + kleineren effektiven Kontext

Zitierbar: Auf Mac-mini-Klasse-Hardware kann Agent-Traffic über Headroom auf 127.0.0.1:8787 zu Ollama auf 11434 tool-lastige Prompts um 60–95 % verkleinern und Tool-Turns unter einer Minute wiederherstellen — mit Rohlogs unmöglich.

Externe Referenzen: Headroom GitHub, Proxy-Dokumentation, Ollama API.

Architektur der Kompressionsschicht

┌──────────────┐  工具 JSON/日志   ┌─────────────────────┐  压缩后      ┌─────────────┐
│ Agent        │ ────────────────► │ Headroom 代理       │ ───────────►│ Ollama      │
│ (OpenClaw、  │  OPENAI_BASE_URL  │ :8787               │  聊天 API    │ :11434/v1   │
│  LangGraph、 │  = localhost:8787 │ SmartCrusher + CCR  │              │ llama3 等   │
│  Aider…)     │                   │                     │              │             │
└──────────────┘                   └─────────────────────┘              └─────────────┘

Der Headroom-Proxy stellt die OpenAI-kompatible /v1/chat/completions-API bereit — dieselbe Schnittstelle wie Ollama. Sie richten den Agent-Client auf Headroom; Headroom komprimiert und leitet an die Ollama-Upstream-URL weiter.

Schritt-für-Schritt (Ollama + Headroom)

1. Referenz-Ollama auf dem Host

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

Wählen Sie ein RAM-passendes Modell: 3B–8B auf Mac mini 16 GB für Agent-Schleifen; 14B+ braucht 32 GB oder mehr für komfortablen KV-Spielraum.

2. Headroom-Proxy-Stack installieren

python3 --version   # 3.10+
pip install "headroom-ai[proxy]"
headroom --version

3. Headroom starten und auf Ollama zeigen

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

Prüfung:

curl -s http://127.0.0.1:8787/health | python3 -m json.tool

4. Agent-SDK auf Headroom, nicht direkt auf Ollama

export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=ollama-local

Lokales OpenClaw-Modell — in ~/.openclaw/.env konfigurieren; Eingangsmodus kann mit OpenClaw + Ollama-Webhook kombiniert werden.

5. Bibliotheksmodus für eigenen 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"])

Wenn Sie HTTP selbst orchestrieren, vermeidet der Bibliotheksmodus Proxy-Port-Konflikte.

6. Tool-Payloads vor Kompression begrenzen (doppelte Absicherung)

rg -n "ERROR" logs/ | head -n 200

Besser als cat logs/build.log. Headroom rettet grobe Skills, aber ein 200-Zeilen-Limit begrenzt Worst-Case-Latenz auf 16-GB-Hosts.

7. Einsparungen und Latenz messen

curl -s http://127.0.0.1:8787/stats | python3 -m json.tool

Pro Turn tokens_before, tokens_after und Echtzeit notieren. Beim ersten Repo-Audit ≥50 % Reduktion anstreben; JSON-/Such-Dumps erreichen oft 60–90 %.

8. Optionales MCP: Claude Code + lokaler Ollama-Sidecar

headroom mcp install

Nützlich, wenn das lokale Modell in einem anderen Terminal läuft — MCP headroom_stats; praktisch beim Mix aus Cloud-Hermes-Speicherkompression und lokalem Headroom.

9. Proxy-Persistenz per launchd (dauerhaft laufender Mac mini)

Erstellen Sie ~/Library/LaunchAgents/ai.headroom.ollama.plist, setzen Sie OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1, laden Sie vor dem Agent-Gateway. Ollama in separatem LaunchAgent — Startreihenfolge: Ollama → Headroom → Agent.

10. Regressionstest nach Modellwechsel

Nach ollama pull eines neuen Tags ein Szenario mit fettem Tool erneut ausführen. Quantisierungsgewinne ersetzen keine Kompression — Kontextlänge dominiert weiterhin den Prefill.

Mac-mini-Benchmark-Vorlage

Szenario	Roh-Tokens (typisch)	Nach Headroom (typisch)	Echtzeit-Ziel
Fehlgeschlagene Suite npm test stderr	25.000–45.000	3.000–8.000	M4 16 GB Prefill <45 s
find . -name '*.ts'-Liste	15.000–30.000	2.000–5.000	<30 s
Einzelner 500-KB-JSON-API-Dump	40.000–70.000	4.000–10.000	<60 s

Jedes Szenario einmal mit Proxy-Bypass (x-headroom-bypass: true-Header) laufen lassen, Freeze-Zeit notieren — Zahlen ins Team-Wiki.

Fehlerbehebung

Agent verbindet sich noch direkt mit 11434

Symptom: null Anfragen in Headroom /stats.

Fix: Prozessumgebung prüfen (ps eww -p $(pgrep -f your-agent)). OPENAI_BASE_URL des Agent-Prozesses muss http://127.0.0.1:8787/v1 sein, nicht nur in der Shell-Konfiguration.

Ollama 404 Modell nicht gefunden über Proxy

Symptom: Upstream-404 in Headroom-Logs.

Fix: Modellname in der Chat-Anfrage muss zu ollama list passen; zuerst lokal pullen — Headroom verwaltet keine Modelldateien.

Kompression entfernt nötige Stack-Zeilen

Symptom: fehlende Zeilennummern im Audit.

Fix: CCR-Abruf im Skill aktivieren („headroom_retrieve aufrufen, wenn Stack unvollständig“) oder einen Turn bypassen. Kompression nicht global deaktivieren.

Mac mini durch Swap blockiert

Symptom: kritischer memory_pressure während Agent-Lauf.

Fix: leichtere Quantisierung (:q4_0), weniger parallele Tools, Headroom hinzufügen. Auf 16 GB 14B + 80.000 Roh-Tokens parallel vermeiden.

Häufige Fragen

Funktioniert Headroom nur mit OpenAI Cloud?

Nein. Der Proxy komprimiert und leitet an jeden OpenAI-kompatiblen Upstream weiter — Ollama, lokales vLLM oder Cloud. OPENAI_TARGET_API_URL auf Ihren lokalen Dienst zeigen.

Ist 95 % Kompression realistisch?

Manche Agent-Workloads erreichen öffentlich 92 %; bei gemischten Repos eher 60–80 %. Mit /stats messen — nicht jeden Turn das Marketing-Maximum annehmen.

Hilft es gegen GPU-Überhitzung?

Gegenüber riesigem Roh-Prompt reduziert weniger Prefill-Arbeit die Wärme — aber kontinuierliche Tool-Schleifen verbrauchen weiter CPU/GPU. powermetrics auf Mac mini beobachten.

Headroom vs. Hermes trajectory_compressor?

Hermes komprimiert langen Gesprächsspeicher; Headroom komprimiert Tool- und RAG-Payloads auf HTTP-/Bibliotheksebene. Beide können cloud/lokal hybrid koexistieren.

Brauche ich Headroom mit Anthropic Cloud?

Optional für Kostenkontrolle; lokale Modelle hängen oft davon ab, nutzbar zu bleiben. Bei Provider-Mix siehe Cloud OpenClaw Headroom.