Utiliser zn-gate sous Windows

Installez zn-gate sous Windows depuis PowerShell ou Git Bash, où il range ses fichiers (%USERPROFILE%\.zn), comment les hooks des agents s'exécutent sous Windows, les versions minimales et les limites connues.

Voir le .md

zn-gate fonctionne nativement sous Windows. Cette page décrit ce qui change par rapport à macOS et Linux : l'installation depuis PowerShell ou Git Bash, l'emplacement des fichiers de zn, le démarrage des hooks des agents, les versions nécessaires et ce qui n'est pas couvert.

Ce qu'il vous faut

Élément Version Pourquoi
Node.js 18 ou plus récent (LTS) ; 20.12 ou plus récent pour le plugin Claude Code Exécute zn-gate et chaque hook. Il doit être dans votre PATH
Claude Code 2.1.295 ou plus récent ; 2.1.299 ou plus récent recommandé sous Windows 2.1.295 est le minimum pour le plugin. Voir les limites connues pour 2.1.299
Git for Windows Toute version récente Nécessaire pour ajouter le plugin Claude Code depuis GitHub. Claude Code exécute aussi les commandes des hooks avec Git Bash

Installez Node.js depuis nodejs.org, ouvrez un nouveau terminal et vérifiez node --version. L'installeur natif de Claude Code n'inclut pas Node.js : sans lui, Claude Code signale au début de la session que node est introuvable, les prompts sont bloqués et les appels d'outils s'exécutent sans contrôle.

Installer dans PowerShell

Lancez-le vous-même, dans une fenêtre PowerShell normale et sans arguments :

npx.cmd -y zn-gate init

Il détecte Claude Code, Codex CLI, Cursor et OpenCode, affiche la configuration de chacun, exécute chaque étape après votre confirmation et se termine par une vérification.

Si PowerShell affiche « running scripts is disabled on this system » : la stratégie d'exécution par défaut bloque npm.ps1 et npx.ps1. Choisissez une option :

  • Utilisez les versions .cmd : npm.cmd, npx.cmd et zn.cmd (par exemple npm.cmd install -g zn-gate).
  • Lancez les commandes depuis l'invite de commandes.
  • Autorisez les scripts locaux pour votre compte uniquement : Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Pour Claude Code, le plugin est la voie recommandée :

claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn

Pour Codex CLI, Cursor ou OpenCode, installez zn-gate puis ses hooks :

npm.cmd install -g zn-gate
zn.cmd hooks install codex       # ou : cursor, opencode

Installer dans Git Bash

La stratégie d'exécution de PowerShell ne concerne pas Git Bash : les commandes sont les mêmes que sous macOS et Linux :

npx -y zn-gate init

Un agent à la fois : npm install -g zn-gate, puis zn hooks install codex (ou cursor, opencode).

Le paquet Python, pour les agents que vous construisez vous-même, s'installe dans un environnement virtuel. Dans PowerShell :

python -m venv .venv
.venv\Scripts\pip install zn-gate

Où zn range ses fichiers

zn conserve son état dans un dossier .zn de votre profil utilisateur : %USERPROFILE%\.zn (par exemple C:\Users\vous\.zn). Définissez la variable d'environnement ZN_HOME pour utiliser un autre dossier.

Quoi Où
Le coffre chiffré (secrets) %USERPROFILE%\.zn\vault\ (secrets.age)
Fichiers de session tant que le coffre est déverrouillé %USERPROFILE%\.zn\run\
Le journal d'audit local du coffre %USERPROFILE%\.zn\audit.jsonl
Le journal que lit zn-gate evidence %USERPROFILE%\.zn\evidence.jsonl
Réglages facultatifs des hooks %USERPROFILE%\.zn\config.json

La clé du coffre est conservée dans le Gestionnaire d'identification Windows (Windows Credential Manager). S'il n'y a pas de trousseau, zn demande une phrase secrète à la place (zn unlock --backend passphrase). zn n'applique pas de modes de fichier Unix sous Windows : ce sont les permissions du dossier de votre profil utilisateur qui s'appliquent.

Où chaque agent range la configuration qu'écrit zn hooks install :

Agent Sous Windows
Claude Code %USERPROFILE%\.claude\settings.json (ou le dossier de CLAUDE_CONFIG_DIR)
Codex CLI %USERPROFILE%\.codex\hooks.json (ou le dossier de CODEX_HOME)
Cursor %USERPROFILE%\.cursor\hooks.json
OpenCode plugins\zn-gate.js dans %USERPROFILE%\.config\opencode (ou dans le dossier sous XDG_CONFIG_HOME)

Les agents ne peuvent ni lire ni modifier %USERPROFILE%\.zn : zn le bloque, y compris quand une commande l'écrit $env:USERPROFILE\.zn ou %USERPROFILE%\.zn.

Les fichiers de politique d'organisation qui peuvent désactiver les hooks se trouvent dans C:\Program Files\ClaudeCode (Claude Code) et %ProgramData%\OpenAI\Codex (Codex). zn-gate check et zn hooks install les lisent et vous préviennent quand l'un d'eux arrête zn.

Comment les hooks s'exécutent sous Windows

Chaque hook est un court processus Node.js : l'agent démarre node, qui exécute le script de hook de zn-gate avec l'événement sur son entrée standard.

Agent Comment le hook démarre
Claude Code, plugin node exécute le lanceur du plugin, qui vérifie d'abord les fichiers épinglés de zn-gate
Claude Code, zn hooks install Claude Code exécute la commande avec Git Bash (avec PowerShell seulement si Git Bash n'est pas installé). zn écrit le chemin de node et celui du script de hook entre apostrophes, avec des barres obliques, si bien qu'un chemin contenant des espaces ou des caractères spéciaux n'est jamais interprété
Codex CLI La commande Windows passe par cmd.exe et démarre powershell.exe -NoProfile -NonInteractive avec le même appel à node
Cursor Sous Windows, Cursor enveloppe généralement la commande dans PowerShell. zn écrit la même forme avec powershell.exe, que cmd.exe, PowerShell et Git Bash exécutent à l'identique
OpenCode Le plugin démarre node avec une liste d'arguments, sans shell

Dans notre CI, le plugin ajoute une médiane de 51 à 90 ms par appel de hook sous Windows, en plus des 42 à 92 ms que prend le hook sans le plugin.

Le processus d'arrière-plan du coffre parle aux hooks par un tube nommé Windows (un socket Unix sous macOS et Linux). Chaque connexion doit prouver qu'elle connaît la clé de session conservée dans %USERPROFILE%\.zn\run\. La boîte de dialogue de confirmation du coffre, le Gestionnaire d'identification et zn secret set --clipboard démarrent le Windows PowerShell 5.1 du système, trouvé par le système lui-même et non par la variable SystemRoot, qu'un agent pourrait modifier. Sans lui, la boîte de dialogue ne s'affiche pas (les approbations sont refusées) et le Gestionnaire d'identification s'arrête avec une erreur qui suggère zn unlock --backend passphrase.

Exécuter des commandes avec zn run

  • Un programme .cmd ou .bat (par exemple un outil en ligne de commande installé avec npm) démarre uniquement par le cmd.exe du système. zn refuse un chemin de programme qui contient %, ! ou ", car cmd.exe les développerait.
  • Approuver un fichier .cmd ou .bat approuve ce fichier, pas les programmes qu'il lance par leur nom : un shim npm exécute le node trouvé dans votre PATH. Préférez approuver le programme lui-même, ou utilisez l'outil secrets_http_request pour les API web.
  • Les programmes sont recherchés comme Windows le fait, avec PATHEXT : une installation npm place un script nommé claude à côté de claude.cmd, et zn choisit celui que Windows sait exécuter.
  • Une commande PowerShell qui passe déjà par zn-gate run -- ... avec un marqueur de secret est laissée telle quelle par le hook. Avant la 1.12.0, elle était refusée.

Limites connues

  • WSL : non testé. Nous n'avons pas exécuté zn-gate dans le sous-système Windows pour Linux ; cette page n'en dit donc rien.
  • Claude Code est la voie que nous testons sous Windows, y compris son outil PowerShell.
  • Codex CLI : nous avons exécuté la commande du hook à la main depuis PowerShell et depuis cmd.exe. Elle ne fait pas partie de nos tests automatisés.
  • Cursor et OpenCode : non testés sous Windows. Pour OpenCode, l'enveloppe de zn run est écrite pour bash : avec PowerShell comme shell d'OpenCode, une commande qui contient un marqueur de secret échoue au lieu de s'exécuter (aucune valeur n'est exposée).
  • zn-gate check : sous Windows, il ne démarre pas un hook installé sous la forme zn hook <agent>. Il vérifie à la place les règles de zn pour cet agent et le dit dans sa sortie.
  • Claude Code antérieur à 2.1.299, sans Git for Windows : PreToolUse laissait passer les appels quand le hook ne pouvait pas s'exécuter. Mettez Claude Code à jour ou installez Git for Windows.
  • Un hook qui ne peut pas s'exécuter (par exemple, node est absent) laisse les appels d'outils sans contrôle dans Claude Code et Codex, et bloque les prompts dans Claude Code. Ce que prend en charge chaque agent.
  • Une commande shell, PowerShell ou Monitor de plus de 100 Ko est bloquée, car zn ne peut pas la vérifier dans le temps que l'agent attend le hook.

Vérifiez que ça fonctionne

Ouvrez un nouveau terminal et lancez :

npx.cmd -y zn-gate check

Il doit afficher OK pour chaque agent que vous avez configuré. Ce que signifie la sortie.

Pour aller plus loin