ZCode desktop app

Configurer zn-gate dans l'application de bureau ZCode de z.ai : installer ses hooks, et ce que zn-gate couvre et ne couvre pas dans cet outil.

Voir le .md

Configurer zn-gate dans l'application de bureau ZCode de z.ai : installer ses hooks, et ce que zn-gate couvre et ne couvre pas dans cet outil.

Installer les hooks

Dans votre propre terminal, pas via votre agent :

npx -y zn-gate init

init recherche l'application de bureau ZCode (un dossier ~/.zcode, ou un programme zcode dans votre PATH), affiche chaque étape et demande votre accord avant d'en exécuter une. Pour ne faire que cette étape avec zn-gate installé (npm install -g zn-gate) :

zn hooks install zcode

Cela écrit les hooks de zn dans ~/.zcode/cli/config.json pour votre utilisateur, à côté de ce qui s'y trouve déjà. Cela permet aussi de :

  • activer hooks.enabled, car ZCode n'exécute aucun hook tant qu'il est désactivé (il l'est par défaut). S'il était désactivé et que le fichier contenait déjà vos propres hooks, l'installation les liste : ils s'exécuteront dès la prochaine session ZCode. zn hooks uninstall zcode remet l'interrupteur dans son état d'origine (désactivé ou non défini), sauf si vous l'avez modifié vous-même entre-temps ;
  • enregistrer le serveur MCP secrets de zn-gate dans le même fichier ;
  • conserver une sauvegarde du fichier avant de le modifier.

zn hooks uninstall zcode supprime les hooks de zn et le serveur, et laisse vos propres réglages intacts. Démarrez une nouvelle session ZCode après l'installation ou la désinstallation : une session en cours conserve les hooks avec lesquels elle a démarré.

Il n'existe pas d'installation --project. ZCode n'exécute pas les hooks d'un projet (<project>/.zcode/config.json), seulement ceux de votre fichier utilisateur ; chaque membre d'une équipe exécute donc zn hooks install zcode une fois sur sa propre machine.

Exécutez ensuite npx -y zn-gate check pour vérifier que le hook fonctionne sur votre machine.

Le plugin ZCode

Une version plugin ZCode de zn-gate est prête. Les étapes pour l'ajouter dans ZCode (Settings, Plugins) seront publiées avec son dépôt de plugin. D'ici là, la méthode prise en charge pour utiliser zn-gate dans ZCode est zn hooks install zcode, ci-dessus.

Ce qu'est le plugin, pour savoir à quoi vous attendre lors de sa publication :

  • Il embarque sa propre copie de zn-gate, figée sur une version et vérifiée à chaque appel par rapport au SHA-256 de chaque fichier de la version publiée. ZCode n'installe pas les paquets npm, il n'y a donc rien à télécharger et rien qui puisse manquer. Il ne demande ni compte ni clé API, et n'envoie rien sur le réseau.
  • ZCode exécute les hooks d'un plugin quelle que soit la valeur de hooks.enabled, de sorte que le plugin continue de protéger lorsque ce réglage est désactivé. Il a les mêmes hooks que zn hooks install zcode.
  • Son hook est un script shell POSIX. Testé sous Linux avec l'application de bureau ZCode 3.16.3 ; macOS n'est pas testé. Pas Windows : utilisez zn hooks install zcode dans ce cas. Il nécessite Node.js 20.19 ou plus récent, ou utilise celui sur lequel ZCode lui-même s'exécute, et bloque l'appel s'il n'en trouve aucun ou si quoi que ce soit échoue. La documentation de ZCode ne dit pas ce qui se passe lorsqu'un hook échoue ; dans nos tests avec l'application de bureau ZCode 3.16.3 sous Linux, un hook qui a échoué (un code de sortie autre que 2, un plantage ou un dépassement de délai) a laissé l'appel s'exécuter, et seuls le code de sortie 2 ou une réponse deny l'ont bloqué.
  • Si Node.js se bloque au démarrage du hook du plugin, le hook répond quand même en 28 secondes, sous le délai de 30 secondes que le plugin définit sur ses hooks : il bloque l'appel, ou n'émet qu'un avertissement pour les événements qui ne peuvent pas bloquer.
  • Utilisez le plugin ou zn hooks install zcode, pas les deux : ZCode ne supprime pas les hooks en double, chaque appel serait donc vérifié deux fois. zn hooks install zcode avertit lorsque le plugin est activé, et zn-gate check le signale.
  • Vous pouvez désactiver le plugin dans Settings, Plugins. Avec le plugin désactivé et hooks.enabled à false, rien de zn ne s'exécute dans ZCode, et zn-gate check le signale comme non protégé.
  • La politique de zn protège les fichiers du plugin : l'agent ne peut rien écrire, supprimer ni déplacer dans ~/.zcode/cli/plugins/ (zn-gate 1.14.0 et suivantes). Les autres programmes qui s'exécutent sous votre identité peuvent toujours les modifier.

Ce que zn-gate protège dans ZCode, et ce qu'il ne protège pas

Élément Dans ZCode
Empêche l'agent de lire ou d'écrire .env et les fichiers d'identifiants (hooks) Oui, une fois les hooks installés
Bloque les commandes shell qui manipulent des secrets et dit à l'agent de les exécuter via zn run (hooks) Oui
Vérifie les arguments des appels d'outils MCP avant leur exécution (hooks) Oui : une valeur secrète ou un marqueur __ZN_ est bloqué, les données personnelles déclenchent d'abord une question, et les chemins de fichiers subissent les contrôles de lecture et d'écriture
Bloque un secret collé dans le chat Oui : le prompt est arrêté avant d'atteindre le modèle (ZCode ne permet pas à un hook de modifier un prompt : il est donc bloqué, pas nettoyé)
Empêche l'agent de modifier le fichier de configuration de ZCode et ~/.zn Au mieux : les outils de fichiers et le shell de ZCode sont contrôlés, pas les autres moyens de modifier le fichier
Retire les secrets de la sortie du shell et du contenu des fichiers Non : les hooks de ZCode ne peuvent pas réécrire ce qu'un outil renvoie. zn ajoute un avertissement pour le modèle lorsqu'une sortie contient un secret
Fonctionne avec les hooks d'un projet Non : ZCode les ignore
Contrôles de zn-gate disponibles pour l'agent (MCP) Oui, le serveur secrets enregistré à l'installation

À savoir :

  • Version testée. Les hooks sont configurés dans le même fichier utilisateur que celui documenté par l'application (~/.zcode/cli/config.json, Settings -> Hooks), et c'est là que zn les écrit. zn suit le comportement des hooks décrit dans la documentation officielle de ZCode, et le hook de zn est couvert par des tests automatisés. Testé de bout en bout sur l'application de bureau officielle ZCode 3.16.3 sous Linux x64 (octobre 2026) : avec zn installé, Settings -> Hooks liste les hooks de zn, et dans une vraie tâche zn a bloqué la lecture de .env et de ~/.aws/credentials pendant que les commandes et lectures ordinaires s'exécutaient ; les mêmes vérifications ont aussi réussi en mode headless avec l'agent fourni par l'application. Les mêmes vérifications ont aussi réussi sous Windows x64 (Windows Server 2022, même version de l'application, octobre 2026), pour un administrateur et pour un utilisateur standard, via l'agent fourni par l'application ; la fenêtre de l'application Windows elle-même n'a pas été pilotée. Non testé : macOS. ZCode est un produit jeune et peut modifier ce comportement dans une nouvelle version ; zn-gate check indique donc si le hook fonctionne sur votre machine.
  • Si le hook zn lui-même échoue, ZCode peut exécuter l'appel. La documentation de ZCode ne dit pas ce qui se passe lorsqu'un hook échoue ; dans nos tests avec l'application de bureau ZCode 3.16.3 sous Linux, un hook qui a échoué (un code de sortie autre que 2, un plantage ou un dépassement de délai) a laissé l'appel s'exécuter, et seuls le code de sortie 2 ou une réponse deny l'ont bloqué. zn couvre les cas qu'il peut : ses propres contrôles répondent deny et se terminent avec le code 2 s'ils échouent ou durent trop longtemps, et le script de lancement que zn écrit (~/.zn/hooks/zn-hook-zcode.sh) bloque l'appel avec un message lorsque le Node.js avec lequel zn-gate a été installé a disparu. Le lanceur a aussi sa propre échéance de 28 secondes (2 secondes sous le délai de 30 secondes que zn définit sur ses entrées de hook, sur macOS, Linux et Windows) : un hook qui se bloque au démarrage est arrêté et l'appel est bloqué. Un hook que ZCode ne peut pas démarrer du tout (par exemple si le fichier du lanceur a été supprimé) n'est pas couvert ; zn-gate check le signale.
  • Les questions nécessitent quelqu'un pour répondre. Lorsque zn vous interrogerait d'abord (données personnelles dans un appel MCP), ZCode a besoin d'une demande d'autorisation pour afficher la question. Lorsque personne ne peut répondre à une demande d'autorisation, la question de zn se termine par un blocage et l'appel ne s'exécute pas. Non testé dans l'application de bureau.
  • Hooks désactivés. Avec "hooks.enabled": false dans ~/.zcode/cli/config.json, ZCode n'exécute aucun des hooks de ce fichier, y compris ceux de zn (les hooks d'un plugin ZCode continuent de s'exécuter). Une entrée isolée peut aussi être désactivée avec "enabled": false, ou exécutée en arrière-plan avec async, et un hook en arrière-plan ne peut rien bloquer. zn-gate check signale ces trois cas comme non protégés, et zn hooks install zcode les répare.
  • Des valeurs peuvent encore atteindre le modèle. Une valeur affichée par une commande, ou trouvée dans un fichier que l'agent a le droit de lire, n'est pas retirée. Gardez les secrets dans le vault.
  • Sous-agents. Non testé : si ZCode exécute les hooks dans ses sous-agents.
  • Quel fichier l'agent ne peut pas modifier avec ses outils : ~/.zcode/cli/config.json. La politique de zn protège aussi de la même manière le <project>/.zcode/config.json d'un projet, ainsi que le dossier des plugins ~/.zcode/cli/plugins/ (zn-gate 1.14.0 et suivantes). Les dossiers ~/.zcode et ~/.zcode/cli ne peuvent être ni supprimés, ni déplacés, ni créés.

Plus de détails dans le modèle de menaces et dans la compatibilité des agents.

Documentation de ZCode