Solução de problemas do zn-gate

As onze mensagens que mais aparecem para quem começa a usar o zn-gate: o que cada uma significa e o que fazer. Cada mensagem está copiada como o zn-gate a imprime.

Ver .md

As onze mensagens que mais aparecem para quem começa a usar o zn-gate: o que cada uma significa e o que fazer. Cada mensagem está copiada como o zn-gate a imprime. Uma parte entre sinais de menor e maior, como <agent>, é um espaço que o zn preenche para você. As mensagens são citadas como o zn-gate 1.13.1 as imprime.

Execute cada comando no seu próprio terminal, não por meio do seu agente de IA. As palavras que você não conhece estão no glossário.

1. O Node.js é antigo demais

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.

O que significa: o zn-gate é um programa em Node.js e o seu computador tem uma versão antiga demais. O número de versão na mensagem é o seu e será diferente.

O que fazer:

  1. Instale a versão LTS em nodejs.org, ou execute nvm install --lts se você usa o nvm.
  2. Abra um terminal novo e confira com node --version. Ele deve mostrar 18 ou superior (a versão LTS é recomendada; o plugin do Claude Code precisa do 20.12 ou superior).
  3. Execute o seu comando de novo.

2. npx: command not found

O que significa: o Node.js não está instalado, ou este terminal foi aberto antes de você instalá-lo. npx e npm vêm com o Node.js.

O que fazer: instale a versão LTS do Node.js, abra um terminal novo e execute o comando de novo. Confira com npx --version.

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

O que significa: o Windows PowerShell bloqueia por padrão o script que inicia npm e npx. Não há nada errado com o zn-gate.

O que fazer, qualquer uma destas opções:

  • Use as versões .cmd: npx.cmd -y zn-gate init, ou npm.cmd install -g zn-gate.
  • Execute os mesmos comandos no Prompt de Comando em vez do PowerShell.
  • Permita scripts locais para a sua conta: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Mais no README.

4. Ele precisa que você esteja no seu próprio terminal

Você pode ver uma destas:

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.

O que significa: alguns passos mudam as suas configurações ou mexem nos seus segredos, então o zn só os executa quando uma pessoa os digita. Ele se recusa quando o seu agente de IA os executa, ou quando um script os executa sem ninguém no teclado. Isso é de propósito. Nada foi alterado.

O que fazer: abra você mesmo uma janela de terminal (não a do agente) e execute o mesmo comando nela. Se você só vir "started from ...", o zn acha que há um agente acima do seu terminal na cadeia de processos. Abra uma janela de terminal nova pelo menu do sistema e tente de novo. No caso do init, os passos impressos abaixo da mensagem são os comandos a executar.

5. "Your secret vault is locked"

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

O que significa: o zn guarda os valores reais dos seus segredos em um cofre criptografado, e o cofre está fechado. Ele se bloqueia sozinho após 30 minutos sem uso, após 8 horas no máximo, ou quando você reinicia o computador. Se o zn não está instalado no seu computador, a mensagem mostra no lugar a forma npx -y zn-gate@<version> unlock.

O que fazer:

  1. Execute zn unlock no seu próprio terminal. Ele pode pedir uma frase secreta. Digite você mesmo: o zn nunca a lê a partir do seu agente.
  2. Execute zn vault status para ver que ele diz unlocked.
  3. Execute de novo o comando que falhou.

Mais em segredos. Se ele pedir um terminal para digitar a frase secreta e você não tiver nenhum (por exemplo, por SSH), essa página explica como executar o cofre em um terminal separado.

6. Seu agente foi bloqueado: ".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.

O que significa: seu agente tentou ler um arquivo com segredos em texto simples. O zn o impediu, então os segredos não chegaram ao agente. É o zn funcionando, não um erro.

O que fazer:

  1. Se o agente precisa de um valor desse arquivo, execute você mesmo zn env shadow .env no seu próprio terminal. Os valores vão para o cofre e o arquivo mantém marcadores como __ZN_API_KEY__ que o agente pode usar.
  2. Se você não esperava essa leitura, pergunte ao seu agente por que ele queria esse arquivo, e não procure um jeito de contornar o bloqueio.
  3. Para recuperar o seu .env antigo, execute o comando de restauração que o zn env shadow imprimiu, por exemplo zn env unshadow .env --backup <name>.

Mais em segredos e o que a verificação significa.

7. Seu agente ignora os hooks do zn em um computador gerenciado

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.

Outras versões dizem que a política "runs only the hooks in its managed settings (allowManagedHooksOnly)", que um arquivo de configurações seu "sets disableAllHooks", ou que uma lista de MCP gerenciada não inclui o servidor "secrets" do zn.

O que significa: uma configuração impede que os hooks do zn sejam executados. Em geral, a sua empresa ou escola controla as configurações do Claude Code; às vezes é uma linha no seu próprio arquivo de configurações. O Claude Code não mostra nenhum aviso, então o zn avisa você quando você instala os hooks ou executa npx -y zn-gate check ou npx -y zn-gate status. Até isso ser corrigido, o zn não está protegendo esse agente.

O que fazer:

  • Se a mensagem citar o seu próprio arquivo de configurações, essa linha desativa todos os hooks que você instalar, inclusive os do zn. Remova a linha disableAllHooks, a menos que você a tenha colocado de propósito, e execute npx -y zn-gate check.
  • Se ela citar uma política da organização, peça ao seu administrador que adicione o zn às configurações gerenciadas. Envie a mensagem a ele.
  • Execute npx -y zn-gate check para ver quais agentes estão protegidos.

Mais em compat.

8. O zn-gate connect não aceita a sua chave

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.

O que significa: o connect é opcional e ativa a verificação na nuvem. Ele só salva uma chave se for uma chave somente de análise e funcionar. A mensagem diz qual parte falhou. Nada foi salvo, então não há nada a desfazer.

O que fazer:

  1. Crie uma nova chave somente de análise na página de conexão indicada na mensagem. Não use uma chave com acesso total.
  2. Execute zn-gate connect e cole a chave no campo oculto. Nunca coloque a chave na linha de comando.
  3. Para desativar a verificação na nuvem a qualquer momento: zn-gate disconnect.

Mais em connect. Você não precisa do connect para usar o zn-gate: sem ele, tudo fica na sua máquina.

9. "will not send the saved key" (configurações de 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

O que significa: seu terminal tem uma configuração que desativa a verificação dos certificados de sites, muda o funcionamento das conexões seguras, ou poderia imprimir ou ler a sua chave. O zn-gate se recusa a enviar a sua chave salva por uma conexão assim. Mensagens parecidas citam no lugar NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, OPENSSL_CONF, NODE_DEBUG ou NODE_OPTIONS. Suas verificações locais continuam funcionando.

O que fazer: o zn-gate se recusa de propósito: com essa configuração, alguém entre você e o usezn.com poderia ler a sua chave. Nada está quebrado, e as verificações locais continuam funcionando sem a verificação na nuvem.

  • Se você mesmo definiu, por exemplo para um teste, remova, abra um terminal novo e tente de novo. No macOS ou no Linux, unset NODE_TLS_REJECT_UNAUTHORIZED (ou o nome que aparece na mensagem) remove no terminal atual. Se ela voltar, procure no arquivo de inicialização do seu shell (como ~/.zshrc ou ~/.bashrc).
  • Se a sua empresa precisa dela, por exemplo por causa de um proxy com certificado próprio, mantenha e fale com o seu administrador. Até lá, o zn-gate usa só as verificações locais neste computador.
  • Nunca desative a verificação de certificados só para fazer esta mensagem sumir.

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.

O que significa: o zn-gate mantém um registro do que decidiu. Cada linha está ligada à anterior, então uma linha editada, cortada ou escrita pela metade quebra a cadeia. O zn não conserta um registro: ele para de escrever nele para nunca esconder o dano. A sua proteção continua funcionando. Só o registro para. No Windows, a mensagem mostra um comando move em vez de mv.

O que fazer:

  1. Execute npx -y zn-gate evidence --verify. Ele diz onde está a quebra.
  2. Guarde o arquivo antigo se precisar dele para revisão. Mova-o para o lado com o comando que aparece na mensagem.
  3. O próximo evento começa um registro novo. Execute npx -y zn-gate evidence --verify de novo para ver que está tudo certo.

11. O plugin do Claude Code precisa de um Node.js mais novo

Você pode ver uma destas. A primeira vem de npx -y zn-gate check e a segunda 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.

O número de versão nas mensagens é o seu e será diferente.

O que significa: o plugin do zn-gate para o Claude Code precisa do Node.js 20.12 ou posterior. Com um Node.js mais antigo (por exemplo o Node.js 18, que o apt instala em muitos sistemas Debian e Ubuntu), o plugin não funciona de propósito, e o Claude Code pode mostrar os servidores MCP dele como falhos ao conectar. O próprio zn-gate e os hooks do zn continuam funcionando com o Node.js 18 ou posterior. Não há nada errado com os seus arquivos.

Como verificar:

  1. Execute node --version no seu próprio terminal. Se mostrar uma versão menor que 20.12 (como v18.19.1), essa é a causa. O Claude Code inicia o plugin com o primeiro node do seu PATH, então use o terminal de onde você inicia o Claude Code.
  2. Execute npx -y zn-gate check. Uma linha do Claude Code que diga NOT protected: the zn-gate plugin needs Node.js 20.12 or later confirma.

O que fazer, uma das duas:

  • Atualizar o Node.js (recomendado): instale a versão LTS do Node.js em nodejs.org, abra um terminal novo, confira que node --version mostra essa versão e depois inicie uma nova sessão do Claude Code. Se o computador tiver várias instalações do Node.js, garanta que a nova seja a primeira no seu PATH.
  • Ou usar os hooks do zn em vez do plugin: execute npm install -g zn-gate, depois zn hooks install claude-code, depois claude plugin disable zn-gate@usezn, tudo no seu próprio terminal. Em seguida, execute npx -y zn-gate check de novo.

Executar npx -y zn-gate init com um Node.js anterior ao 20.12 faz a segunda opção por você: ele pula o plugin e configura os hooks do zn para o Claude Code no lugar, e, se o plugin já estiver instalado, o desativa quando os hooks funcionam.

Também útil

  • Seu agente bloqueia cada pedido depois que você atualizou ou removeu o Node.js: veja If your agent blocks every prompt.
  • Sem saber o que está protegido: npx -y zn-gate check, explicado em check.
  • Ainda travado: pergunte em Discussions. Informe a sua versão do zn-gate (zn-gate --version), o seu sistema operacional e a mensagem, e não inclua nenhum segredo.