Usar o zn-gate no Windows

O zn-gate roda nativamente no Windows. Esta página mostra o que muda em relação ao macOS e ao Linux: instalar pelo PowerShell ou pelo Git Bash, onde o zn guarda seus arquivos, como os hooks dos agentes iniciam, quais versões você precisa e o que não está coberto.

O que você precisa

Instale o Node.js em nodejs.org, abra um terminal novo e confira node --version. O instalador nativo do Claude Code não inclui o Node.js: sem ele, o Claude Code avisa no início da sessão que não encontrou o node, os prompts são bloqueados e as chamadas de ferramentas rodam sem verificação.

Instalar no PowerShell

Execute você mesmo, em uma janela normal do PowerShell e sem argumentos:

npx.cmd -y zn-gate init

Ele encontra o Claude Code, o Codex CLI, o Cursor e o OpenCode, mostra a configuração de cada um, executa cada passo depois que você confirma e termina com uma verificação.

Se o PowerShell disser "running scripts is disabled on this system": a política de execução padrão bloqueia npm.ps1 e npx.ps1. Escolha uma opção:

• Use as versões .cmd: npm.cmd, npx.cmd e zn.cmd (por exemplo, npm.cmd install -g zn-gate).
• Execute os comandos no Prompt de Comando.
• Permita scripts locais só para a sua conta: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Para o Claude Code, o recomendado é o plugin:

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

Para o Codex CLI, o Cursor ou o OpenCode, instale o zn-gate e depois os hooks dele:

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

Instalar no Git Bash

A política de execução do PowerShell não afeta o Git Bash, então os comandos são os mesmos do macOS e do Linux:

npx -y zn-gate init

Um agente de cada vez: npm install -g zn-gate e depois zn hooks install codex (ou cursor, opencode).

O pacote Python, para agentes que você mesmo constrói, é instalado em um ambiente virtual. No PowerShell:

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

Onde o zn guarda seus arquivos

O zn guarda seu estado em uma pasta .zn no seu perfil de usuário: %USERPROFILE%\.zn (por exemplo, C:\Users\voce\.zn). Defina a variável de ambiente ZN_HOME para usar outra pasta.

A chave do cofre fica no Gerenciador de Credenciais do Windows (Windows Credential Manager). Quando não há chaveiro, o zn pede uma senha (passphrase) no lugar (zn unlock --backend passphrase). O zn não define modos de arquivo do Unix no Windows: valem as permissões da pasta do seu perfil de usuário.

Onde cada agente guarda a configuração que o zn hooks install escreve:

Os agentes não podem ler nem alterar %USERPROFILE%\.zn: o zn bloqueia, inclusive quando um comando escreve $env:USERPROFILE\.zn ou %USERPROFILE%\.zn.

Os arquivos de política da organização que podem desligar os hooks ficam em C:\Program Files\ClaudeCode (Claude Code) e %ProgramData%\OpenAI\Codex (Codex). O zn-gate check e o zn hooks install leem esses arquivos e avisam quando algum deles impede o zn de funcionar.

Como os hooks rodam no Windows

Cada hook é um processo curto do Node.js: o agente inicia o node, que executa o script de hook do zn-gate com o evento na entrada padrão.

Na nossa CI, o plugin acrescenta uma mediana de 51 a 90 ms por chamada de hook no Windows, além dos 42 a 92 ms que o hook leva sem o plugin.

O processo em segundo plano do cofre conversa com os hooks por um pipe nomeado do Windows (um socket Unix no macOS e no Linux). Cada conexão precisa provar que conhece a chave de sessão guardada em %USERPROFILE%\.zn\run\. A caixa de confirmação do cofre, o Gerenciador de Credenciais e o zn secret set --clipboard iniciam o Windows PowerShell 5.1 do sistema, localizado pelo próprio sistema e não pela variável SystemRoot, que um agente poderia alterar. Sem ele, a caixa não aparece (as aprovações são recusadas) e o Gerenciador de Credenciais para com um erro que sugere zn unlock --backend passphrase.

Executar comandos com zn run

• Um programa .cmd ou .bat (por exemplo, uma CLI instalada com npm) inicia somente pelo cmd.exe do sistema. O zn recusa um caminho de programa que contenha %, ! ou ", porque o cmd.exe os expandiria.
• Aprovar um arquivo .cmd ou .bat aprova esse arquivo, não os programas que ele inicia pelo nome: um shim do npm executa o node que estiver no seu PATH. Prefira aprovar o próprio programa ou usar a ferramenta secrets_http_request para APIs web.
• Os programas são localizados como o Windows faz, pelo PATHEXT: uma instalação do npm coloca um script chamado claude ao lado do claude.cmd, e o zn escolhe o que o Windows consegue executar.
• Um comando do PowerShell que já passa por zn-gate run -- ... com um marcador de segredo é deixado como está pelo hook. Antes da 1.12.0, ele era recusado.

Limites conhecidos

• WSL: não testado. Não executamos o zn-gate dentro do Subsistema do Windows para Linux, então esta página não diz nada sobre ele.
• Claude Code é o caminho que testamos no Windows, incluindo a ferramenta PowerShell dele.
• Codex CLI: executamos o comando do hook manualmente no PowerShell e no cmd.exe. Ele não faz parte dos nossos testes automáticos.
• Cursor e OpenCode: não testados no Windows. No OpenCode, o envoltório do zn run é escrito para bash: com o PowerShell como shell do OpenCode, um comando com marcador de segredo falha em vez de rodar (nenhum valor é exposto).
• zn-gate check: no Windows, ele não inicia um hook instalado como zn hook <agent>. Em vez disso, verifica as regras do zn para esse agente e diz isso na saída.
• Claude Code anterior à 2.1.299, sem o Git for Windows: o PreToolUse deixava as chamadas passarem quando o hook não conseguia rodar. Atualize o Claude Code ou instale o Git for Windows.
• Um hook que não consegue rodar (por exemplo, falta o node) deixa as chamadas de ferramentas sem verificação no Claude Code e no Codex, e bloqueia os prompts no Claude Code. O que cada agente suporta.
• Um comando de shell, PowerShell ou Monitor com mais de 100 KB é bloqueado, porque o zn não consegue verificá-lo no tempo que o agente espera pelo hook.

Confira se está funcionando

Abra um terminal novo e execute:

npx.cmd -y zn-gate check

Ele deve mostrar OK para cada agente que você configurou. O que a saída significa.

Leitura adicional

• Instalar o zn-gate: todos os agentes e a configuração com um só comando.
• Guarde os valores do seu .env no cofre criptografado