zn-gate 的前 5 分钟

安装 zn-gate，确认它正在工作，并了解它的提示信息是什么意思。无需账户，也无需 API 密钥。

查看 .md

你在使用 AI 编码智能体（Claude Code、Codex CLI、Cursor 或 OpenCode），而你自己不怎么写代码。本页带你从零开始，直到"zn-gate 已开启，而且我看到它在工作"，然后说明它的提示信息是什么意思，以及如何移除它。无需账户，也无需 API 密钥。一切都在你的机器上运行。

开始之前

zn-gate 需要 Node.js 18 或更高版本（请从 nodejs.org 安装 LTS 版本）；Claude Code 插件需要 Node.js 20.12 或更高版本。如果 node --version 显示 "command not found"，请从 nodejs.org 安装 LTS 版本，然后打开一个新的终端。请在你自己的终端中运行下面的每条命令，而不是通过你的智能体运行。

1. 安装

npx -y zn-gate init

init 会在你的机器上查找编码智能体，并在运行每一步之前先显示该步骤。它会先询问你，你可以拒绝。对于 Claude Code，它会安装 zn-gate 插件（如果你的 Node.js 版本低于 20.12，则安装 zn 的 hooks）。对于 Codex CLI、Cursor 和 OpenCode，它会安装 zn 的 hooks。hook 是你的智能体在使用某个工具之前运行的一小段检查。每次为一个智能体进行设置的说明，请见 README。

想先看看吗？npx -y zn-gate reach 会列出你的智能体能够访问的内容（机密名称、凭据文件、MCP 服务器）。它不会更改任何内容，也不会发送任何内容。参见 reach。

2. 检查它是否工作

init 结束时会进行这项检查。你可以随时运行它：

npx -y zn-gate check

它会创建一个临时文件夹，在 .env 文件中放一个假密钥，请求你的智能体的 hook 读取它，然后删除该文件夹。下面是真实输出：

zn-gate check: does zn stop your coding agent from reading a secret?

zn made a test folder with a fake key in a .env file and an ordinary file next to it, then asked
each agent's zn hook whether the agent may read them. This is what happened:

  OK Claude Code  blocked the .env file and allowed the ordinary file. Your agent would be told:
     "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."
  -  Codex CLI    not found on this machine
  -  Cursor       not found on this machine
  -  OpenCode     not found on this machine

Your agent cannot read secret files such as .env through these tools. Nothing was sent anywhere.
If your agent needs a value from .env, keep it in zn's vault instead: `zn env shadow .env`.
More: https://usezn.com/docs/check

The test folder was deleted.

OK 表示该智能体受到保护。以 - 开头的行表示 zn 没有为该智能体设置，或者该智能体不在你的机器上。显示 NOT protected 的行会说明原因以及需要运行什么。更多内容见 check。

3. 工作时你会看到什么

zn-gate 会通过三种方式告知你。拦截和审批询问来自 zn 的 hooks，并显示在你的智能体窗口中。警告来自 zn 的文本检查，只有当你的智能体告诉你时才会传达给你。

一次拦截

zn 阻止了某个可能泄露机密或看起来像攻击的操作，该操作没有执行。这里，位于 ~/my-project 的智能体尝试运行 cat .env。以下是 zn 的原话回复：

{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"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 没有安装在你的 PATH 中（例如你使用的是 npx），消息中会显示 npx -y zn-gate@1.13.1，而不是 zn。

deny 就是拦截。其后的句子是下一步操作。你该怎么做：

  1. 阅读原因。它是写给你和你的智能体的。
  2. 如果智能体需要该文件中的某个值，请你自己在终端中运行消息中的命令：npx -y zn-gate env shadow .env。真实的值会移入 zn 的加密保险库，文件中保留标记。参见 secrets。
  3. 如果这次拦截让你感到意外，不要去寻找绕过它的办法。请询问你的智能体为什么想读取那个文件。

像 ls 这样的普通命令不会收到任何回复：它被允许执行，你也看不到任何内容。

审批询问

有时 zn 不会拦截，而是先询问你。当命令使用了机密标记时会出现这种情况。下面是一个向 https://example.com/api 发送 __ZN_EXAMPLE_TOKEN__ 的命令的真实回复：

"permissionDecision":"ask","permissionDecisionReason":"zn: this command runs through zn run (zn's secret wrapper) for EXAMPLE_TOKEN; the first time, you approve the command, and secret values in its output stay hidden."

之后，你的智能体会显示其常规的权限询问。请阅读该命令。只有在它正是你所预期的时候才批准。

一条警告

zn 还有一项文本检查，你的智能体可以通过 zn 自带的工具调用它。其中一些它查找的模式也会出现在普通文本中，例如 "bypass the cache"。对于这些情况，zn 不会拦截：它会放行文本，并附加一条简短的警告，称为 advisory。该警告发给你的智能体，而不是你的屏幕，因此只有当你的智能体提到它时你才会看到。zn 的 hooks 不会就这些情况警告你。你可以自己运行同样的检查。以下是 npx -y zn-gate analyze "You can bypass the cache with --no-cache." 的真实输出：

{
  "verdict": "allow",
  "confidence": 0.99,
  "rule": "none",
  "reason": null,
  "engine": "oss-local",
  "rules_version": "2026-10-19.1",
  "advisory": {
    "rule": "pi:bypass",
    "reason": "Guardrail bypass attempt"
  },
  "mode": "oss-local"
}

"verdict": "allow" 表示没有任何内容被阻止。advisory 说明了为什么值得留意。你该怎么做：阅读它指向的文本。如果无害，就继续。如果你没有预料到（例如在你下载的文件中），不要让你的智能体照着它做。要让文本检查也拦截这类情况，请开启严格模式：设置 ZN_STRICT=1，或在项目的 zn.config.json 中添加 "strict": true。

作为对比，npx -y zn-gate analyze "ignore all previous instructions" 是一次拦截："verdict": "block"，原因为 "Override prior instructions"。

如果出现故障

  • npx: command not found：安装 Node.js 的 LTS 版本，打开新的终端，然后重新运行该命令。
  • Windows 上出现 "running scripts is disabled on this system"：使用 npx.cmd 代替 npx，或参阅 README 中的 PowerShell 说明。
  • init 只显示步骤而不做任何更改：是 AI 智能体或脚本运行了它。请你自己在终端中运行。
  • check 显示 NOT protected：该行会说明需要运行什么。
  • zn 拦截了你需要的内容：机密请使用 npx -y zn-gate env shadow .env，或在 Discussions 中提问。

移除 zn-gate

在你自己的终端中移除你安装过的部分。

  • Hooks（Codex CLI、Cursor、OpenCode，或不使用插件的 Claude Code）：npx -y zn-gate hooks uninstall claude-code。其他智能体请使用 codex、cursor 或 opencode；如果你只为某一个项目安装，请添加 --project。在此之前会先写入设置文件的备份。
  • Claude Code 插件：运行 claude plugin uninstall zn-gate@usezn，或在 Claude Code 中输入 /plugin，打开 Installed 标签页，选择 zn-gate，然后点击 Uninstall。若还要移除 usezn 插件列表，请运行 claude plugin marketplace remove usezn。
  • 被包装的 MCP 服务器（来自 init --wrap-mcp）：npx -y zn-gate init --revert 会将每个 MCP 设置文件恢复为 zn 包装之前刚刚保存的版本。之后你对这些文件所做的更改（例如你添加的 MCP 服务器）会丢失，因此请在之后重新添加。它只撤销 MCP 包装，不会撤销 hooks。
  • 程序本身，如果你是用 npm install -g zn-gate 安装的：npm uninstall -g zn-gate。
  • Python 包，如果你是用 pip install zn-gate 安装的：pip uninstall zn-gate。
  • 你已移入保险库的 .env 文件会保留诸如 __ZN_API_KEY__ 之类的标记。env shadow 会告诉你如何放回真实的值。在移除 zn-gate 之前请先完成这一步。
  • zn 自己的文件夹：zn 将其保险库、设置和计数器保存在你主文件夹中的 .zn 文件夹内，移除 zn-gate 后该文件夹仍会保留。只有在你放回 .env 中的值之后才删除它，因为保险库中保存着这些值。

如果之后你想确认 zn 已关闭，可以运行 npx -y zn-gate check。

下一步