# PR #1 — openclaw-billing-proxy : HEARTBEAT_OK + sessions_* manquants + scan NVM

- **URL source** : https://github.com/zacdcook/openclaw-billing-proxy/pull/1
- **Repo parent** : https://github.com/zacdcook/openclaw-billing-proxy (501 stars, 132 forks, MIT, JavaScript, cree 2026-04-05)
- **Auteur PR** : @liewjiajun (contributeur externe)
- **Mergeur** : @zacdcook (owner du repo)
- **Branche** : `fix/heartbeat-and-nvm-scan` → `master`
- **Date d'ouverture** : 2026-04-06 06:55 UTC
- **Date de merge** : 2026-04-06 07:10 UTC (mergee en 15 min — review eclair)
- **Statut** : MERGED
- **Diff** : +63 / -6 sur 5 fichiers (`CHANGELOG.md`, `README.md`, `config.example.json`, `proxy.js`, `setup.js`)
- **Date d'acces** : 2026-05-23
- **Type** : Pull Request GitHub
- **Thematique** : Proxy de facturation Anthropic, contournement de la detection "third-party tools", subscription Claude Max/Pro vs Extra Usage
- **Licence repo** : MIT
- **Langage** : JavaScript (Node 18+)

## Resume executif

PR de contribution externe qui ajoute trois corrections au proxy `openclaw-billing-proxy` (un middleman HTTP qui force les requetes OpenClaw a etre facturees sur l'abonnement Claude Max/Pro plutot que sur l'Extra Usage, suite a la decision d'Anthropic du 4 avril 2026 de revoquer la facturation subscription pour les outils tiers). La PR (1) ajoute la sanitisation du trigger `HEARTBEAT_OK` decouvert par recherche binaire sur un system prompt de 103 KB, (2) ajoute les outils `sessions_store` et `sessions_yield_interrupt` apparus dans OpenClaw 2026.4.x, (3) fait scanner `setup.js` les chemins NVM (`~/.nvm/versions/node/*/lib/...`). Mergee en 15 minutes par le mainteneur avec un commit de cleanup post-merge supprimant un debug log qui dumpait les bodies dans `/tmp/`. Devenue la version v1.3.0 du proxy.

## Objectif du projet (le repo parent, contexte indispensable)

`openclaw-billing-proxy` est un proxy HTTP local (port 18801 par defaut) qui s'intercale entre OpenClaw (un assistant code tiers, fork ou alternative a Claude Code) et l'API Anthropic. Apres le 4 avril 2026, Anthropic a coupe la facturation subscription pour les outils tiers : les requetes OpenClaw partaient automatiquement en Extra Usage (paiement a l'usage). Le proxy injecte l'identifiant de facturation Claude Code et echange le token pour faire passer les requetes OpenClaw pour des sessions Claude Code legitimes, ce qui les replace dans l'abonnement Max/Pro.

A la date de la PR (v1.2.0 → v1.3.0), Anthropic ne fait que du matching de chaines (Layer 1-2 dans la nomenclature du repo). A partir du 8 avril 2026, Anthropic a upgrade vers du fingerprinting multi-couches (tool names + system template + cumulative body density), declenchant la v2.0.0 du proxy avec un traitement bidirectionnel en 7 couches.

## Architecture / Structure du repo

```
.
├── proxy.js             (43.6 KB)  Coeur du proxy HTTP — 7 layers de traitement bidirectionnel
├── setup.js             (13.7 KB)  Auto-detection credentials + scan tools OpenClaw + ecriture config
├── troubleshoot.js      (15.9 KB)  Diagnostic 8 layers (credentials, token, API, billing, triggers, health, e2e)
├── config.example.json  (774 B)    Exemple de config (replacements + reverseMap)
├── .env.example         (580 B)    OAUTH_TOKEN / PROXY_PORT / PROXY_HOST
├── Dockerfile           (74 B)     node:18-alpine
├── docker-compose.yml   (1.1 KB)   Health check + volume ~/.claude readonly + bind localhost
├── CHANGELOG.md         (18.9 KB)  Historique tres detaille jusqu'a v2.2.4
├── README.md            (13.7 KB)
└── LICENSE              (MIT)
```

## Contenu detaille de la PR

### Probleme 1 — `HEARTBEAT_OK` comme trigger Anthropic

Le system prompt OpenClaw contient des instructions de heartbeat ack du type :

```
HEARTBEAT_OK
OCPlatform treats a leading/trailing "HEARTBEAT_OK" as a heartbeat ack...
```

Le classifier Anthropic considere `HEARTBEAT_OK` comme un identifiant de harness tiers. Resultat : meme avec le billing block correct et l'OAuth token Claude Code, toutes les requetes echouent avec "out of extra usage". Decouvert par l'auteur via **recherche binaire sur un system prompt de 103 KB** — methodologie remarquable. Fix : remplacer par `HB_ACK` outbound et inverse-mapper inbound.

### Probleme 2 — `sessions_store` et `sessions_yield_interrupt`

OpenClaw 2026.4.x introduit deux nouveaux outils de gestion de session non couverts par les defaults du proxy. Ils echappent a la sanitisation et declenchent la detection. Ajoutes aux arrays `replacements` et `reverseMap`.

**Note d'ordre critique** : `sessions_yield_interrupt` doit etre place AVANT `sessions_yield` dans le tableau, sinon `sessions_yield` matche le prefixe et casse le pattern long. C'est documente explicitement dans la description de PR.

### Probleme 3 — Auto-detection NVM dans `setup.js`

Avant la PR, `setup.js` ne scannait que les chemins systeme et npm global pour detecter les outils `sessions_*` installes par OpenClaw. Les utilisateurs NVM (Node Version Manager) retombaient sur les defaults, manquant les nouveaux outils. Fix : ajout du scan `~/.nvm/versions/node/*/lib/...`.

## Discussion / Review

Une seule reaction du mainteneur **@zacdcook** (OWNER), 2 minutes apres le merge :

> Merged! Great contribution — the HEARTBEAT_OK discovery, new sessions_* tools, and NVM path scanning are all solid finds.
>
> One change made post-merge: removed the debug logging line (line 253 in proxy.js) that wrote raw request bodies to `/tmp/`. Not appropriate for production since it dumps tokens and conversation history to disk.
>
> Commit: fa8ef13

Aucune autre review formelle, aucun label, aucune CI verifiee. Acceptee a vue.

## Test plan declare par l'auteur

- [x] Confirmation que `HEARTBEAT_OK` est un trigger via tests API isoles (echec avec, succes sans)
- [x] Verification que le body complet de 144 KB OpenClaw passe via le proxy
- [x] Teste sur OpenClaw 2026.4.2 avec abonnement Claude Max

PR generee avec Claude Code (mention `Generated with Claude Code` dans le body).

## Fonctionnalites detaillees (du proxy global au moment de la PR — v1.3.0)

- **Layer 1 : Billing Header** : injection d'un identifiant Claude Code de 84 caracteres dans le system prompt.
- **Layer 2 : Token Swap** : remplace le token OpenClaw par l'OAuth token Claude Code lu depuis `~/.claude/.credentials.json` (ou macOS Keychain via v1.4.0).
- **Layer 3 : String sanitization** : 7 patterns (apres reduction v1.1.0 a partir de 18) — `OpenClaw`, `openclaw`, `sessions_spawn/list/history/send/yield`, `running inside`. La PR ajoute `HEARTBEAT_OK`, `sessions_store`, `sessions_yield_interrupt`.
- **Reverse mapping bidirectionnel** : SSE streaming en temps reel + JSON buffer. Indispensable pour que OpenClaw retrouve ses tool names et paths originels (`.openclaw/` au lieu de `.ocplatform/` qui casserait le filesystem).
- **Auto-detection credentials** : cross-platform (Linux, macOS dot/no-dot, Windows).
- **Health endpoint** `/health` : token status, request count, uptime, subscription type, pattern counts.
- **Configurable** via `config.json` ou args CLI, zero dependency.

Apres la PR (versions 2.x), s'ajoutent : tool name renaming PascalCase (29 outils), strip du system config template (28 KB → 0.5 KB), strip des tool descriptions, property renaming, CC tool stubs (Glob/Grep/Agent/NotebookEdit/TodoRead), Stainless SDK headers, fingerprint SHA256 dynamique, Docker support, BOM handling.

## Installation / Usage (du repo global)

```bash
# Prerequis : Node 18+, Claude Code CLI authentifie
npm install -g @anthropic-ai/claude-code
claude auth login
claude auth status   # doit montrer loggedIn: true, subscriptionType: max/pro

# Setup proxy
git clone https://github.com/zacdcook/openclaw-billing-proxy
cd openclaw-billing-proxy
node setup.js
node proxy.js

# Configuration OpenClaw : editer ~/.openclaw/openclaw.json
# "models.providers.anthropic.baseUrl": "http://127.0.0.1:18801"

# Redemarrer la gateway OpenClaw
node troubleshoot.js   # verifier
```

Deploiements production : Docker Compose (avec `~/.claude` mount readonly), systemd, PM2, Windows startup. Le token OAuth expire toutes les ~24 h — refresh manuel via Claude Code CLI ou cron `claude -p "ping" --max-turns 1`.

## Pertinence SEO pour ElevaSEO

**Faible directement, mais indirectement utile.**

Ce repo n'a aucun rapport SEO. Sa pertinence pour ElevaSEO se limite a deux axes :

1. **Cost engineering pour usage intensif de Claude** : si ElevaSEO utilise Claude Code de maniere intensive (audits SEO, generation de briefs, scripts d'analyse), comprendre comment Anthropic facture (subscription Max/Pro vs Extra Usage) et comment les outils tiers s'integrent dans ce billing est utile pour piloter le cout. ElevaSEO utilise visiblement Claude Code (cf. CLAUDE.md global et hooks RTK), donc la question du billing peut se poser le jour ou un outil maison ou un fork est utilise.

2. **Watch security/legal** : ce type de proxy est un workaround officiellement non supporte (le README contient un disclaimer explicite). L'utiliser pour des operations commerciales facturees a des clients pose des risques de TOS Anthropic. **Ne PAS deployer ce proxy en production ElevaSEO**, mais en avoir lu le code aide a comprendre les techniques d'evasion de classifier (utile pour audits anti-spam et comprehension des mecanismes de detection AI).

3. **Anecdotique mais educatif** : la methodologie de recherche binaire sur un system prompt de 103 KB pour identifier un trigger est elegante. Pattern transferable a du debug de classifier interne ou de prompt engineering avance.

Verdict : **a NE PAS utiliser**, mais **a connaitre** comme illustration des dynamiques entre Anthropic et l'ecosysteme third-party. Faible priorite documentaire.

## Limites / Risques / Mefiance

- **Workaround non officiel** : disclaimer explicite du repo. Anthropic peut changer la detection a tout moment (et l'a fait le 8 avril 2026, soit 2 jours apres la PR — cassant la v1.x).
- **Violation potentielle des TOS Anthropic** : l'objectif declare est de masquer une session OpenClaw pour qu'elle ressemble a une session Claude Code aux yeux de l'API. Risque legal et commercial. Pas adapte a un usage business serieux d'ElevaSEO.
- **Surface de risque securite** : le proxy lit `~/.claude/.credentials.json`, manipule l'OAuth token, et reecrit des bodies en streaming. Une bug peut leaker un token. Le mainteneur a d'ailleurs du faire un commit post-merge pour retirer un debug log qui ecrivait les raw bodies (avec tokens) dans `/tmp/` — c'est exactement le type de fuite qu'on craint.
- **Repo mainteneur unique** (@zacdcook), MIT mais sans gouvernance claire. La PR est mergee en 15 min sans review formelle. Qualite des contributions hautement variable.
- **Course aux armements infinie** : a partir de v2.0, le proxy implemente du tool name fingerprinting bypass, system template strip, property renaming. Chaque nouvelle version Anthropic peut casser tout. Maintenance lourde.
- **PR generee par Claude Code** : ironie de la situation — utiliser Claude pour ecrire le code qui contourne le billing Claude.
- **Surventes possibles** : le README parle de "Zero cost increase. Full OpenClaw functionality. No code changes to OpenClaw." — vrai a l'instant T, mais nie le risque de breakage permanent. Le CHANGELOG montre 10+ versions en 4 jours, ce qui contredit la promesse implicite de stabilite.
- **Aucun test automatise visible** : tout est valide manuellement par l'auteur. Pas de CI, pas de suite de tests dans le repo.

## Captures de code pertinentes

### Sanitisation du HEARTBEAT_OK (ajoutee par la PR — fragment conceptuel)

```js
// proxy.js — replacements outbound
[
  ["HEARTBEAT_OK", "HB_ACK"],
  ["sessions_yield_interrupt", "yield_task_interrupt"], // AVANT sessions_yield
  ["sessions_yield",           "yield_task"],
  ["sessions_store",           "store_task"],
  ["sessions_spawn",           "create_task"],
  // ...
]
// reverseMap inbound (inverse de chaque entree)
```

### Configuration OpenClaw pour pointer sur le proxy

```json
{
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "http://127.0.0.1:18801"
      }
    }
  }
}
```

### Detection Anthropic — modele en 4 layers (post v2.0, contexte du repo)

| Layer | Mecanisme | Reponse du proxy |
|-------|-----------|------------------|
| 1 | Billing header (84-char string match) | Injection identifiant CC |
| 2 | String triggers (30 keywords) | split/join replacements |
| 3 | Tool name fingerprinting (signature de 29 outils, seuil ~25) | rename PascalCase CC |
| 4 | System prompt template matching (seuil ~26 KB) | strip + paraphrase 0.5 KB |

## Liens externes mentionnes

- Repo parent : `https://github.com/zacdcook/openclaw-billing-proxy`
- Anthropic Claude Code : `https://claude.com/claude-code`
- Anthropic API et docs subscription billing (implicites, non linkees)
- Issues references dans le CHANGELOG : #11, #13, #15, #16, #17, #19, #21, #24, #26
- Commit cleanup post-merge : `fa8ef13`