ZCode desktop app

在 z.ai 的 ZCode desktop app 中配置 zn-gate：安装它的钩子，以及 zn-gate 在该环境中覆盖和不覆盖的内容。

查看 .md

在 z.ai 的 ZCode desktop app 中配置 zn-gate：安装它的钩子，以及 zn-gate 在该环境中覆盖和不覆盖的内容。

安装钩子

在你自己的终端中运行，不要通过你的智能体：

npx -y zn-gate init

init 会查找 ZCode desktop app（~/.zcode 文件夹，或 PATH 中的 zcode 程序），显示每一步，并在执行每一步之前征求你的同意。如果已安装 zn-gate（npm install -g zn-gate），只想执行这一步：

zn hooks install zcode

这会为你的用户把 zn 的钩子写入 ~/.zcode/cli/config.json，与文件中已有的内容并存。它还会：

  • 开启 hooks.enabled，因为该开关关闭时 ZCode 不会运行任何钩子（默认是关闭的）。如果它原本是关闭的，而你的文件中已经有自己的钩子，安装时会列出这些钩子：它们将从下一次 ZCode 会话开始运行。zn hooks uninstall zcode 会把该开关恢复为原来的状态（关闭或未设置），除非你在此期间自己修改过它；
  • 在同一文件中注册 zn-gate 的 secrets MCP 服务器；
  • 在修改文件之前保留一份备份。

zn hooks uninstall zcode 会移除 zn 的钩子和该服务器，并保留你自己的设置不变。安装或卸载之后请启动新的 ZCode 会话：正在运行的会话会沿用它启动时的钩子。

没有 --project 安装方式。ZCode 不会运行项目中的钩子（<project>/.zcode/config.json），只运行你用户文件中的钩子，因此团队中的每个人都需要在自己的机器上运行一次 zn hooks install zcode。

然后运行 npx -y zn-gate check，确认钩子在你的机器上能正常工作。

ZCode 插件

zn-gate 的 ZCode 插件版本已经就绪。在 ZCode 中添加它的步骤（Settings，Plugins）将随其插件仓库一起发布。在此之前，在 ZCode 中使用 zn-gate 的受支持方式是上文的 zn hooks install zcode。

插件是什么，以便你在它发布时知道会得到什么：

  • 它自带一份 zn-gate，固定在某一个版本，并在每次调用时对照已发布版本中每个文件的 SHA-256 进行检查。ZCode 不会安装 npm 包，所以无需下载，也不会缺失任何东西。它不需要账户，也不需要 API 密钥，并且不通过网络发送任何内容。
  • 无论 hooks.enabled 如何设置，ZCode 都会运行插件的钩子，因此即使该开关关闭，插件仍会继续提供保护。它的钩子与 zn hooks install zcode 相同。
  • 它的 hook 是一个 POSIX shell 脚本。已在 Linux 上使用 ZCode 桌面应用 3.16.3 测试；macOS 未测试。不支持 Windows：在 Windows 上请使用 zn hooks install zcode。它需要 Node.js 20.19 或更高版本，或者使用 ZCode 自身运行所用的那个版本；如果找不到，或任何环节失败，它会拦截该调用。ZCode 的文档没有说明 hook 失败时会发生什么；在我们使用 Linux 上的 ZCode 桌面应用 3.16.3 的测试中，失败的 hook（退出码不是 2、崩溃或超时）会让调用照常运行，只有退出码 2 或 deny 响应才会拦截调用。
  • 如果插件钩子启动时 Node.js 挂起，该钩子仍会在 28 秒内给出响应，低于插件为其钩子设置的 30 秒超时：它会拦截该调用，或在无法拦截的事件上仅发出警告。
  • 请使用插件或 zn hooks install zcode 其中之一，不要同时使用：ZCode 不会移除重复的钩子，因此每次调用都会被检查两次。当插件处于开启状态时，zn hooks install zcode 会发出警告，zn-gate check 也会报告这一点。
  • 你可以在 Settings，Plugins 中关闭插件。当插件关闭且 hooks.enabled 为 false 时，zn 的任何内容都不会在 ZCode 中运行，zn-gate check 会将其报告为未受保护。
  • zn 的策略保护插件的文件：智能体不能写入、删除或移动 ~/.zcode/cli/plugins/ 中的任何内容（zn-gate 1.14.0 及更高版本）。以你的身份运行的其他程序仍然可以编辑它们。

zn-gate 在 ZCode 中保护什么，以及不保护什么

项目 在 ZCode 中
拦截智能体读取或写入 .env 和凭据文件（钩子） 是，安装钩子之后
拦截处理机密的 shell 命令，并告诉智能体通过 zn run 运行它们（钩子） 是
在 MCP 工具调用运行之前检查其参数（钩子） 是：机密值或 __ZN_ 标记会被拦截，个人数据会先询问你，文件路径会进行读取和写入检查
拦截粘贴到聊天中的机密 是：提示在到达模型之前就会被拦下（ZCode 不允许钩子修改提示，因此是拦截，而不是清理）
阻止智能体编辑 ZCode 的配置文件和 ~/.zn 尽力而为：ZCode 的文件工具和 shell 会被检查，其他修改该文件的方式不会
从 shell 输出和文件内容中移除机密 否：ZCode 的钩子无法改写工具返回的内容。当输出中包含机密时，zn 会为模型添加一条提示
支持项目中的钩子 否：ZCode 会忽略它们
智能体可用的 zn-gate 检查（MCP） 是，即安装时注册的 secrets 服务器

需要了解的事项：

  • 已测试版本。 钩子配置在应用文档所述的同一个用户文件中（~/.zcode/cli/config.json，Settings -> Hooks），zn 也把它们写在那里。zn 遵循 ZCode 官方文档中描述的钩子行为，并且 zn 的钩子有自动化测试覆盖。已在 Linux x64 上的官方 ZCode 桌面应用 3.16.3 上完成端到端测试（2026 年 10 月）：安装 zn 后，Settings -> Hooks 会列出 zn 的钩子，在真实任务中，zn 阻止了对 .env 和 ~/.aws/credentials 的读取，而普通命令和读取照常运行；同样的检查在使用应用自带智能体的无界面模式下也通过了。同样的检查在 Windows x64 上也通过了（Windows Server 2022，相同的应用版本，2026 年 10 月），分别针对管理员和标准用户，通过应用自带的智能体完成；Windows 应用窗口本身未被操作。未测试： macOS。ZCode 是一个年轻的产品，新版本可能会改变这一行为，因此请用 zn-gate check 查看钩子在你的机器上是否有效。
  • 如果 zn 钩子本身失败，ZCode 可能会放行该调用。 ZCode 的文档没有说明钩子失败时会发生什么；在我们使用 Linux 上的 ZCode 桌面应用 3.16.3 的测试中，失败的钩子（退出码不是 2、崩溃或超时）会让调用照常运行，只有退出码 2 或 deny 响应才会拦截调用。zn 覆盖了它能覆盖的情况：它自己的检查在失败或运行过久时会返回 deny 并以退出码 2 退出，而 zn 写入的启动脚本（~/.zn/hooks/zn-hook-zcode.sh）在安装 zn-gate 时使用的 Node.js 已不存在时，会拦截调用并给出提示。启动脚本还有自己的 28 秒期限（比 zn 在其钩子条目上设置的 30 秒超时少 2 秒，适用于 macOS、Linux 和 Windows）：启动时卡住的钩子会被终止并拦截调用。ZCode 完全无法启动的钩子（例如启动脚本文件被删除了）不在覆盖范围内；zn-gate check 会报告这种情况。
  • 提问需要有人回答。 当 zn 要先询问你时（MCP 调用中包含个人数据），ZCode 需要一个权限提示来显示该问题。当没有人能回答权限提示时，zn 的提问会以拦截告终，调用不会运行。未在桌面应用中测试。
  • 钩子被关闭。 如果 ~/.zcode/cli/config.json 中有 "hooks.enabled": false，ZCode 不会运行该文件中的任何钩子，包括 zn 的（ZCode 插件的钩子仍会继续运行）。单个条目也可以用 "enabled": false 关闭，或用 async 设为在后台运行，而后台钩子无法拦截任何内容。zn-gate check 会把这三种情况都报告为未受保护，zn hooks install zcode 可以修复它们。
  • 值仍可能到达模型。 命令打印出的值，或在智能体被允许读取的文件中发现的值，不会被移除。请把机密保存在保险库中。
  • 子智能体。 未测试：ZCode 是否会在它的子智能体内部运行钩子。
  • 智能体无法通过其工具编辑的文件： ~/.zcode/cli/config.json。zn 的策略同样以相同方式保护项目的 <project>/.zcode/config.json，以及插件文件夹 ~/.zcode/cli/plugins/（zn-gate 1.14.0 及更高版本）。文件夹 ~/.zcode 和 ~/.zcode/cli 不能被删除、移动或创建。

更多细节见威胁模型和智能体兼容性。

ZCode 文档