OpenClaw via Headroom : réduire jusqu'à 80 % la facture API grâce au proxy de compression (2026)

Les audits nocturnes de dépôt d'OpenClaw lancent des linters, des exécuteurs de tests et des avalanches de grep qui renvoient des mégaoctets de JSON dans le contexte du modèle. Payer le prix public d'Anthropic pour chaque octet brut transforme une automatisation rigoureuse en poste de facture API à quatre chiffres. Headroom se place entre la passerelle et le fournisseur : un proxy local sur le port 8787 (par défaut) qui compresse les sorties d'outils, les journaux et l'historique avec SmartCrusher / CodeCompressor / CCR avant que les requêtes n'atteignent api.anthropic.com. Les benchmarks publiés montrent 92 % de réduction de tokens sur les traces de type SRE et 73–92 % sur les charges de recherche de code ; ce guide vise 60–80 %+ d'économies sur les tours gourmands en outils sans modifier le Markdown de vos skills.

Associez cela aux garde-fous de dépense de notre guide budgets de tokens et throttles d'outils OpenClaw et à la planification de passerelle dans LaunchAgents vs cron sur macOS. L'hygiène des secrets se trouve dans les profils openclaw.json et .env.

Divulgation : MacHTML propose en option la location d'un Mac mini cloud pour des passerelles de préproduction ; ce runbook est neutre vis-à-vis des fournisseurs et fonctionne sur tout hôte macOS.

Pourquoi OpenClaw + Headroom est une pile unique

OpenClaw excelle dans les passerelles permanentes : entrée Slack/Telegram, listes d'autorisation d'outils et skills multi-étapes qui relisent d'énormes arborescences de travail. Headroom excelle dans la compression de contexte — sans résumer votre intention, mais en réduisant ce que les outils renvoient. La combinaison est rare car la plupart des équipes ne choisissent qu'un levier :

Levier	Ce qu'il réduit	Angle mort
Throttles OpenClaw seuls	Nombre de tours, concurrence	Envoie encore 50 Ko de JSON de linter tel quel
Modèle plus petit seul	$/token en entrée/sortie	Rate des constats sur les audits complexes
Troncature manuelle des journaux dans les skills	Ad hoc	Casse la reproductibilité entre exécutions cron
Proxy Headroom + OpenClaw	Tokens outils/RAG/journaux avant le fournisseur	Requiert un processus Python 3.10+ local

Le README de Headroom répertorie OpenClaw comme une intégration de premier ordre (chemin de plugin ContextEngine plus proxy générique compatible OpenAI). Vous conservez l'orchestration d'OpenClaw ; Headroom réécrit la forme de la charge utile que voit le modèle.

Références externes : Headroom GitHub, documentation du proxy Headroom, API Anthropic.

Architecture : passerelle → proxy → Anthropic

┌─────────────┐   HTTP/SSE    ┌──────────────────────┐   HTTPS    ┌─────────────────┐
│ OpenClaw    │ ────────────► │ Headroom proxy       │ ────────► │ api.anthropic.com│
│ gateway     │ 127.0.0.1:8787│ SmartCrusher + CCR   │           │ (real API key)   │
│ :8788 tools │               │ /v1/messages         │           └─────────────────┘
└─────────────┘               └──────────────────────┘
        ▲                              │
        │ tool stdout/json             │ headroom_retrieve if model needs originals
        └──────────────────────────────┘

Règle de routage : OpenClaw lit les URL de base des fournisseurs depuis l'environnement (~/.openclaw/.env) et openclaw.json. Dirigez le trafic Anthropic vers Headroom, pas vers le point de terminaison public. Headroom relaie avec votre véritable ANTHROPIC_API_KEY issue de l'environnement du processus proxy — OpenClaw peut garder la même variable de clé, mais l'hôte doit être local.

Discipline des ports : le proxy Headroom écoute par défaut sur 8787 — le même port que de nombreux exemples de passerelle OpenClaw. En production, faites tourner Headroom sur 8787 et déplacez la passerelle OpenClaw vers 8788 (ou l'inverse). Documentez la paire dans vos plists LaunchAgent.

Runbook étape par étape (macOS 2026)

1. Installer Headroom avec les extras proxy

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

Sur Apple Silicon, pip install "headroom-ai[all]" est acceptable si le disque le permet ; la version proxy seule garde des images plus petites.

2. Démarrer le proxy avec journalisation et statistiques

export ANTHROPIC_API_KEY="sk-ant-..."   # real key — proxy forwards upstream
headroom proxy \
  --host 127.0.0.1 \
  --port 8787 \
  --log-file ~/.headroom/openclaw-proxy.jsonl

Vérifiez l'état :

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

Vous voulez optimize: true et un tokens_saved croissant après du trafic de test.

3. Acheminer les appels Anthropic d'OpenClaw via le proxy

Modifiez ~/.openclaw/.env (chmod 600) :

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=http://127.0.0.1:8787
# If you use OpenAI-compatible models in the same gateway:
# OPENAI_BASE_URL=http://127.0.0.1:8787/v1

Confirmez qu'OpenClaw résout l'env avant le démarrage de la passerelle — voir les profils JSON et .env. Ne committez pas ces lignes.

4. Déplacer la passerelle OpenClaw hors du port 8787 si nécessaire

Dans ~/.openclaw/openclaw.json, réglez le port d'écoute de la passerelle sur 8788 lorsque Headroom occupe 8787 :

{
  "gateway": {
    "port": 8788,
    "host": "127.0.0.1"
  }
}

Redémarrez la passerelle ; les sondes de santé doivent viser 8788, pas le port Headroom.

5. Optionnel — chemin de plugin natif Headroom pour OpenClaw

Headroom documente OpenClaw comme un plugin ContextEngine (headroom/providers/openclaw). Si vous préférez le mode plugin à l'URL de base brute :

pip install "headroom-ai[all]"
headroom wrap openclaw   # when available in your installed version

Si wrap openclaw est absent, restez sur proxy + ANTHROPIC_BASE_URL — c'est le chemin universel pris en charge selon la documentation du proxy.

6. Tester la compression à chaud avec une grosse charge d'outil

Déclenchez un skill qui renvoie un gros JSON (sortie de test ou résultats find). Comparez :

curl -s http://127.0.0.1:8787/stats | python3 -m json.tool
tail -n 5 ~/.headroom/openclaw-proxy.jsonl

Objectif : savings_percent tendant vers ≥40 % au premier audit réel ; les nuits gourmandes en outils dépassent souvent 60–80 %.

7. Pérenniser Headroom sous launchd (en parallèle d'OpenClaw)

Créez ~/Library/LaunchAgents/ai.headroom.proxy.plist avec des ProgramArguments appelant headroom proxy --host 127.0.0.1 --port 8787, des EnvironmentVariables pour ANTHROPIC_API_KEY et un StandardOutPath sous ~/.headroom/logs/. Chargez-le avant ai.openclaw.gateway pour que l'URL de base soit résolue au démarrage de la passerelle — modèles dans le guide LaunchAgent et cron.

8. Brancher des sidecars MCP / Claude Code (optionnel)

Headroom expose des outils MCP (headroom_compress, headroom_retrieve, headroom_stats). Pour les bacs à sable Claude Code qui alimentent les skills OpenClaw, installez MCP une fois :

headroom mcp install

Les skills OpenClaw peuvent appeler le même point de statistiques de compression à http://127.0.0.1:8787/stats pour des tableaux de bord.

9. Définir des garde-fous de budget sur le proxy

headroom proxy --port 8787 --budget 50.0 --log-file ~/.headroom/openclaw-proxy.jsonl

--budget 50.0 fixe un plafond quotidien en USD dans Headroom — il complète, sans les remplacer, les throttles par tour d'OpenClaw.

10. Valider avec openclaw doctor

openclaw doctor

doctor doit montrer la passerelle saine sur 8788, le fournisseur joignable via 127.0.0.1:8787 et aucun double bind de port (EADDRINUSE).

Modèle de pipeline d'audit nocturne

En général, un cron ou un LaunchAgent à 02h00 locales déclenche un skill OpenClaw :

1. git fetch --all et diff par rapport à main
2. Exécuter npm test / eslint / un script d'audit personnalisé via les outils autorisés
3. Publier un résumé sur Slack

Sans Headroom, l'étape 2 injecte souvent 15k–65k tokens de stderr (benchmark SRE publié : 65 694 → 5 118 tokens). Avec la compression du proxy, la même ligne FATAL reste repérable via la récupération CCR si le modèle demande les originaux.

À citer : Acheminer le trafic Anthropic d'OpenClaw via Headroom sur 127.0.0.1:8787 peut réduire le contexte gourmand en outils de 60 à 92 % tout en préservant la réversibilité grâce à CCR — à empiler avec les throttles OpenClaw pour le contrôle des dépenses, non en remplacement.

Comparez les choix de harnais dans Hermes vs OpenClaw lorsque vous séparez la compression mémoire de la compression d'outils en couche HTTP.

Dépannage

La passerelle renvoie 502 / connexion refusée au chat

Symptôme : les journaux OpenClaw montrent des erreurs amont juste après l'activation du proxy.

Correctif : vérifiez que Headroom écoute (curl http://127.0.0.1:8787/health). Si la passerelle et le proxy ont tous deux tenté 8787, séparez les ports (étape 4). Rechargez les LaunchAgents dans l'ordre : Headroom d'abord, OpenClaw ensuite.

Les économies restent proches de 0 % dans /stats

Symptôme : tokens_saved stagne ; transforms vide.

Correctif : assurez-vous que le trafic passe réellement par le proxy — ANTHROPIC_BASE_URL doit être défini dans l'environnement du processus de la passerelle, pas seulement dans votre shell interactif. Pour déboguer le passthrough, lancez temporairement headroom proxy --no-optimize et comparez. Les grosses charges doivent être des corps d'outils/messages, pas de minuscules prompts.

Le modèle « perd » les détails de la trace de pile

Symptôme : le tour compressé omet les numéros de ligne attendus par les auditeurs.

Correctif : Headroom CCR stocke les originaux localement ; ajoutez dans le skill un texte autorisant headroom_retrieve ou définissez x-headroom-bypass: true sur un tour de diagnostic. Ne désactivez pas la compression globalement pour les exécutions nocturnes — corrigez plutôt la politique de récupération.

EMFILE ou pic CPU sur le Mac mini

Symptôme : audits simultanés + compression ML (--llmlingua) saturent l'Apple Silicon.

Correctif : retirez --llmlingua sauf besoin de réduction maximale ; alignez-vous sur les limites de parallélisme d'outils / ulimit. Plafonnez les appels d'outils simultanés d'OpenClaw à 3–5 pendant les fenêtres cron.

FAQ

Headroom remplace-t-il les throttles de tokens d'OpenClaw ?

Non. Headroom réduit ce qui entre dans le modèle ; OpenClaw limite la fréquence à laquelle les outils se déclenchent. Utilisez les deux — voir le runbook de budget de tokens.

L'économie de 80 % est-elle garantie ?

Headroom publie des plages de 60–95 % selon la charge. Les audits OpenClaw gourmands en outils atteignent souvent 60–92 % ; les tours conversationnels courts économisent moins. Mesurez /stats sur votre dépôt.

Anthropic bloquera-t-il les requêtes passées par le proxy ?

Headroom relaie vers l'API officielle avec votre clé — comme l'usage direct du SDK. Gardez ANTHROPIC_API_KEY uniquement sur l'hôte du proxy ; effectuez une rotation en cas de fuite des journaux.

Puis-je exécuter Headroom sous Linux pendant qu'OpenClaw reste sur macOS ?

Oui — définissez ANTHROPIC_BASE_URL=http://linux-host:8787 si le pare-feu l'autorise. Les passerelles sensibles à la latence préfèrent un proxy co-localisé sur le même Mac mini.

Comment cela se compare-t-il à la compression de trajectoire Hermes ?

Hermes compresse les transcriptions de mémoire d'agent ; Headroom compresse les sorties d'outils et messages au niveau HTTP. Pour le choix du harnais, lisez Hermes vs OpenClaw — les piles peuvent coexister sur des hôtes différents.

Vous utilisez Ollama local plutôt qu’Anthropic ? Le même proxy Headroom réduit les charges outils pour modèles locaux — voir Headroom + Ollama latence locale pour corriger le prefill sur Mac mini 16 Go.