Usar zn-gate en Windows

Instala zn-gate en Windows desde PowerShell o Git Bash, dónde guarda sus archivos (%USERPROFILE%\.zn), cómo se ejecutan los hooks de los agentes en Windows, las versiones mínimas y los límites conocidos.

Ver .md

zn-gate funciona de forma nativa en Windows. Esta página explica lo que cambia respecto a macOS y Linux: instalar desde PowerShell o Git Bash, dónde guarda zn sus archivos, cómo arrancan los hooks de los agentes, qué versiones necesitas y qué no está cubierto.

Qué necesitas

Elemento Versión Para qué
Node.js 18 o posterior (LTS); 20.12 o posterior para el plugin de Claude Code Ejecuta zn-gate y cada hook. Debe estar en tu PATH
Claude Code 2.1.295 o posterior; en Windows se recomienda 2.1.299 o posterior 2.1.295 es el mínimo para el plugin. Mira los límites conocidos para 2.1.299
Git for Windows Cualquier versión reciente Hace falta para añadir el plugin de Claude Code desde GitHub. Claude Code también ejecuta los comandos de los hooks con Git Bash

Instala Node.js desde nodejs.org, abre una terminal nueva y comprueba node --version. El instalador nativo de Claude Code no incluye Node.js: sin él, Claude Code avisa al empezar la sesión de que no encuentra node, bloquea los prompts y deja pasar las llamadas a herramientas sin comprobar.

Instalar en PowerShell

Ejecútalo tú, en una ventana normal de PowerShell y sin argumentos:

npx.cmd -y zn-gate init

Detecta Claude Code, Codex CLI, Cursor y OpenCode, te muestra la configuración de cada uno, ejecuta cada paso cuando lo confirmas y termina con una comprobación.

Si PowerShell dice «running scripts is disabled on this system»: la política de ejecución por defecto bloquea npm.ps1 y npx.ps1. Elige una opción:

  • Usa las versiones .cmd: npm.cmd, npx.cmd y zn.cmd (por ejemplo, npm.cmd install -g zn-gate).
  • Ejecuta los comandos desde el Símbolo del sistema.
  • Permite los scripts locales solo para tu cuenta: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Para Claude Code, lo recomendado es el plugin:

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

Para Codex CLI, Cursor u OpenCode, instala zn-gate y luego sus hooks:

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

Instalar en Git Bash

La política de ejecución de PowerShell no afecta a Git Bash, así que los comandos son los mismos que en macOS y Linux:

npx -y zn-gate init

Un agente cada vez: npm install -g zn-gate y después zn hooks install codex (o cursor, opencode).

El paquete de Python, para los agentes que construyes tú, se instala en un entorno virtual. En PowerShell:

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

Dónde guarda zn sus archivos

zn guarda su estado en una carpeta .zn dentro de tu perfil de usuario: %USERPROFILE%\.zn (por ejemplo, C:\Users\tu-usuario\.zn). Define la variable de entorno ZN_HOME para usar otra carpeta.

Qué Dónde
El almacén cifrado (secretos) %USERPROFILE%\.zn\vault\ (secrets.age)
Archivos de sesión mientras el almacén está desbloqueado %USERPROFILE%\.zn\run\
El registro de auditoría local del almacén %USERPROFILE%\.zn\audit.jsonl
El registro que lee zn-gate evidence %USERPROFILE%\.zn\evidence.jsonl
Ajustes opcionales de los hooks %USERPROFILE%\.zn\config.json

La clave del almacén se guarda en el Administrador de credenciales de Windows (Windows Credential Manager). Si no hay llavero, zn te pide una frase de contraseña (zn unlock --backend passphrase). zn no aplica permisos de archivo de Unix en Windows: valen los permisos de la carpeta de tu perfil de usuario.

Dónde guarda cada agente la configuración que escribe zn hooks install:

Agente En Windows
Claude Code %USERPROFILE%\.claude\settings.json (o la carpeta de CLAUDE_CONFIG_DIR)
Codex CLI %USERPROFILE%\.codex\hooks.json (o la carpeta de CODEX_HOME)
Cursor %USERPROFILE%\.cursor\hooks.json
OpenCode plugins\zn-gate.js dentro de %USERPROFILE%\.config\opencode (o de la carpeta bajo XDG_CONFIG_HOME)

Los agentes no pueden leer ni cambiar %USERPROFILE%\.zn: zn lo bloquea, también cuando un comando lo escribe como $env:USERPROFILE\.zn o %USERPROFILE%\.zn.

Los archivos de política de la organización que pueden desactivar los hooks están en C:\Program Files\ClaudeCode (Claude Code) y %ProgramData%\OpenAI\Codex (Codex). zn-gate check y zn hooks install los leen y te avisan cuando uno detiene a zn.

Cómo se ejecutan los hooks en Windows

Cada hook es un proceso corto de Node.js: el agente arranca node, que ejecuta el script del hook de zn-gate con el evento en su entrada estándar.

Agente Cómo arranca el hook
Claude Code, plugin node ejecuta el lanzador del plugin, que antes comprueba los archivos fijados de zn-gate
Claude Code, zn hooks install Claude Code ejecuta el comando con Git Bash (con PowerShell solo si Git Bash no está instalado). zn escribe la ruta de node y la del script del hook entre comillas simples y con barras normales, así que una ruta con espacios o caracteres especiales nunca se interpreta
Codex CLI El comando de Windows pasa por cmd.exe y arranca powershell.exe -NoProfile -NonInteractive con la misma llamada a node
Cursor En Windows, Cursor suele envolver el comando en PowerShell. zn escribe la misma forma con powershell.exe, que cmd.exe, PowerShell y Git Bash ejecutan igual
OpenCode El plugin arranca node con una lista de argumentos, sin shell

En nuestra CI, el plugin añade una mediana de 51 a 90 ms por llamada de hook en Windows, además de los 42 a 92 ms que tarda el hook sin el plugin.

El proceso en segundo plano del almacén habla con los hooks mediante una canalización con nombre de Windows (un socket Unix en macOS y Linux). Cada conexión tiene que demostrar que conoce la clave de sesión guardada en %USERPROFILE%\.zn\run\. El diálogo de confirmación del almacén, el Administrador de credenciales y zn secret set --clipboard arrancan el Windows PowerShell 5.1 del sistema, localizado a través del propio sistema y no de la variable SystemRoot, que un agente podría cambiar. Sin él, el diálogo no se muestra (se rechazan las aprobaciones) y el Administrador de credenciales se detiene con un error que sugiere zn unlock --backend passphrase.

Ejecutar comandos con zn run

  • Un programa .cmd o .bat (por ejemplo, una CLI instalada con npm) arranca solo a través del cmd.exe del sistema. zn rechaza una ruta de programa que contenga %, ! o ", porque cmd.exe las expandiría.
  • Aprobar un archivo .cmd o .bat aprueba ese archivo, no los programas que lanza por nombre: un shim de npm ejecuta el node que encuentre en tu PATH. Es mejor aprobar el propio programa, o usar la herramienta secrets_http_request para las API web.
  • Los programas se buscan como lo hace Windows, mediante PATHEXT: una instalación de npm deja un script llamado claude junto a claude.cmd, y zn elige el que Windows puede ejecutar.
  • Un comando de PowerShell que ya pasa por zn-gate run -- ... con un marcador de secreto lo deja pasar el hook. Antes de la 1.12.0 se rechazaba.

Límites conocidos

  • WSL: no probado. No hemos ejecutado zn-gate dentro del Subsistema de Windows para Linux, así que esta página no dice nada sobre él.
  • Claude Code es la vía que probamos en Windows, incluida su herramienta PowerShell.
  • Codex CLI: ejecutamos el comando del hook a mano desde PowerShell y desde cmd.exe. No forma parte de nuestras pruebas automáticas.
  • Cursor y OpenCode: no probados en Windows. En OpenCode, el envoltorio de zn run está escrito para bash: con PowerShell como shell de OpenCode, un comando con un marcador de secreto falla en lugar de ejecutarse (no se expone ningún valor).
  • zn-gate check: en Windows no arranca un hook instalado como zn hook <agent>. Comprueba en su lugar las reglas de zn para ese agente y lo dice en su salida.
  • Claude Code anterior a 2.1.299, sin Git for Windows: PreToolUse dejaba pasar las llamadas cuando el hook no podía ejecutarse. Actualiza Claude Code o instala Git for Windows.
  • Un hook que no puede ejecutarse (por ejemplo, falta node) deja las llamadas a herramientas sin comprobar en Claude Code y Codex, y bloquea los prompts en Claude Code. Qué admite cada agente.
  • Un comando de shell, PowerShell o Monitor de más de 100 KB se bloquea, porque zn no puede comprobarlo en el tiempo que el agente espera al hook.

Comprueba que funciona

Abre una terminal nueva y ejecuta:

npx.cmd -y zn-gate check

Debería mostrar OK para cada agente que hayas configurado. Qué significa la salida.

Para saber más