适用于 Gemini CLI 的 zn-gate

为 Gemini CLI 安装 zn 的实验性钩子：在工具运行之前，阻止读取和写入密钥文件，以及处理密钥的 shell 命令。

查看 .md

对 Gemini CLI 的支持是实验性的。请把它当作第一道防线：zn 可以阻止一次调用，但无法隐藏工具返回的内容（见下面的“限制”）。

2026 年 6 月 18 日，Google 已在免费账户和 Google One 账户中用 Antigravity CLI 取代了 Gemini CLI。Antigravity 现在是新安装的首选；zn-gate 仍然支持 Gemini CLI。

你需要 Node.js 18 或更高版本。在终端中逐行粘贴以下命令，每行后按回车：

npm install -g zn-gate
zn hooks install gemini

在 macOS 和 Linux 上，如果 npm install -g 因 EACCES 失败，请按照 npm 的指南修复权限错误操作。

无需管理员权限即可修复：

mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

如果使用 bash，请写入 ~/.bashrc 而不是 ~/.zshrc。

然后打开新的终端并运行 npx -y zn-gate init。使用 nvm 等 Node.js 版本管理器也可以避免该问题。

然后打开一个新的 Gemini CLI 会话。zn 会把它的钩子添加到 ~/.gemini/settings.json。之后要更新？请参阅升级 zn-gate。

仅用于一个项目

在项目内运行 zn hooks install gemini --project。它会把 .gemini/settings.json 写入该项目，而不是你的主目录。在你批准之前，Gemini CLI 会把项目钩子视为不受信任，并且该钩子会从你的 PATH 运行 zn，所以每个打开该项目的人都需要安装 zn-gate。

你将获得的保护

  • zn 会在每次工具调用运行之前检查它。
  • 按文件路径，阻止读取和写入密钥文件，例如含值的 .env 文件。
  • 处理密钥的 shell 命令会被阻止。对于使用 __ZN_<NAME>__ 标记的命令，zn 会阻止它，并告诉模型应改用的确切 zn run -- ... 命令行。
  • 会输出明文密钥的跨文件夹搜索会被阻止。请指定更窄的路径。
  • 智能体无法编辑 Gemini CLI 自己的设置文件。
  • zn 从不替你批准调用。当它没有异议时，由 Gemini CLI 自己的批准机制决定。

限制

  • 工具返回的内容不会被改动。 命令打印出的值，或位于智能体可读取文件中的值，仍会到达模型。请把你的密钥放在保险库里。
  • zn 会拦截它会询问的内容。 Gemini CLI 的钩子无法向你请求确认，所以 zn 会阻止它会拒绝的调用，以及它会询问的调用，并给出原因和批准方式。其余情况适用 Gemini CLI 自身的审批。
  • 粘贴到手动输入的提示词中的密钥不会被检查。
  • 钩子崩溃或超时时，Gemini CLI 会让调用继续运行，因此 zn 改为拦截。 在 Gemini CLI 中只有明确的拒绝才会拦截。zn 为其钩子设置了 15 秒超时（Gemini CLI 自身的默认值是 60 秒），11 秒后仍在运行的检查会得到拦截响应。在用户级安装中由一个小的启动脚本、在项目级安装中由一个启动守卫，对失败的钩子（包括安装 zn 时使用的 Node.js 已不存在的情况）给出拦截响应。
  • 设置可以关闭该钩子。 hooksConfig.enabled: false、hooksConfig.disabled 中的钩子名称，以及 /hooks disable 命令，都会将它关闭。zn-gate check 会报告这些情况。
  • zn 是用 Gemini CLI 0.64.0 和一个脚本化的模型检查的，并非覆盖所有版本。

检查是否正常工作

在新的终端中运行 zn-gate check。应显示 Gemini CLI 的 OK。输出含义。

在 Windows PowerShell 中，如果 npm 提示 "running scripts is disabled on this system"，请改用 npm.cmd 和 zn.cmd：参见安装。

如何移除

在你自己的终端中运行 zn hooks uninstall gemini（项目级安装请加上 --project）。