ZCode desktop app

Configure o zn-gate no aplicativo desktop ZCode da z.ai: instale seus hooks e veja o que o zn-gate cobre e o que não cobre ali.

Ver .md

Configure o zn-gate no aplicativo desktop ZCode da z.ai: instale seus hooks e veja o que o zn-gate cobre e o que não cobre ali.

Instale os hooks

No seu próprio terminal, não pelo seu agente:

npx -y zn-gate init

O init procura o aplicativo desktop ZCode (uma pasta ~/.zcode ou um programa zcode no seu PATH), mostra cada etapa e pergunta antes de executar uma. Para fazer só esta etapa com o zn-gate instalado (npm install -g zn-gate):

zn hooks install zcode

Isso grava os hooks do zn em ~/.zcode/cli/config.json para o seu usuário, ao lado de qualquer coisa que já estiver lá. Também:

  • ativa hooks.enabled, porque o ZCode não executa nenhum hook enquanto ele está desativado (vem desativado por padrão). Se estava desativado e você já tinha hooks próprios no arquivo, a instalação os lista: eles passam a rodar a partir da próxima sessão do ZCode. zn hooks uninstall zcode devolve a chave ao que era (desativada ou não definida), a menos que você a tenha alterado nesse meio-tempo;
  • registra o servidor MCP secrets do zn-gate no mesmo arquivo;
  • guarda um backup do arquivo antes de alterá-lo.

zn hooks uninstall zcode remove os hooks do zn e o servidor e deixa as suas próprias configurações intactas. Inicie uma nova sessão do ZCode depois de instalar ou desinstalar: uma sessão em andamento mantém os hooks com que foi iniciada.

Não existe instalação com --project. O ZCode não executa os hooks de um projeto (<project>/.zcode/config.json), apenas os do seu arquivo de usuário, então cada pessoa de uma equipe executa zn hooks install zcode uma vez na própria máquina.

Depois execute npx -y zn-gate check para ver se o hook funciona na sua máquina.

O plugin do ZCode

Uma versão do zn-gate como plugin do ZCode está pronta. Os passos para adicioná-la no ZCode (Settings, Plugins) serão publicados junto com o repositório do plugin. Até lá, a forma compatível de usar o zn-gate no ZCode é zn hooks install zcode, acima.

O que é o plugin, para você saber o que esperar quando ele for publicado:

  • Ele traz a sua própria cópia do zn-gate, fixada em uma versão e verificada, a cada chamada, contra o SHA-256 de cada arquivo da versão publicada. O ZCode não instala pacotes npm, então não há nada para baixar e nada que possa faltar. Não precisa de conta nem de chave de API e não envia nada pela rede.
  • O ZCode executa os hooks de um plugin independentemente do que hooks.enabled diga, então o plugin continua protegendo quando essa opção está desligada. Ele tem os mesmos hooks que zn hooks install zcode.
  • Seu hook é um script de shell POSIX. Testado no Linux com o aplicativo desktop do ZCode 3.16.3; o macOS não foi testado. Não funciona no Windows: use zn hooks install zcode ali. Ele precisa do Node.js 20.19 ou posterior, ou usa o que o próprio ZCode executa, e bloqueia a chamada quando não encontra nenhum ou quando qualquer coisa falha. A documentação do ZCode não diz o que acontece quando um hook falha; em nossos testes com o aplicativo desktop do ZCode 3.16.3 em Linux, um hook que falhou (um código de saída diferente de 2, uma falha ou um timeout) deixou a chamada seguir, e só o código de saída 2 ou uma resposta deny a bloqueou.
  • Se o Node.js travar enquanto o hook do plugin inicia, o hook ainda responde em até 28 segundos, abaixo do timeout de 30 segundos que o plugin define em seus hooks: ele bloqueia a chamada ou apenas emite um aviso em eventos que não podem bloquear.
  • Use o plugin ou zn hooks install zcode, não os dois: o ZCode não remove hooks duplicados, então cada chamada seria verificada duas vezes. zn hooks install zcode avisa quando o plugin está ativo, e o zn-gate check informa isso.
  • Você pode desativar o plugin em Settings, Plugins. Com o plugin desativado e hooks.enabled falso, nada do zn é executado no ZCode, e o zn-gate check informa que não está protegido.
  • A política do zn protege os arquivos do plugin: o agente não pode gravar, apagar nem mover nada em ~/.zcode/cli/plugins/ (zn-gate 1.14.0 e posteriores). Outros programas executados como você ainda podem editá-los.

O que o zn-gate protege no ZCode e o que não protege

Item No ZCode
Impede o agente de ler ou gravar .env e arquivos de credenciais (hooks) Sim, depois de instalados os hooks
Bloqueia comandos de shell que lidam com segredos e orienta o agente a executá-los por zn run (hooks) Sim
Verifica os argumentos das chamadas de ferramentas MCP antes de executarem (hooks) Sim: um valor secreto ou um marcador __ZN_ é bloqueado, dados pessoais pedem sua confirmação antes, e os caminhos de arquivo passam pelas verificações de leitura e gravação
Bloqueia um segredo colado no chat Sim: o prompt é interrompido antes de chegar ao modelo (o ZCode não permite que um hook altere um prompt, então ele é bloqueado, não limpo)
Impede o agente de editar o arquivo de configuração do ZCode e ~/.zn Melhor esforço: as ferramentas de arquivo e o shell do ZCode são verificados, outras formas de alterar o arquivo não
Remove segredos da saída do shell e do conteúdo de arquivos Não: os hooks do ZCode não conseguem reescrever o que uma ferramenta retorna. O zn adiciona um aviso para o modelo quando uma saída contém um segredo
Funciona com hooks em um projeto Não: o ZCode os ignora
Verificações do zn-gate disponíveis para o agente (MCP) Sim, o servidor secrets registrado na instalação

O que vale saber:

  • Versão testada. Os hooks são configurados no mesmo arquivo de usuário que o aplicativo documenta (~/.zcode/cli/config.json, Settings -> Hooks), e é ali que o zn os grava. O zn segue o comportamento de hooks descrito na documentação oficial do ZCode, e o hook do zn é coberto por testes automatizados. Testado de ponta a ponta no aplicativo desktop oficial do ZCode 3.16.3 em Linux x64 (outubro de 2026): com o zn instalado, Settings -> Hooks lista os hooks do zn, e em uma tarefa real o zn bloqueou a leitura de .env e ~/.aws/credentials enquanto comandos e leituras comuns foram executados; as mesmas verificações também passaram em modo headless com o agente que o aplicativo inclui. As mesmas verificações também passaram no Windows x64 (Windows Server 2022, mesma versão do aplicativo, outubro de 2026), para um administrador e para um usuário padrão, por meio do agente que o aplicativo inclui; a janela do aplicativo no Windows em si não foi operada. Não testado: macOS. O ZCode é um produto jovem e pode mudar esse comportamento em uma nova versão, então o zn-gate check mostra se o hook funciona na sua máquina.
  • Se o próprio hook do zn falhar, o ZCode pode executar a chamada. A documentação do ZCode não diz o que acontece quando um hook falha; em nossos testes com o aplicativo desktop do ZCode 3.16.3 em Linux, um hook que falhou (um código de saída diferente de 2, uma falha ou um timeout) deixou a chamada seguir, e só o código de saída 2 ou uma resposta deny a bloqueou. O zn cobre os casos que consegue: suas próprias verificações respondem deny e saem com código 2 se falharem ou demorarem demais, e o script launcher que o zn grava (~/.zn/hooks/zn-hook-zcode.sh) bloqueia a chamada com uma mensagem quando o Node.js com que o zn-gate foi instalado não existe mais. O launcher também tem seu próprio prazo de 28 segundos (2 segundos abaixo do timeout de 30 segundos que o zn define nas entradas dos seus hooks, no macOS, Linux e Windows): um hook que trava ao iniciar é interrompido e a chamada é bloqueada. Um hook que o ZCode não consegue iniciar de forma alguma (por exemplo, o arquivo do launcher foi apagado) não é coberto; o zn-gate check avisa isso.
  • Perguntas precisam de alguém para responder. Quando o zn perguntaria antes (dados pessoais em uma chamada MCP), o ZCode precisa de um prompt de permissão para mostrar a pergunta. Quando ninguém pode responder a um prompt de permissão, a pergunta do zn termina em bloqueio e a chamada não é executada. Não testado no aplicativo desktop.
  • Hooks desativados. Com "hooks.enabled": false em ~/.zcode/cli/config.json, o ZCode não executa nenhum dos hooks desse arquivo, inclusive os do zn (os hooks de um plugin do ZCode continuam rodando). Uma única entrada também pode ser desativada com "enabled": false, ou configurada para rodar em segundo plano com async, e um hook em segundo plano não consegue bloquear nada. O zn-gate check informa os três casos como não protegidos, e o zn hooks install zcode os repara.
  • Valores ainda podem chegar ao modelo. Um valor impresso por um comando, ou encontrado em um arquivo que o agente tem permissão de ler, não é removido. Mantenha os segredos no vault.
  • Subagentes. Não testado: se o ZCode executa os hooks dentro dos seus subagentes.
  • Qual arquivo o agente não consegue editar por suas ferramentas: ~/.zcode/cli/config.json. A política do zn também protege da mesma forma o <project>/.zcode/config.json de um projeto, e a pasta de plugins ~/.zcode/cli/plugins/ (zn-gate 1.14.0 e posteriores). As pastas ~/.zcode e ~/.zcode/cli não podem ser removidas, movidas nem criadas.

Há mais detalhes no modelo de ameaças e em compatibilidade com agentes.

Documentação do ZCode