Dépannage de zn-gate

Les onze messages que l'on rencontre le plus souvent en débutant avec zn-gate : ce que chacun signifie et quoi faire. Chaque message est copié tel que zn-gate l'affiche. Une partie entre chevrons, comme <agent>, est un blanc que zn remplit pour vous. Les messages sont cités tels que zn-gate 1.13.1 les affiche.

Lancez chaque commande dans votre propre terminal, pas par l'intermédiaire de votre agent IA. Les mots que vous ne connaissez pas sont dans le glossaire.

1. Node.js est trop ancien

zn-gate needs Node.js 18 or later, and this is Node.js v12.22.9.
Install the LTS version from https://nodejs.org/ (or run: nvm install --lts), then run the command again.

Ce que cela signifie : zn-gate est un programme Node.js et votre ordinateur en a une version trop ancienne. Le numéro de version dans le message est le vôtre et sera différent.

Que faire :

1. Installez la version LTS depuis nodejs.org, ou lancez nvm install --lts si vous utilisez nvm.
2. Ouvrez un nouveau terminal et vérifiez avec node --version. Il doit afficher 18 ou plus (la version LTS est recommandée ; le plugin Claude Code demande 20.12 ou plus).
3. Relancez votre commande.

2. npx: command not found

Ce que cela signifie : Node.js n'est pas installé, ou ce terminal a été ouvert avant son installation. npx et npm sont fournis avec Node.js.

Que faire : installez la version LTS de Node.js, ouvrez un nouveau terminal et relancez la commande. Vérifiez avec npx --version.

3. "running scripts is disabled on this system" (Windows)

Ce que cela signifie : Windows PowerShell bloque par défaut le script qui lance npm et npx. Il n'y a rien d'anormal dans zn-gate.

Que faire, l'une de ces options :

• Utilisez les versions .cmd : npx.cmd -y zn-gate init, ou npm.cmd install -g zn-gate.
• Lancez les mêmes commandes dans l'Invite de commandes plutôt que dans PowerShell.
• Autorisez les scripts locaux pour votre compte : Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Plus de détails dans le README.

4. Il faut que vous soyez devant votre propre terminal

Vous pouvez voir l'un de ces messages :

zn hooks: Not allowed: zn hooks install needs an interactive terminal.
zn env: Not allowed: zn env shadow needs an interactive terminal.
<command> must be run by you in your own terminal, not by an AI agent (detected CLAUDECODE).
An AI agent is running this, so zn only prints the steps: installing hooks is your decision. Nothing was changed.

Ce que cela signifie : certaines étapes modifient vos réglages ou touchent à vos secrets, donc zn ne les exécute que lorsqu'une personne les saisit. Il refuse quand votre agent IA les lance, ou quand un script les lance sans personne au clavier. C'est voulu. Rien n'a été modifié.

Que faire : ouvrez vous-même une fenêtre de terminal (pas celle de l'agent) et lancez-y la même commande. Si vous ne voyez que « started from ... », zn pense qu'un agent se trouve au-dessus de votre terminal dans la chaîne de processus. Ouvrez une nouvelle fenêtre de terminal depuis le menu de votre système et réessayez. Pour init, les étapes affichées sous le message sont les commandes à lancer.

5. "Your secret vault is locked"

Your secret vault is locked. Unlock it in this terminal with: zn unlock. Then run this command again.

Ce que cela signifie : zn garde les vraies valeurs de vos secrets dans un coffre chiffré, et le coffre est fermé. Il se verrouille tout seul après 30 minutes sans utilisation, après 8 heures au plus, ou au redémarrage de l'ordinateur. Si zn n'est pas installé sur votre ordinateur, le message donne à la place la forme npx -y zn-gate@<version> unlock.

Que faire :

1. Lancez zn unlock dans votre propre terminal. Il peut demander une phrase secrète. Saisissez-la vous-même : zn ne la lit jamais depuis votre agent.
2. Lancez zn vault status pour voir qu'il indique unlocked.
3. Relancez la commande qui a échoué.

Plus de détails dans secrets. S'il demande un terminal pour saisir la phrase secrète et que vous n'en avez pas (par exemple en SSH), cette page explique comment lancer le coffre dans un terminal séparé.

6. Votre agent a été bloqué : ".env holds plain-text secrets"

zn: .env holds plain-text secrets. Ask the user to run `zn env shadow .env` in their terminal: it moves the values to the local vault and leaves __ZN_<NAME>__ markers you can read and use.

Ce que cela signifie : votre agent a essayé de lire un fichier contenant des secrets en clair. zn l'a arrêté, donc les secrets ne sont pas parvenus à l'agent. C'est zn qui fait son travail, pas une erreur.

Que faire :

1. Si l'agent a besoin d'une valeur de ce fichier, lancez vous-même zn env shadow .env dans votre propre terminal. Les valeurs passent dans le coffre et le fichier garde des marqueurs comme __ZN_API_KEY__ que l'agent peut utiliser.
2. Si vous ne vous attendiez pas à cette lecture, demandez à votre agent pourquoi il voulait ce fichier, et ne cherchez pas à contourner le blocage.
3. Pour remettre votre ancien .env, lancez la commande de restauration affichée par zn env shadow, par exemple zn env unshadow .env --backup <name>.

Plus de détails dans secrets et ce que signifie la vérification.

7. Votre agent ignore les hooks de zn sur un ordinateur géré

Your organization's Claude Code policy (<file>) turns off all hooks (disableAllHooks), so zn's hooks do not run. Claude Code does not show this. Ask your administrator to add zn to the managed settings.

D'autres versions disent que la politique « runs only the hooks in its managed settings (allowManagedHooksOnly) », qu'un de vos fichiers de réglages « sets disableAllHooks », ou qu'une liste MCP gérée n'inclut pas le serveur « secrets » de zn.

Ce que cela signifie : un réglage empêche les hooks de zn de s'exécuter. En général, c'est votre entreprise ou votre école qui contrôle les réglages de Claude Code ; parfois c'est une ligne de votre propre fichier de réglages. Claude Code n'affiche lui-même aucun avertissement, donc zn vous prévient quand vous installez les hooks ou lancez npx -y zn-gate check ou npx -y zn-gate status. Tant que ce n'est pas corrigé, zn ne protège pas cet agent.

Que faire :

• Si le message nomme votre propre fichier de réglages, cette ligne désactive tous les hooks que vous installez, ceux de zn compris. Supprimez la ligne disableAllHooks, sauf si vous l'avez mise exprès, et lancez npx -y zn-gate check.
• S'il nomme une politique d'organisation, demandez à votre administrateur d'ajouter zn aux réglages gérés. Envoyez-lui le message.
• Lancez npx -y zn-gate check pour voir quels agents sont protégés.

Plus de détails dans compat.

8. zn-gate connect n'accepte pas votre clé

That does not look like a zn API key (they start with zn_). Nothing was saved.
usezn.com did not accept this key (it may be revoked or mistyped). Nothing was saved.
This key can do more than analyze text, and zn-gate only accepts a key limited to analyzing. Create an analysis-only key on the connect page and paste that one: <connect page address>
Nothing was saved.

Ce que cela signifie : connect est facultatif et active la vérification dans le cloud. Il n'enregistre une clé que si c'est une clé d'analyse uniquement et qu'elle fonctionne. Le message indique quelle partie a échoué. Rien n'a été enregistré, il n'y a donc rien à annuler.

Que faire :

1. Créez une nouvelle clé d'analyse uniquement sur la page de connexion indiquée dans le message. N'utilisez pas une clé à accès complet.
2. Lancez zn-gate connect et collez la clé dans le champ masqué. Ne mettez jamais la clé sur la ligne de commande.
3. Pour désactiver la vérification dans le cloud à tout moment : zn-gate disconnect.

Plus de détails dans connect. Vous n'avez pas besoin de connect pour utiliser zn-gate : sans lui, tout reste sur votre machine.

9. "will not send the saved key" (réglages TLS)

NODE_TLS_REJECT_UNAUTHORIZED=0 is set, so zn-gate will not send the saved key over a connection whose certificate is not checked

Ce que cela signifie : votre terminal a un réglage qui désactive la vérification des certificats des sites web, change le fonctionnement des connexions sécurisées, ou pourrait afficher ou lire votre clé. zn-gate refuse d'envoyer votre clé enregistrée par une telle connexion. Des messages semblables nomment à la place NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, OPENSSL_CONF, NODE_DEBUG ou NODE_OPTIONS. Vos vérifications locales continuent de fonctionner.

Que faire : zn-gate refuse volontairement : avec ce réglage, quelqu'un placé entre vous et usezn.com pourrait lire votre clé. Rien n'est cassé, et les vérifications locales fonctionnent sans la vérification dans le cloud.

• Si vous l'avez défini vous-même, par exemple pour un test, retirez-le, ouvrez un nouveau terminal et réessayez. Sous macOS ou Linux, unset NODE_TLS_REJECT_UNAUTHORIZED (ou le nom indiqué dans le message) le retire pour ce terminal. S'il revient, regardez dans le fichier de démarrage de votre shell (comme ~/.zshrc ou ~/.bashrc).
• Si votre entreprise en a besoin, par exemple pour un proxy avec son propre certificat, gardez-le et demandez à votre administrateur. D'ici là, zn-gate n'utilise que ses vérifications locales sur cet ordinateur.
• Ne désactivez jamais la vérification des certificats pour faire disparaître ce message.

10. "the evidence log ... is damaged"

zn-gate: the evidence log <path> is damaged (<reason>) Events are not being recorded. Run 'zn-gate evidence --verify' for details. To start a new log and keep the old file for review, move it aside (mv "<path>" "<folder>/evidence.damaged.jsonl"); the next event starts a new chain.

Ce que cela signifie : zn-gate tient un journal de ses décisions. Chaque ligne est liée à la précédente, donc une ligne modifiée, coupée ou écrite à moitié rompt la chaîne. zn ne répare pas un journal : il cesse d'y écrire pour ne jamais masquer le dommage. Votre protection continue de fonctionner. Seul l'enregistrement s'arrête. Sous Windows, le message affiche une commande move au lieu de mv.

Que faire :

1. Lancez npx -y zn-gate evidence --verify. Il indique où se trouve la rupture.
2. Gardez l'ancien fichier si vous voulez le consulter. Mettez-le de côté avec la commande donnée dans le message.
3. L'événement suivant démarre un nouveau journal. Relancez npx -y zn-gate evidence --verify pour vérifier que tout va bien.

11. Le plugin Claude Code demande un Node.js plus récent

Vous pouvez voir l'un de ces messages. Le premier vient de npx -y zn-gate check, le second de npx -y zn-gate init :

X  Claude Code   NOT protected: the zn-gate plugin needs Node.js 20.12 or later (you have 18.19.1).
Claude Code plugin skipped: it needs Node.js 20.12 or later (you have 18.19.1). zn's hooks are set up instead; update Node.js to use the plugin.

Le numéro de version dans les messages est le vôtre et sera différent.

Ce que cela signifie : le plugin zn-gate pour Claude Code demande Node.js 20.12 ou plus récent. Avec un Node.js plus ancien (par exemple Node.js 18, que apt installe sur de nombreux systèmes Debian et Ubuntu), le plugin ne fonctionne pas, volontairement, et Claude Code peut afficher ses serveurs MCP comme échoués à la connexion. zn-gate lui-même et les hooks de zn fonctionnent toujours avec Node.js 18 ou plus récent. Vos fichiers n'ont rien.

Comment vérifier :

1. Lancez node --version dans votre propre terminal. Si elle indique une version inférieure à 20.12 (comme v18.19.1), c'est la cause. Claude Code démarre le plugin avec le premier node de son PATH : utilisez donc le terminal depuis lequel vous lancez Claude Code.
2. Lancez npx -y zn-gate check. Une ligne pour Claude Code qui indique NOT protected: the zn-gate plugin needs Node.js 20.12 or later le confirme.

Que faire, l'une ou l'autre :

• Mettre à jour Node.js (recommandé) : installez la version LTS de Node.js depuis nodejs.org, ouvrez un nouveau terminal, vérifiez que node --version l'affiche, puis démarrez une nouvelle session Claude Code. Si votre ordinateur a plusieurs installations de Node.js, assurez-vous que la nouvelle est la première dans votre PATH.
• Ou utiliser les hooks de zn à la place du plugin : lancez npm install -g zn-gate, puis zn hooks install claude-code, puis claude plugin disable zn-gate@usezn, le tout dans votre propre terminal. Relancez ensuite npx -y zn-gate check.

Lancer npx -y zn-gate init avec un Node.js antérieur à 20.12 fait la seconde option pour vous : il ignore le plugin et configure à la place les hooks de zn pour Claude Code, et si le plugin est déjà installé, il le désactive une fois que les hooks fonctionnent.

À savoir aussi

• Votre agent bloque chaque requête après une mise à jour ou une désinstallation de Node.js : voyez If your agent blocks every prompt.
• Vous ne savez pas ce qui est protégé : npx -y zn-gate check, expliqué dans check.
• Toujours bloqué : posez la question dans Discussions. Indiquez votre version de zn-gate (zn-gate --version), votre système d'exploitation et le message, et n'incluez aucun secret.