Solución de problemas de zn-gate

Los once mensajes que más se ven al empezar con zn-gate: qué significa cada uno y qué hacer. Cada mensaje está copiado tal como lo imprime zn-gate. Una parte entre paréntesis angulares, como <agent>, es un hueco que zn rellena por ti. Los mensajes se citan tal como los imprime zn-gate 1.13.1.

Ejecuta cada comando en tu propia terminal, no a través de tu agente de IA. Las palabras que no conozcas están en el glosario.

1. Node.js es demasiado antiguo

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.

Qué significa: zn-gate es un programa de Node.js y tu ordenador tiene una versión demasiado antigua. El número de versión del mensaje es el tuyo y será distinto.

Qué hacer:

1. Instala la versión LTS desde nodejs.org, o ejecuta nvm install --lts si usas nvm.
2. Abre una terminal nueva y comprueba con node --version. Debe decir 18 o superior (se recomienda la versión LTS; el plugin de Claude Code necesita 20.12 o superior).
3. Vuelve a ejecutar tu comando.

2. npx: command not found

Qué significa: Node.js no está instalado, o esta terminal se abrió antes de instalarlo. npx y npm vienen con Node.js.

Qué hacer: instala la versión LTS de Node.js, abre una terminal nueva y vuelve a ejecutar el comando. Comprueba con npx --version.

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

Qué significa: Windows PowerShell bloquea por defecto el script que inicia npm y npx. No le pasa nada a zn-gate.

Qué hacer, cualquiera de estas opciones:

• Usa las versiones .cmd: npx.cmd -y zn-gate init, o npm.cmd install -g zn-gate.
• Ejecuta los mismos comandos en el Símbolo del sistema en lugar de PowerShell.
• Permite los scripts locales para tu cuenta: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Más en el README.

4. Necesita que estés en tu propia terminal

Puedes ver uno de estos:

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.

Qué significa: algunos pasos cambian tu configuración o tocan tus secretos, así que zn solo los ejecuta cuando los escribe una persona. Se niega cuando los ejecuta tu agente de IA, o cuando los ejecuta un script sin nadie ante el teclado. Es a propósito. No se cambió nada.

Qué hacer: abre tú mismo una ventana de terminal (no la del agente) y ejecuta allí el mismo comando. Si solo ves "started from ...", zn cree que hay un agente por encima de tu terminal en la cadena de procesos. Abre una ventana de terminal nueva desde el menú del sistema y vuelve a intentarlo. Con init, los pasos impresos bajo el mensaje son los comandos que debes ejecutar.

5. "Your secret vault is locked"

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

Qué significa: zn guarda los valores reales de tus secretos en una bóveda cifrada, y la bóveda está cerrada. Se bloquea sola tras 30 minutos sin uso, como máximo a las 8 horas, o cuando reinicias el ordenador. Si zn no está instalado en tu ordenador, el mensaje da en su lugar la forma npx -y zn-gate@<version> unlock.

Qué hacer:

1. Ejecuta zn unlock en tu propia terminal. Puede pedirte una frase de contraseña. Escríbela tú: zn nunca la lee desde tu agente.
2. Ejecuta zn vault status para ver que dice unlocked.
3. Vuelve a ejecutar el comando que falló.

Más en secretos. Si te pide una terminal para introducir la frase de contraseña y no tienes ninguna (por ejemplo por SSH), esa página explica cómo ejecutar la bóveda en una terminal aparte.

6. Tu agente fue 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.

Qué significa: tu agente intentó leer un archivo con secretos en texto plano. zn lo detuvo, así que los secretos no llegaron al agente. Es zn funcionando, no un error.

Qué hacer:

1. Si el agente necesita un valor de ese archivo, ejecuta tú mismo zn env shadow .env en tu propia terminal. Los valores pasan a la bóveda y el archivo conserva marcadores como __ZN_API_KEY__ que el agente puede usar.
2. Si no esperabas esa lectura, pregunta a tu agente por qué quería ese archivo, y no busques una forma de saltarte el bloqueo.
3. Para recuperar tu .env original, ejecuta el comando de restauración que imprimió zn env shadow, por ejemplo zn env unshadow .env --backup <name>.

Más en secretos y qué significa la comprobación.

7. Tu agente ignora los hooks de zn en un ordenador gestionado

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.

Otras versiones dicen que la política "runs only the hooks in its managed settings (allowManagedHooksOnly)", que un archivo de ajustes tuyo "sets disableAllHooks", o que una lista de MCP gestionada no incluye el servidor "secrets" de zn.

Qué significa: un ajuste impide que se ejecuten los hooks de zn. Normalmente tu empresa o centro controla los ajustes de Claude Code; a veces es una línea de tu propio archivo de ajustes. Claude Code no muestra ningún aviso, así que zn te lo dice cuando instalas los hooks o ejecutas npx -y zn-gate check o npx -y zn-gate status. Hasta que se arregle, zn no está protegiendo a ese agente.

Qué hacer:

• Si el mensaje nombra tu propio archivo de ajustes, esa línea desactiva todos los hooks que instales, también los de zn. Quita la línea disableAllHooks, salvo que la pusieras a propósito, y ejecuta npx -y zn-gate check.
• Si nombra una política de la organización, pide a tu administrador que añada zn a los ajustes gestionados. Envíale el mensaje.
• Ejecuta npx -y zn-gate check para ver qué agentes están protegidos.

Más en compat.

8. zn-gate connect no acepta tu clave

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.

Qué significa: connect es opcional y activa la comprobación en la nube. Solo guarda una clave si es una clave de solo análisis y funciona. El mensaje dice qué parte falló. No se guardó nada, así que no hay nada que deshacer.

Qué hacer:

1. Crea una clave nueva de solo análisis en la página de conexión que indica el mensaje. No uses una clave con acceso completo.
2. Ejecuta zn-gate connect y pega la clave en el campo oculto. Nunca pongas la clave en la línea de comandos.
3. Para desactivar la comprobación en la nube cuando quieras: zn-gate disconnect.

Más en connect. No necesitas connect para usar zn-gate: sin él, todo se queda en tu máquina.

9. "will not send the saved key" (ajustes 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

Qué significa: tu terminal tiene un ajuste que desactiva la comprobación de los certificados de los sitios web, cambia cómo funcionan las conexiones seguras, o podría imprimir o leer tu clave. zn-gate se niega a enviar tu clave guardada por una conexión así. Otros mensajes parecidos nombran NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, OPENSSL_CONF, NODE_DEBUG o NODE_OPTIONS. Tus comprobaciones locales siguen funcionando.

Qué hacer: zn-gate se niega a propósito: con ese ajuste, alguien entre tú y usezn.com podría leer tu clave. No se ha roto nada, y las comprobaciones locales siguen funcionando sin la comprobación en la nube.

• Si lo pusiste tú, por ejemplo para una prueba, quítalo, abre una terminal nueva y vuelve a intentarlo. En macOS o Linux, unset NODE_TLS_REJECT_UNAUTHORIZED (o el nombre que aparece en el mensaje) lo quita en esta terminal. Si vuelve, mira en el archivo de arranque de tu shell (como ~/.zshrc o ~/.bashrc).
• Si tu empresa lo necesita, por ejemplo por un proxy con su propio certificado, déjalo y consulta a tu administrador. Hasta entonces zn-gate usa solo sus comprobaciones locales en este ordenador.
• Nunca desactives la comprobación de certificados para que desaparezca este mensaje.

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.

Qué significa: zn-gate guarda un registro de lo que decidió. Cada línea está enlazada con la anterior, así que una línea editada, cortada o escrita a medias rompe la cadena. zn no repara un registro: deja de escribir en él para no ocultar el daño. Tu protección sigue funcionando. Solo se detiene el registro. En Windows el mensaje muestra un comando move en lugar de mv.

Qué hacer:

1. Ejecuta npx -y zn-gate evidence --verify. Te dice dónde está la rotura.
2. Conserva el archivo viejo si lo necesitas para revisarlo. Apártalo con el comando que aparece en el mensaje.
3. El siguiente evento empieza un registro nuevo. Ejecuta npx -y zn-gate evidence --verify otra vez para comprobar que está bien.

11. El plugin de Claude Code necesita un Node.js más nuevo

Puedes ver uno de estos. El primero sale de npx -y zn-gate check y el segundo 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.

El número de versión de los mensajes es el tuyo y será distinto.

Qué significa: el plugin de zn-gate para Claude Code necesita Node.js 20.12 o posterior. Con un Node.js más antiguo (por ejemplo Node.js 18, que apt instala en muchos sistemas Debian y Ubuntu), el plugin no funciona a propósito, y Claude Code puede mostrar sus servidores MCP como fallidos al conectar. zn-gate y los hooks de zn siguen funcionando con Node.js 18 o posterior. No pasa nada con tus archivos.

Cómo comprobarlo:

1. Ejecuta node --version en tu propia terminal. Si dice una versión inferior a 20.12 (como v18.19.1), esa es la causa. Claude Code arranca el plugin con el primer node de su PATH, así que usa la terminal desde la que inicias Claude Code.
2. Ejecuta npx -y zn-gate check. Una línea de Claude Code que diga NOT protected: the zn-gate plugin needs Node.js 20.12 or later lo confirma.

Qué hacer, una de las dos:

• Actualizar Node.js (recomendado): instala la versión LTS de Node.js desde nodejs.org, abre una terminal nueva, comprueba que node --version la muestra y luego inicia una sesión nueva de Claude Code. Si tienes varias instalaciones de Node.js, asegúrate de que la nueva sea la primera en tu PATH.
• O usar los hooks de zn en lugar del plugin: ejecuta npm install -g zn-gate, luego zn hooks install claude-code, luego claude plugin disable zn-gate@usezn, todo en tu propia terminal. Después ejecuta npx -y zn-gate check otra vez.

Ejecutar npx -y zn-gate init con un Node.js anterior a 20.12 hace la segunda opción por ti: omite el plugin y configura en su lugar los hooks de zn para Claude Code, y si el plugin ya está instalado lo desactiva cuando los hooks funcionan.

También útil

• Tu agente bloquea cada petición después de actualizar o quitar Node.js: mira If your agent blocks every prompt.
• ¿No sabes qué está protegido? npx -y zn-gate check, explicado en check.
• Sigues atascado: pregunta en Discussions. Indica tu versión de zn-gate (zn-gate --version), tu sistema operativo y el mensaje, y no incluyas ningún secreto.