Documentation / Dépannage
Dépannage
Mis à jour le
Quand les économies restent à zéro ou que votre agent cite un message de Tokenade, commencez par une seule commande :
Elle vérifie le binaire, la licence, 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 :
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. |
license | Pas de licence sur la machine, licence qui ne se vérifie plus, quota épuisé, ou tokenade.net injoignable depuis plus de 3 jours. La ligne affiche le même message que celui reçu par l'agent (voir plus bas). | En général tokenade login. |
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. |
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
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.
Tokenade est en pause
Quand Tokenade ne peut pas compacter, il ne fait pas échouer les appels d'outils de votre agent. Il lui remet un avis, l'agent continue avec ses outils habituels, et la compaction s'arrête sur la machine. Il existe quatre avis, toujours rédigés en anglais.
Machine non connectée.
Correction : lancez tokenade login dans un terminal. Voir Se connecter et activer une machine.
Licence invalide.
Correction : tokenade login. Cela arrive par exemple quand un fichier de licence a été copié depuis une autre machine.
Quota mensuel épuisé. L'avis commence par :
Il renvoie ensuite vers la page de mise à niveau (plan Free) ou vers le déblocage du paiement à l'usage dans votre tableau de bord (plan Pro). La compaction reprend le 1er du mois, ou dès que votre plan le permet. Voir les tarifs.
tokenade.net injoignable depuis plus de 3 jours.
La pause commence 72 heures après le premier envoi d'usage en échec. Correction : autorisez le HTTPS vers https://tokenade.net dans votre pare-feu, proxy ou filtre DNS, puis lancez tokenade healthcheck pour retester tout de suite. Voir Ce que Tokenade envoie.
Machine retirée du tableau de bord (MACHINE_REVOKED)
Si vous retirez une machine depuis votre tableau de bord sur tokenade.net, son envoi d'usage suivant reçoit une réponse HTTP 403 avec MACHINE_REVOKED. Tokenade efface alors la licence et le cache de quota locaux, et la machine retombe sur l'avis « isn't connected » ci-dessus. Pour la réutiliser, lancez tokenade login.
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 :
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 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.
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
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 :
Envoyer un rapport
Si rien de tout cela n'aide, tokenade report envoie les journaux de Tokenade et les transcriptions de vos agents, masqués, pour analyse, après saisie d'une phrase de consentement. Lancez d'abord tokenade report --dry-run pour construire l'archive en local (~/.tokenade/last-report.zip) et vérifier son contenu sans rien envoyer. Utilisez --message "…" pour décrire le problème. Détails dans Ce que Tokenade envoie et conserve.
Pour comprendre le comportement des hooks de Claude Code, lisez Les hooks de Claude Code.