# Dépannage

> Diagnostiquer Tokenade avec tokenade healthcheck : le sens de chaque vérification, les messages de pause vus par l'agent et leur correction.

Source: https://tokenade.net/fr/docs/troubleshooting · Updated: 2026-10-16

Quand les économies restent à zéro ou que votre agent cite un message de Tokenade, commencez par une seule commande :

```bash
tokenade healthcheck
```

Elle vérifie le binaire, les hooks de chaque agent et les magasins locaux, affiche une ligne par vérification, et sort avec le code `1` si l'une d'elles échoue. `tokenade health` et `tokenade doctor` sont des alias. Ajoutez `--json` pour obtenir un objet structuré (`version`, `failures`, `ok`, `checks[]`) où chaque vérification porte un `id` stable, pratique dans un script :

```bash
tokenade healthcheck --json | jq '.checks[] | select(.id == "hook_installed")'
```

Les lignes `OK` sont passées, `--` sont informatives, `!!` sont des échecs.

## Lignes du diagnostic et corrections

| id | Ce que signale un échec ou un avertissement | Correction |
|---|---|---|
| `binary` | Indique quel `tokenade` s'exécute, et prévient si plusieurs copies sont dans votre PATH. | Supprimez la copie inutile, ou placez la bonne en premier dans le PATH. |
| `gain_ledger` | `~/.tokenade/gain.jsonl` n'est pas inscriptible : aucune économie n'est enregistrée. | Corrigez le propriétaire ou les droits de `~/.tokenade/` (souvent créé par un lancement sous `sudo`). |
| `agent_detect` | Aucun agent IA détecté dans l'arborescence courante (information). | Lancez-la depuis un projet où vous utilisez votre agent. |
| `hook_installed` | Claude Code n'a pas les hooks de Tokenade : jamais installés, ou retirés par un autre outil ou une mise à jour de l'agent. | `tokenade ensure-hooks` si Tokenade était installé, sinon `tokenade install`. |
| `pretool_read` | Les hooks de Tokenade dans les réglages de Claude Code ne couvrent pas les lectures de fichiers : l'optimisation des lectures ne se déclenche jamais. | `tokenade ensure-hooks`. |
| `hook-integrity` | Des commandes de hook Tokenade ne correspondent plus à la forme installée. Une dérive peut signaler une altération. | `tokenade install`. |
| `binary_paths` | Des configurations d'agent pointent vers un binaire `tokenade` qui n'existe plus : ces hooks sont morts sans bruit. | `tokenade install` pour réécrire les chemins. |
| `hook_binaries_agree` | Vos hooks exécutent un autre `tokenade` que celui de votre PATH. | `tokenade install` depuis la copie à garder. |
| `codex-hook-trust` | Codex n'a pas approuvé les hooks de Tokenade, qui ne font donc rien. | Voir [Hooks Codex non approuvés](#hooks-codex-non-approuvés). |
| `claude-workspace-trust` | Claude Code n'a pas approuvé le dossier courant : en session interactive, il n'y exécute aucun hook. | Acceptez la demande de confiance quand Claude Code ouvre le dossier. Les lancements `claude -p` ne sont pas concernés. |
| `mcp_entry` | Une ancienne entrée `tokenade` traîne dans les `mcpServers` d'un agent ; elle lance la commande retirée `tokenade mcp`. | `tokenade install` la supprime. |
| `wrapped_mcps` | Des serveurs MCP tiers enveloppés par `mcp-wrap` pointent vers un ancien chemin de Tokenade. | `tokenade unwrap-mcps && tokenade install`. |
| `stale_mcp_procs` | Des processus MCP Tokenade tournent encore sur un ancien binaire. | Redémarrez votre agent. |
| `semantic_model` | Le modèle d'embeddings n'est pas encore téléchargé (information). Il l'est une fois, au premier `semantic` ou `--prompt`. | Rien à faire. |
| `posix-shell` | Windows uniquement : ni `sh` ni `bash` trouvé, la compaction des commandes shell est coupée. | Installez Git for Windows. |
| `web_transport` | `curl` introuvable ; la récupération web marche, en mode dégradé (information). | Installez `curl`. |
| `filter-syntax` | Des fichiers de compacteur sont illisibles et ne s'appliquent jamais. | Corrigez ou supprimez le fichier indiqué dans le détail. |
| `project-filters` | Des compacteurs de projet attendent votre approbation (information). | `tokenade trust-filters` (inspectez d'abord avec `--list`). |
| `ledger-integrity` | Des lignes du registre d'économies violent les règles de comptabilité. | `tokenade audit-gains` donne le détail. |
| `disk-footprint` | Place occupée par Tokenade, plus gros éléments en tête. | `tokenade evict-stale` purge les entrées de cache périmées. |

Les autres lignes informatives (activité des plugins par agent, leviers jamais déclenchés, nombre de contournements) décrivent l'usage de Tokenade et n'appellent pas de correction.

## Voir ce qu'ont fait les hooks

```bash
tokenade hooks status     # chaque hook Claude Code installé
tokenade hooks tail 50    # les 50 derniers événements de hook de ~/.tokenade/debug.log (20 par défaut)
```

Les deux acceptent `--json`. Le journal de débogage est un fichier JSON à une ligne par événement, avec `ts`, `component`, `event` et `details`. Il est actif par défaut après `tokenade install` (sauf installation avec `--no-debug-log`) et tourne à 16 Mio. Pour l'écrire ailleurs, posez `TOKENADE_DEBUG_LOG=<path>` là où l'agent démarre.

Les hooks ne bloquent jamais votre agent : si Tokenade échoue, l'appel d'outil passe tel quel. Pour mettre Tokenade hors de cause pendant un débogage, posez `TOKENADE_HOOK_DISABLED=1`, ou préfixez une commande par `tokenade raw`.

## Votre agent dit que Tokenade est en pause

Tokenade 2.0 ne se met jamais en pause : il n'y a ni licence ni quota à vérifier. Si votre agent relaie un avis qui commence par `tokenade —` et parle de compte, de licence, de facturation ou de tokenade.net injoignable, cette machine tourne encore sur une version 1.x. Mettez-la à jour :

```bash
npm i -g @tokenade/cli@latest
```

Voir [Installer Tokenade](https://tokenade.net/fr/docs/install), section « Passer de la 1.x à la 2.0 ».

## Hooks Codex non approuvés

Codex n'exécute pas un hook tant que vous ne l'avez pas approuvé. `tokenade install` approuve les hooks qu'il écrit en inscrivant leur approbation dans `~/.codex/config.toml`. Si la ligne `codex-hook-trust` échoue, réappliquez-la :

```bash
tokenade codex-trust
```

La commande affiche `trusted N Codex hook(s) in ~/.codex/config.toml`. Vous pouvez aussi les approuver depuis Codex avec `/hooks`. Tant que les hooks ne tournent pas, le [proxy LLM](https://tokenade.net/fr/docs/llm-proxy) de Tokenade couvre Codex pour le repli des sorties, le masquage des identifiants et la note de style ; dès que les hooks tournent, rien n'est fait deux fois. Voir [Codex](https://tokenade.net/fr/docs/codex).

## Claude Code ignore les hooks dans un dossier

Claude Code n'exécute aucun hook dans une session interactive ouverte dans un dossier dont la demande de confiance n'a pas été acceptée. Les hooks de Tokenade n'y échappent pas : rien n'y est compacté. La ligne `claude-workspace-trust` le signale ; acceptez la demande quand Claude Code ouvre le dossier.

## `tokenade install` refuse sous sudo

```text
✗ running under sudo: this would install into /root, not your own HOME —
  your AI agent would never see the hooks (and everything would LOOK fine).
  Re-run WITHOUT sudo: tokenade install
  (intentional root install: TOKENADE_ALLOW_ROOT=1 tokenade install)
```

Lancez-la avec votre propre utilisateur. Si vous utilisez vraiment votre agent en root, posez `TOKENADE_ALLOW_ROOT=1`.

## Les hooks ont disparu après une mise à jour de l'agent

Certaines mises à jour d'agent ou d'autres outils réécrivent le fichier de réglages. Tokenade vérifie et répare ses hooks tout seul de temps en temps. Pour réparer tout de suite :

```bash
tokenade ensure-hooks --force
```

## Signaler un bug

Si rien de tout cela n'aide, ouvrez un ticket sur [GitHub](https://github.com/pi-infected/tokenade/issues). Indiquez votre `tokenade --version`, la sortie de `tokenade healthcheck` et les lignes utiles de `tokenade hooks tail` ; relisez-les pour retirer toute donnée privée avant de les coller.

Pour comprendre le comportement des hooks de Claude Code, lisez [Les hooks de Claude Code](https://tokenade.net/fr/articles/claude-code-hooks).

## Voir aussi

- [Comment les hooks interceptent les appels d'outils](https://tokenade.net/fr/docs/hooks)
- [Commandes de maintenance](https://tokenade.net/fr/docs/maintenance)
- [Mettre à jour et désinstaller](https://tokenade.net/fr/docs/upgrade-uninstall)
- [Variables d'environnement](https://tokenade.net/fr/docs/environment-variables)
