ZCode desktop app

Configura zn-gate en la aplicación de escritorio ZCode de z.ai: instala sus hooks y consulta qué cubre zn-gate ahí y qué no.

Ver .md

Configura zn-gate en la aplicación de escritorio ZCode de z.ai: instala sus hooks y consulta qué cubre zn-gate ahí y qué no.

Instalar los hooks

En tu propia terminal, no a través de tu agente:

npx -y zn-gate init

init busca la aplicación de escritorio ZCode (una carpeta ~/.zcode, o un programa zcode en tu PATH), muestra cada paso y pregunta antes de ejecutar uno. Para hacer solo este paso con zn-gate instalado (npm install -g zn-gate):

zn hooks install zcode

Esto escribe los hooks de zn en ~/.zcode/cli/config.json para tu usuario, junto a lo que ya hubiera allí. Además:

  • activa hooks.enabled, porque ZCode no ejecuta ningún hook mientras está desactivado (por defecto lo está). Si estaba desactivado y ya tenías hooks propios en el archivo, la instalación los enumera: se ejecutarán desde la próxima sesión de ZCode. zn hooks uninstall zcode devuelve el interruptor a como estaba (desactivado o sin definir), salvo que lo hayas cambiado tú mismo entretanto;
  • registra el servidor MCP secrets de zn-gate en el mismo archivo;
  • guarda una copia de seguridad del archivo antes de modificarlo.

zn hooks uninstall zcode elimina los hooks de zn y el servidor, y deja intacta tu propia configuración. Inicia una sesión nueva de ZCode después de instalar o desinstalar: una sesión en curso conserva los hooks con los que arrancó.

No hay instalación con --project. ZCode no ejecuta los hooks de un proyecto (<project>/.zcode/config.json), solo los de tu archivo de usuario, así que cada persona de un equipo ejecuta zn hooks install zcode una vez en su propia máquina.

Después ejecuta npx -y zn-gate check para comprobar que el hook funciona en tu máquina.

El plugin de ZCode

Ya hay una versión de zn-gate como plugin de ZCode. Los pasos para añadirlo en ZCode (Settings, Plugins) se publicarán junto con su repositorio de plugin. Hasta entonces, la forma admitida de usar zn-gate en ZCode es zn hooks install zcode, arriba.

Qué es el plugin, para que sepas qué esperar cuando se publique:

  • Lleva su propia copia de zn-gate, fijada a una versión y comprobada en cada llamada contra el SHA-256 de cada archivo de la versión publicada. ZCode no instala paquetes de npm, así que no hay nada que descargar ni nada que pueda faltar. No necesita cuenta ni clave de API, y no envía nada por la red.
  • ZCode ejecuta los hooks de un plugin diga lo que diga hooks.enabled, así que el plugin sigue protegiendo aunque ese interruptor esté desactivado. Tiene los mismos hooks que zn hooks install zcode.
  • Su hook es un script de shell POSIX. Probado en Linux con la aplicación de escritorio de ZCode 3.16.3; macOS no se ha probado. Windows no: usa allí zn hooks install zcode. Necesita Node.js 20.19 o posterior, o usa el que ejecuta el propio ZCode, y bloquea la llamada cuando no encuentra ninguno o cuando algo falla. La documentación de ZCode no dice qué ocurre cuando un hook falla; en nuestras pruebas con la aplicación de escritorio de ZCode 3.16.3 en Linux, un hook que falló (un código de salida distinto de 2, un fallo o un tiempo agotado) dejó que la llamada se ejecutara, y solo el código de salida 2 o una respuesta deny la bloqueó.
  • Si Node.js se bloquea mientras arranca el hook del plugin, el hook sigue respondiendo en menos de 28 segundos, por debajo del timeout de 30 segundos que el plugin establece en sus hooks: bloquea la llamada, o solo avisa en los eventos que no pueden bloquear.
  • Usa el plugin o zn hooks install zcode, no ambos: ZCode no elimina los hooks duplicados, así que cada llamada se comprobaría dos veces. zn hooks install zcode avisa cuando el plugin está activado, y zn-gate check lo indica.
  • Puedes desactivar el plugin en Settings, Plugins. Con el plugin desactivado y hooks.enabled en false, no se ejecuta nada de zn en ZCode, y zn-gate check lo indica como no protegido.
  • La política de zn protege los archivos del plugin: el agente no puede escribir, borrar ni mover nada en ~/.zcode/cli/plugins/ (zn-gate 1.14.0 y posteriores). Otros programas que se ejecutan como tú sí pueden editarlos.

Qué protege zn-gate en ZCode y qué no

Elemento En ZCode
Impide que el agente lea o escriba .env y archivos de credenciales (hooks) Sí, una vez instalados los hooks
Bloquea los comandos de shell que manejan secretos y le indica al agente que los ejecute mediante zn run (hooks) Sí
Comprueba los argumentos de las llamadas a herramientas MCP antes de ejecutarlas (hooks) Sí: un valor secreto o un marcador __ZN_ se bloquea, los datos personales te lo preguntan primero y las rutas de archivo pasan por las comprobaciones de lectura y escritura
Bloquea un secreto pegado en el chat Sí: el prompt se detiene antes de llegar al modelo (ZCode no permite que un hook cambie un prompt, así que se bloquea, no se limpia)
Impide que el agente edite el archivo de configuración de ZCode y ~/.zn Mejor esfuerzo: se comprueban las herramientas de archivos y el shell de ZCode, otras formas de cambiar el archivo no
Elimina secretos de la salida del shell y del contenido de los archivos No: los hooks de ZCode no pueden reescribir lo que devuelve una herramienta. zn añade un aviso para el modelo cuando una salida contiene un secreto
Funciona con hooks en un proyecto No: ZCode los ignora
Comprobaciones de zn-gate disponibles para el agente (MCP) Sí, el servidor secrets registrado en la instalación

Conviene saber:

  • Versión probada. Los hooks se configuran en el mismo archivo de usuario que documenta la aplicación (~/.zcode/cli/config.json, Settings -> Hooks), y ahí es donde los escribe zn. zn sigue el comportamiento de los hooks descrito en la documentación oficial de ZCode, y el hook de zn está cubierto por pruebas automatizadas. Probado de extremo a extremo en la aplicación de escritorio oficial de ZCode 3.16.3 en Linux x64 (octubre de 2026): con zn instalado, Settings -> Hooks muestra los hooks de zn, y en una tarea real zn bloqueó la lectura de .env y ~/.aws/credentials mientras los comandos y lecturas habituales se ejecutaron; las mismas comprobaciones también pasaron sin interfaz con el agente que incluye la aplicación. Las mismas comprobaciones también pasaron en Windows x64 (Windows Server 2022, misma versión de la aplicación, octubre de 2026), con un administrador y con un usuario estándar, a través del agente que incluye la aplicación; no se manejó la ventana de la aplicación en Windows. No probado: macOS. ZCode es un producto joven y puede cambiar este comportamiento en una versión nueva, por eso zn-gate check muestra si el hook funciona en tu máquina.
  • Si el propio hook de zn falla, ZCode puede ejecutar la llamada. La documentación de ZCode no dice qué ocurre cuando un hook falla; en nuestras pruebas con la aplicación de escritorio de ZCode 3.16.3 en Linux, un hook que falló (un código de salida distinto de 2, un fallo o un tiempo agotado) dejó que la llamada se ejecutara, y solo el código de salida 2 o una respuesta deny la bloqueó. zn cubre los casos que puede: sus propias comprobaciones responden deny y terminan con código 2 si fallan o tardan demasiado, y el script launcher que escribe zn (~/.zn/hooks/zn-hook-zcode.sh) bloquea la llamada con un mensaje cuando ya no existe el Node.js con el que se instaló zn-gate. El launcher tiene además su propio plazo de 28 segundos (2 segundos por debajo del tiempo de espera de 30 segundos que zn establece en sus entradas de hook, en macOS, Linux y Windows): un hook que se cuelga al arrancar se detiene y la llamada se bloquea. Un hook que ZCode no puede arrancar en absoluto (por ejemplo, si se borró el archivo del launcher) no está cubierto; zn-gate check lo señala.
  • Las preguntas necesitan a alguien que responda. Cuando zn te preguntaría primero (datos personales en una llamada MCP), ZCode necesita un aviso de permiso para mostrar la pregunta. Cuando nadie puede responder a un aviso de permiso, la pregunta de zn acaba en un bloqueo y la llamada no se ejecuta. No se probó en la aplicación de escritorio.
  • Hooks desactivados. Con "hooks.enabled": false en ~/.zcode/cli/config.json, ZCode no ejecuta ninguno de los hooks de ese archivo, incluidos los de zn (los hooks de un plugin de ZCode siguen ejecutándose). Una sola entrada también puede desactivarse con "enabled": false, o hacerse ejecutar en segundo plano con async, y un hook en segundo plano no puede bloquear nada. zn-gate check informa de los tres casos como no protegidos, y zn hooks install zcode los repara.
  • Los valores aún pueden llegar al modelo. Un valor que imprime un comando, o que se encuentra en un archivo que el agente puede leer, no se elimina. Guarda los secretos en el vault.
  • Subagentes. No se probó: si ZCode ejecuta los hooks dentro de sus subagentes.
  • Qué archivo no puede editar el agente con sus herramientas: ~/.zcode/cli/config.json. La política de zn protege también del mismo modo el <project>/.zcode/config.json de un proyecto, y la carpeta de plugins ~/.zcode/cli/plugins/ (zn-gate 1.14.0 y posteriores). Las carpetas ~/.zcode y ~/.zcode/cli no se pueden eliminar, mover ni crear.

Encontrarás más detalle en el modelo de amenazas y en la compatibilidad con agentes.

Documentación de ZCode