连接（可选的云端检查）

npx -y zn-gate connect

（如果你用 npm i -g zn-gate 安装了它，也可以直接运行 zn-gate connect。）

zn-gate 完全在你的电脑上运行，不需要账户，默认不发送任何内容。这个命令是可选的，它只增加一件事：当你或你的智能体使用 analyze_prompt 工具（或 zn-gate analyze）时，文本会先隐藏检测到的密钥，再由 usezn.com 上的 Galvanize 2 分类器检查。hook、文件和密钥保护、shield 以及其他所有命令都保持本地，绝不使用它。

zn-gate connect 做什么

1. 它只在你亲自输入命令的终端中运行。如果是 AI 智能体启动的，它会拒绝。
2. 它告诉你将要改变什么，并请你确认。
3. 它在浏览器中打开 usezn.com/connect。创建免费账户（或登录），并在那里创建一个仅限分析的 API 密钥。连接页面会替你完成这一步。
4. 回到终端，在隐藏的提示处粘贴密钥。你输入的内容不会显示，密钥也绝不会从命令行或环境变量中读取。
5. 它用 https://api.usezn.com 检查一次密钥。只发送密钥，作为请求头，只发往这一个地址，并通过经过验证的 TLS 连接。
6. 它保存密钥，并显示最后四个字符，方便你辨认。

它接受哪些密钥

connect 只接受仅限分析文本的密钥。这样的密钥不能读取你的用量，不能列出、创建或吊销其他密钥，也不能使用仪表板，因此即使副本泄露，能造成的影响也很小。完全访问权限的密钥会被拒绝，并提示你前往连接页面。服务器拒绝的密钥，或无法检查的密钥（没有响应、出错），同样会被拒绝。在所有这些情况下都不会保存任何内容。

密钥保存在哪里

只保存在以下位置之一，绝不保存在文件中：

• 你的系统密钥链：macOS 钥匙串、Windows 凭据管理器，或 Linux 的 Secret Service（GNOME Keyring、KWallet）。
• zn 保险库：当你的系统没有密钥链且保险库已解锁（zn unlock）时使用。保险库会对其加密。

如果两者都不可用（例如没有桌面会话的 Linux），则不会保存任何内容，zn-gate connect 会告知你。你仍然可以自行在 shell 中设置 ZN_CLOUD=1 和 ZN_API_KEY。

~/.zn/config.json 只记录你已连接、密钥保存在哪里以及它的最后四个字符，从不保存密钥本身。只有当保存的密钥以这四个字符结尾时，云端检查才会根据这条记录开启，所以手写的记录不起作用。保存的密钥只会发送到 https://api.usezn.com：对它而言，--url 和 ZN_API_URL 会被忽略。如果记录存在但无法读取已保存的密钥，提示词只在本地检查，zn-gate 会提示一次。

zn 的 hook 会拒绝你的智能体直接读取已保存密钥的途径，例如向系统密钥链索取 zn 自身条目的命令，或通过 zn 自己的模块加载密钥的代码。connect 和 disconnect 命令本身在由智能体运行时也会被拒绝，并且 zn 会在智能体看到的内容中隐藏密钥的格式（zn_ 后跟 48 个字符）。

这是一道屏障，而不是保险库的围墙：以你的身份运行的程序仍然可以向密钥链索取该密钥，就像索取任何密钥链条目一样。这就是为什么 connect 只接受仅限分析文本的密钥，也是你可以随时吊销它的原因。

查看和更改状态

• zn-gate status 显示是否已连接密钥以及它来自哪里（ZN_API_KEY、--key、密钥链或保险库），从不显示密钥本身。它还会显示检测引擎，以及可选的云端检查是否已开启。
• zn-gate connect --reconnect 替换已保存的密钥。
• zn-gate disconnect 从这台电脑上删除密钥，并关闭云端检查。
• 只有同时设置 ZN_CLOUD=1 时，通过 --key 或 ZN_API_KEY 提供的密钥才会取代已保存的密钥；否则使用已保存的密钥，并忽略 ZN_API_KEY 和 ZN_API_URL。ZN_LOCAL_ONLY=true 或 --local-only 即使已连接也会关闭云端检查。

断开连接并吊销密钥

如果保存了密钥，zn-gate disconnect 会询问是否同时在 usezn.com 上吊销它，使它在所有地方都失效。默认答案是否，只有明确回答“是”才会发送内容：通过 connect 使用的同一条经过验证的连接，向 https://api.usezn.com 发送一个带密钥的请求。

• 无论如何都会删除本地副本，即使请求失败。如果失败，命令会告知你，并指引你前往 usezn.com/api-keys，你可以在那里自行吊销密钥。
• zn-gate disconnect --revoke 会跳过询问，--no-revoke 则从不吊销，也不发起任何网络调用。
• 如果无法读取已保存的密钥，则不会删除任何内容。此时 --no-revoke 只删除本地副本。
• 与 connect 一样，该命令只在你自己的终端中运行。没有终端，或由 AI 智能体运行时，它会拒绝并且不改变任何内容，因此也不会吊销任何密钥。

如果出现问题

• 它拒绝运行：它只在你亲自输入命令的终端中运行。请打开你自己的终端并在那里运行，不要通过 AI 智能体或脚本。
• 密钥被拒绝：请使用连接页面创建仅限分析的密钥，然后再次运行 zn-gate connect。
• 无法检查密钥（没有响应、出错）：请检查网络连接后重试。
• 它说因为没有密钥链而没有保存任何内容：用 zn unlock 解锁保险库并再次运行 zn-gate connect，或自行在 shell 中设置 ZN_CLOUD=1 和 ZN_API_KEY。
• 你想停止使用：运行 zn-gate disconnect。

会发送什么

只发送 analyze_prompt 和 zn-gate analyze 调用的文本（zn-gate 已先移除它检测到的密钥；这条路径不会移除个人数据），以及作为请求头的密钥。工具输出、工具调用参数和工具描述绝不会被发送。参见哪些内容会离开你的电脑。