zn-gate 故障排查

刚开始使用 zn-gate 时最常遇到的十一条提示信息：每条是什么意思、该怎么做。每条信息都与 zn-gate 打印的原文一致。

查看 .md

刚开始使用 zn-gate 时最常遇到的十一条提示信息：每条是什么意思、该怎么做。每条信息都与 zn-gate 打印的原文一致。尖括号中的部分，例如 <agent>，是 zn 替你填写的空白。消息引用的是 zn-gate 1.13.1 打印的原文。

所有命令都在你自己的终端中运行，不要通过你的 AI 智能体运行。不认识的词在术语表中。

1. Node.js 版本过旧

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.

含义： zn-gate 是一个 Node.js 程序，而你的电脑上的版本太旧。信息中的版本号是你自己的，会有所不同。

怎么做：

  1. 从 nodejs.org 安装 LTS 版本；如果你使用 nvm，则运行 nvm install --lts。
  2. 打开一个新的终端，用 node --version 检查。它必须显示 18 或更高（推荐 LTS 版本；Claude Code 插件需要 20.12 或更高）。
  3. 再次运行你的命令。

2. npx: command not found

含义： 没有安装 Node.js，或者这个终端是在你安装之前打开的。npx 和 npm 随 Node.js 一起提供。

怎么做： 安装 Node.js 的 LTS 版本，打开一个新的终端，再次运行命令。用 npx --version 检查。

3. "running scripts is disabled on this system"（Windows）

含义： Windows PowerShell 默认会阻止启动 npm 和 npx 的脚本。zn-gate 本身没有问题。

怎么做，任选其一：

  • 使用 .cmd 版本：npx.cmd -y zn-gate init，或 npm.cmd install -g zn-gate。
  • 在命令提示符（Command Prompt）而不是 PowerShell 中运行同样的命令。
  • 为你的账户允许本地脚本：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。

更多内容见 README。

4. 它需要你在自己的终端中操作

你可能会看到下面其中一条：

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.

含义： 有些步骤会更改你的设置或接触你的密钥，所以 zn 只在有人亲自输入时才运行它们。当你的 AI 智能体运行它们，或者脚本在没有人在键盘前的情况下运行它们时，zn 会拒绝。这是有意为之。没有任何内容被更改。

怎么做： 自己打开一个终端窗口（不是智能体的窗口），在其中运行同样的命令。如果你只看到 "started from ..."，说明 zn 认为在进程链中你的终端上方有一个智能体。请从系统菜单打开一个全新的终端窗口，再试一次。对于 init，信息下方打印的步骤就是要运行的命令。

5. "Your secret vault is locked"

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

含义： zn 把你的密钥真实值存放在加密保险库中，而保险库当前是关闭的。它会在 30 分钟不使用后、最长 8 小时后，或在你重启电脑时自动锁定。如果你的电脑上没有安装 zn，信息中会改为给出 npx -y zn-gate@<version> unlock 这种形式。

怎么做：

  1. 在你自己的终端中运行 zn unlock。它可能会要求输入口令。请自己输入：zn 绝不会从你的智能体那里读取口令。
  2. 运行 zn vault status，确认它显示 unlocked。
  3. 再次运行刚才失败的命令。

更多内容见密钥。如果它要求一个终端来输入口令而你没有（例如通过 SSH 连接时），该页面说明了如何在单独的终端中运行保险库。

6. 你的智能体被拦截：".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.

含义： 你的智能体试图读取一个含有明文密钥的文件。zn 拦住了它，所以密钥没有到达智能体。这是 zn 在起作用，不是错误。

怎么做：

  1. 如果智能体需要该文件中的某个值，请你自己在自己的终端中运行 zn env shadow .env。这些值会移入保险库，文件中保留 __ZN_API_KEY__ 这样的标记，智能体可以使用它们。
  2. 如果你没有预料到这次读取，请问问你的智能体为什么想要那个文件，不要去找绕过拦截的办法。
  3. 要恢复你原来的 .env，请运行 zn env shadow 打印出来的恢复命令，例如 zn env unshadow .env --backup <name>。

更多内容见密钥和检查结果的含义。

7. 在受管理的电脑上，你的智能体忽略了 zn 的钩子

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.

其他版本会说该策略 "runs only the hooks in its managed settings (allowManagedHooksOnly)"，说你的某个设置文件 "sets disableAllHooks"，或者说受管理的 MCP 列表中不包含 zn 的 "secrets" 服务器。

含义： 某项设置使 zn 的钩子无法运行。通常是你的公司或学校在控制 Claude Code 的设置；有时是你自己设置文件中的一行。Claude Code 本身不会给出任何警告，所以当你安装钩子，或运行 npx -y zn-gate check 或 npx -y zn-gate status 时，zn 会告诉你。在问题解决之前，zn 并没有在保护那个智能体。

怎么做：

  • 如果信息指出的是你自己的设置文件，那一行会关闭你安装的所有钩子，包括 zn 的。除非是你有意设置的，否则请删除 disableAllHooks 那一行，然后运行 npx -y zn-gate check。
  • 如果信息指出的是组织策略，请让你的管理员把 zn 添加到受管理的设置中。把这条信息发给他们。
  • 运行 npx -y zn-gate check 查看哪些智能体受到了保护。

更多内容见 compat。

8. zn-gate connect 不接受你的密钥

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.

含义： connect 是可选的，用于开启云端检查。只有当密钥是可用的仅限分析的密钥时，它才会保存。信息会说明是哪一部分出了问题。没有任何内容被保存，所以不需要撤销。

怎么做：

  1. 在信息中指出的连接页面上创建一个新的仅限分析的密钥。不要使用拥有完整权限的密钥。
  2. 运行 zn-gate connect，并在隐藏的输入提示处粘贴密钥。切勿把密钥写在命令行上。
  3. 随时关闭云端检查：zn-gate disconnect。

更多内容见 connect。使用 zn-gate 并不需要 connect：不使用它，一切都留在你的本机上。

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

含义： 你的终端中有一项设置，会关闭对网站证书的检查、改变安全连接的工作方式，或者可能打印或读取你的密钥。zn-gate 拒绝通过这样的连接发送你已保存的密钥。类似的信息会改为提到 NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、OPENSSL_CONF、NODE_DEBUG 或 NODE_OPTIONS。你的本地检查仍然正常工作。

怎么做： zn-gate 是有意拒绝的：有了这项设置，处在你和 usezn.com 之间的人就可能读到你的密钥。没有任何东西坏掉，没有云端检查时本地检查仍然正常工作。

  • 如果是你自己设置的，例如为了测试，请把它去掉，打开一个新的终端再试一次。在 macOS 或 Linux 上，unset NODE_TLS_REJECT_UNAUTHORIZED（或信息中的名称）可在当前终端中去掉它。如果它又出现了，请查看你的 shell 启动文件（例如 ~/.zshrc 或 ~/.bashrc）。
  • 如果你的公司需要它，例如因为代理使用自己的证书，请保留它并询问你的管理员。在此之前，zn-gate 在这台电脑上只使用本地检查。
  • 切勿为了让这条信息消失而关闭证书检查。

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.

含义： zn-gate 会保存一份它所做决定的日志。每一行都与前一行相连，所以被编辑、被截断或只写了一半的行会使链条断裂。zn 不会修复日志：它会停止向日志写入，以免掩盖损坏。你的保护仍在正常工作，只是记录停止了。在 Windows 上，信息中显示的是 move 命令，而不是 mv。

怎么做：

  1. 运行 npx -y zn-gate evidence --verify。它会告诉你断裂的位置。
  2. 如果需要复查，请保留旧文件。用信息中给出的命令把它移到一边。
  3. 下一个事件会开始一份新日志。再运行一次 npx -y zn-gate evidence --verify，确认一切正常。

11. Claude Code 插件需要更新的 Node.js

你可能会看到下面其中一条。第一条来自 npx -y zn-gate check，第二条来自 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.

信息中的版本号是你自己的，会有所不同。

含义： Claude Code 的 zn-gate 插件需要 Node.js 20.12 或更高版本。如果 Node.js 更旧（例如 Node.js 18，许多 Debian 和 Ubuntu 系统上的 apt 会安装它），插件会有意不工作，Claude Code 可能会把它的 MCP 服务器列为连接失败。zn-gate 本身和 zn 的 hooks 在 Node.js 18 或更高版本上仍可运行。你的文件没有任何问题。

如何检查：

  1. 在你自己的终端中运行 node --version。如果显示的版本低于 20.12（例如 v18.19.1），这就是原因。Claude Code 使用其 PATH 中的第一个 node 来启动插件，所以请使用你启动 Claude Code 的那个终端。
  2. 运行 npx -y zn-gate check。如果 Claude Code 那一行显示 NOT protected: the zn-gate plugin needs Node.js 20.12 or later，就确认了原因。

怎么做，二选一：

  • 更新 Node.js（推荐）： 从 nodejs.org 安装 Node.js LTS 版本，打开一个新终端，确认 node --version 显示的是它，然后开始一个新的 Claude Code 会话。如果电脑上装有多个 Node.js，请确保新的那个在你的 PATH 中排在最前面。
  • 或者用 zn 的 hooks 代替插件： 运行 npm install -g zn-gate，然后 zn hooks install claude-code，再运行 claude plugin disable zn-gate@usezn，全部在你自己的终端中进行。然后再运行一次 npx -y zn-gate check。

在低于 20.12 的 Node.js 上运行 npx -y zn-gate init 会替你完成第二种做法：它会跳过插件，改为为 Claude Code 设置 zn 的 hooks；如果插件已经安装，则会在 hooks 正常工作后将其关闭。

其他有用信息

  • 升级或卸载 Node.js 之后，你的智能体拦截每一条提示词：见 If your agent blocks every prompt。
  • 不确定哪些受到了保护：运行 npx -y zn-gate check，说明见 check。
  • 仍然卡住：到 Discussions 提问。请说明你的 zn-gate 版本（zn-gate --version）、你的操作系统和那条信息，并且不要包含任何密钥。