升级 zn-gate

更新 zn-gate 时该做什么：何时重新运行 zn hooks install，为什么 Codex 会要求你再次信任钩子，用 nvm 升级或移动 Node.js 之后怎么办，如何用 zn-gate check 检查，以及 1.8.0 以来每个版本需要你做的事。

查看 .md

本页的所有命令都请在你自己的终端中运行，不要通过 AI 智能体运行：当智能体启动 zn hooks install 和另外几个命令时，zn 的钩子会拒绝。

简短版本

  1. 更新软件包：npm install -g zn-gate（如果你使用 Python 包，再运行 pip install -U zn-gate）。如果你一直只运行 npx -y zn-gate ...，就没有什么需要更新。
  2. 在下面的表格中查找你的旧版本和新版本。大多数版本不需要其他操作。
  3. 运行 zn-gate check。每个已配置的智能体都应显示 OK。

如果 zn-gate check 提示某个智能体未受保护，它也会打印修复的命令。

当某个版本改动了钩子时，重新运行 zn hooks install <agent>

zn hooks install 的钩子（Claude Code、Codex CLI、Cursor）写入智能体自己的设置，因此新版 zn-gate 不会自动重写它们。当某个版本新增或改动了钩子，其发布说明会说明并指出是哪个智能体。为该智能体重新运行安装：

zn hooks install claude-code   # 或 codex、cursor、opencode

重新运行是安全的：它只更新 zn 自己的条目，不动你的其他设置。从 1.13.0 起，如果 zn-gate check 发现的 Claude Code 钩子缺少你的 zn-gate 已有的某个钩子，也会提示你。

其他情况：

  • Claude Code 的 zn-gate 插件通过 Claude Code 的插件管理器更新（在 Claude Code 中使用 /plugin）。之后开启一个新的 Claude Code 会话。插件会安装它所固定的 zn-gate 版本，所以不需要为它运行 zn hooks install。不要同时保留插件和 zn hooks install claude-code 的钩子：两者都会运行。用 zn hooks uninstall claude-code 移除钩子。
  • OpenCode 使用 zn-gate 写入的一个小插件文件。当某个版本提示时，重新运行 zn hooks install opencode。
  • 项目安装（zn hooks install <agent> --project）会写入可以提交到仓库的文件（.claude/settings.json、.codex/hooks.json、.cursor/hooks.json、.opencode/plugins/zn-gate.js）。它们从你的 PATH 调用 zn，因此会跟随你已安装的 zn-gate。当某个版本改动了钩子时，在项目里重新运行安装，并提交改动后的文件。

Codex 要求你再次信任钩子

Codex 只有在你信任某个钩子之后才会运行它，并且在钩子是新的或已改动时会再次询问。运行 zn hooks install codex 之后（第一次，以及任何改动了钩子的版本之后），打开 Codex，使用 /hooks 批准这些钩子。在你批准之前，Codex 不会运行新的或改动过的钩子，也就是说 zn 没有检查那一部分。只有当钩子能正常工作时，zn-gate check 才会把 Codex 显示为受保护。

对于已经自行验证过钩子的自动化流程，codex exec --dangerously-bypass-hook-trust 可以在一次运行中跳过这个询问。日常使用请不要这样做。

Node.js 被升级、移动或删除（nvm、fnm、Homebrew）

钩子的用户级安装会写入当时运行它的 Node.js 的路径和 zn-gate 文件的路径。全局 npm 包属于某一个 Node.js 版本，所以 nvm use、nvm uninstall、Homebrew 升级 Node.js 或重新安装 Node.js 都可能让钩子指向一个已不存在的位置。当钩子无法启动时：

  • 提示词：Claude Code 2.1.295 或更高版本、Cursor 和 OpenCode 会拦截它们，而不是不经检查就放行。Codex CLI 会放行。
  • 工具调用：在 Claude Code 和 Codex CLI 中，它们会不经检查就执行。

要修复，使用你想保留的那个 Node.js：

  1. 运行 npx -y zn-gate check。它会列出每个未受保护的智能体以及修复它的命令。
  2. 通常是 npm install -g zn-gate，然后 zn hooks install <agent>。如果你使用 Codex，请在 /hooks 中信任改动后的钩子。
  3. 如果使用 Claude Code 的 zn-gate 插件，先修复 Node.js（插件需要 20.12 或更高版本），然后开启一个新的 Claude Code 会话。
  4. 如果你马上就要用智能体，可以在修复前先为它关闭 zn：npx -y zn-gate hooks uninstall <agent>（zn 命令可能已随旧的 Node.js 一起消失），插件则用 claude plugin disable zn-gate@usezn。之后用 zn hooks install <agent> 或 claude plugin enable zn-gate@usezn 重新开启，再运行一次 zn-gate check。

检查是否正常工作

zn-gate check

它会创建一个临时文件夹，里面有一个带假密钥的 .env 文件和一个普通文件，让每个智能体已安装的钩子分别读取这两个文件，只有当 .env 文件被阻止、普通文件被允许时，才把该智能体算作受保护。不会发送任何内容，也不会更改任何设置。输出的含义。

每个版本需要你做什么

从 1.8.0 起的版本。“无需操作”表示更新软件包就够了。完整的改动列表见 changelog。

版本 日期 需要做什么
1.13.1 2026-10-20 仅当你使用 Python 的 LangChain 或 LlamaIndex 集成时：用 pip install -U zn-gate 更新。被阻止的提示词、工具调用或工具输出现在会停止 LangChain 的运行；在 mask_secrets=True 时，包含密钥的工具输出也会停止运行。ZnGuardCallbackHandler(on_block="return") 现在会抛出 ValueError：请改用 guard_langchain_tool(tool, on_block="return") 包装该工具（见 LangChain、CrewAI 和 LlamaIndex）。npm 包没有变化。 如果你用 guard_langchain_tool 包装工具，请以 mask_secrets=False 创建 handler。
1.13.0 2026-10-19 如果你用 zn hooks install claude-code 安装了 Claude Code 钩子，请重新运行它，以添加检查所输入的技能或命令会展开成什么内容的钩子（zn-gate check 会告诉你；插件已经包含它）。Node.js 低于 20.12 时，zn-gate init 会配置钩子而不是安装插件；如果你在那里装有插件，check 会给出解决办法。在不带 version 使用该 Action 的 GitHub 工作流中，请设置 version 来选择运行的版本：1.12.0 的 Action 默认使用 1.10.0。
1.12.0 2026-10-18 无需操作。如果你验证发布版本的签名，签名工作流现在是 build-release.yml（见验证发布版本）。
1.11.0 2026-10-17 无需操作。当 zn-gate scan 发现密钥就会失败的 CI 任务，可能开始因新类型的令牌而失败（例如 Square、Discord、Grafana 或 Notion 令牌）：查看每一条发现，并轮换任何真实的令牌。
1.10.0 2026-10-16 如果脚本在使用系统钥匙串时运行 zn unlock，现在需要交互式终端（使用口令后端的 --passphrase-stdin 仍可从管道运行）。
1.9.1 2026-10-16 无需操作。因 zn-gate scan 的发现而失败的 CI 任务，可能因更多类型的密钥而开始失败。Node.js 低于 18 时，zn-gate 和 zn 命令会停止，并提示如何安装 Node.js 18 或更高版本。
1.9.0 2026-10-16 如果脚本不带选项运行 zn-gate init 来包装 MCP 服务器，请改为 zn-gate init --wrap-mcp：单独的 init 现在是引导式设置，只在你自己的终端中运行。
1.8.2 2026-10-15 无需操作。
1.8.1 2026-10-15 如果你使用智能体钩子，请更新；无其他步骤。
1.8.0 2026-10-15 更新后运行一次 zn unlock：仍在运行的旧版本保险库会让钩子中的密钥保持为标记和令牌，直到它重启。不再支持 Python 3.8 和 3.9（那里的 pip 仍会安装 1.7.1）。在启用了 Warn 规则的 zn Team 组织中，不要退回 1.7.1。

如果你是从早于 1.8.0 的版本更新，请逐个查看中间所有版本的行。更早的版本见 changelog。