在 Windows 上使用 zn-gate
在 Windows 上通过 PowerShell 或 Git Bash 安装 zn-gate，了解它的文件存放位置（%USERPROFILE%\.zn）、智能体 hooks 在 Windows 上如何运行、最低版本和已知限制。
zn-gate 可在 Windows 上原生运行。本页说明与 macOS 和 Linux 不同的地方：从 PowerShell 或 Git Bash 安装、zn 的文件存放位置、智能体 hooks 如何启动、需要哪些版本，以及哪些内容不在覆盖范围内。
你需要什么
| 项目 | 版本 | 用途 |
|---|---|---|
| Node.js | 18 或更高（LTS）；Claude Code 插件需要 20.12 或更高 | 运行 zn-gate 和每个 hook。必须在你的 PATH 中 |
| Claude Code | 2.1.295 或更高；在 Windows 上建议 2.1.299 或更高 | 2.1.295 是使用插件的最低版本。2.1.299 见下文的已知限制 |
| Git for Windows | 任意较新版本 | 从 GitHub 添加 Claude Code 插件时需要。Claude Code 也用 Git Bash 运行 hook 命令 |
从 nodejs.org 安装 Node.js，打开新的终端并检查 node --version。Claude Code 的原生安装程序不包含 Node.js：没有它时，Claude Code 会在会话开始时提示找不到 node，提示词会被拦截，工具调用则不经检查直接运行。
在 PowerShell 中安装
请自己在普通的 PowerShell 窗口中运行，不带任何参数：
npx.cmd -y zn-gate init它会找到 Claude Code、Codex CLI、Cursor 和 OpenCode，显示每个智能体的设置，在你确认后执行每一步，最后进行检查。
如果 PowerShell 提示 "running scripts is disabled on this system"： 默认的执行策略会拦截 npm.ps1 和 npx.ps1。任选其一：
- 使用
.cmd版本：npm.cmd、npx.cmd和zn.cmd（例如npm.cmd install -g zn-gate）。 - 在命令提示符（Command Prompt）中运行这些命令。
- 仅为你的账户允许本地脚本：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。
对于 Claude Code，推荐使用插件：
claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn对于 Codex CLI、Cursor 或 OpenCode，先安装 zn-gate，再安装它的 hooks：
npm.cmd install -g zn-gate
zn.cmd hooks install codex # 或：cursor、opencode在 Git Bash 中安装
PowerShell 的执行策略不影响 Git Bash，所以命令与 macOS 和 Linux 相同：
npx -y zn-gate init一次一个智能体：npm install -g zn-gate，然后 zn hooks install codex（或 cursor、opencode）。
Python 包适用于你自己构建的智能体，安装在虚拟环境中。在 PowerShell 中：
python -m venv .venv
.venv\Scripts\pip install zn-gatezn 的文件存放位置
zn 把自己的状态保存在用户配置文件夹里的 .zn 文件夹中：%USERPROFILE%\.zn（例如 C:\Users\你的用户名\.zn）。设置环境变量 ZN_HOME 可以改用其他文件夹。
| 内容 | 位置 |
|---|---|
| 加密保险库（密钥与凭据） | %USERPROFILE%\.zn\vault\（secrets.age） |
| 保险库解锁期间的会话文件 | %USERPROFILE%\.zn\run\ |
| 保险库的本地审计日志 | %USERPROFILE%\.zn\audit.jsonl |
zn-gate evidence 读取的日志 |
%USERPROFILE%\.zn\evidence.jsonl |
| 可选的 hook 设置 | %USERPROFILE%\.zn\config.json |
保险库的密钥保存在 Windows 凭据管理器（Windows Credential Manager）中。没有系统密钥链时，zn 会改为请你输入口令（zn unlock --backend passphrase）。zn 在 Windows 上不设置 Unix 文件权限位：适用的是你的用户配置文件夹的权限。
各智能体保存 zn hooks install 所写配置的位置：
| 智能体 | 在 Windows 上 |
|---|---|
| Claude Code | %USERPROFILE%\.claude\settings.json（或 CLAUDE_CONFIG_DIR 指定的文件夹） |
| Codex CLI | %USERPROFILE%\.codex\hooks.json（或 CODEX_HOME 指定的文件夹） |
| Cursor | %USERPROFILE%\.cursor\hooks.json |
| OpenCode | %USERPROFILE%\.config\opencode 中的 plugins\zn-gate.js（或 XDG_CONFIG_HOME 下的文件夹） |
智能体不能读取或修改 %USERPROFILE%\.zn：zn 会拦截，即使命令写成 $env:USERPROFILE\.zn 或 %USERPROFILE%\.zn 也一样。
可能关闭 hooks 的组织策略文件位于 C:\Program Files\ClaudeCode（Claude Code）和 %ProgramData%\OpenAI\Codex（Codex）。zn-gate check 和 zn hooks install 会读取它们，并在其中某个文件让 zn 失效时告诉你。
hooks 在 Windows 上如何运行
每个 hook 都是一个短暂的 Node.js 进程：智能体启动 node，由它运行 zn-gate 的 hook 脚本，事件通过标准输入传入。
| 智能体 | hook 如何启动 |
|---|---|
| Claude Code，插件 | node 运行插件的启动器，启动器会先检查已固定版本的 zn-gate 文件 |
Claude Code，zn hooks install |
Claude Code 用 Git Bash 运行该命令（仅在未安装 Git Bash 时才用 PowerShell）。zn 把 node 的路径和 hook 脚本的路径用单引号括起来，并使用正斜杠，因此含空格或特殊字符的路径不会被解释 |
| Codex CLI | Windows 命令经过 cmd.exe，并以同样的 node 调用启动 powershell.exe -NoProfile -NonInteractive |
| Cursor | 在 Windows 上，Cursor 通常把命令包在 PowerShell 中。zn 写入同样的 powershell.exe 形式，cmd.exe、PowerShell 和 Git Bash 都以相同方式运行它 |
| OpenCode | 插件以参数列表启动 node，不经过 shell |
在我们的 CI 中，插件在 Windows 上使每次 hook 调用增加的耗时中位数为 51 到 90 毫秒，这是在不用插件时 hook 本身 42 到 92 毫秒之外的增量。
保险库的后台进程通过 Windows 命名管道与 hooks 通信（macOS 和 Linux 上是 Unix 套接字）。每个连接都必须证明自己知道保存在 %USERPROFILE%\.zn\run\ 中的会话密钥。保险库的确认对话框、凭据管理器和 zn secret set --clipboard 会启动系统自带的 Windows PowerShell 5.1，它通过系统本身定位，而不是通过智能体可能修改的 SystemRoot 变量。没有它时，对话框不会显示（审批会被拒绝），凭据管理器会报错并建议使用 zn unlock --backend passphrase。
用 zn run 运行命令
.cmd或.bat程序（例如用 npm 安装的命令行工具）只通过系统的cmd.exe启动。zn 会拒绝包含%、!或"的程序路径，因为cmd.exe会展开它们。- 批准一个
.cmd或.bat文件，批准的是这个文件本身，而不是它按名称启动的程序：npm 的垫片会运行PATH中找到的node。最好批准程序本身，或对网页 API 使用secrets_http_request工具。 - 程序按 Windows 的方式通过
PATHEXT查找：npm 安装会在claude.cmd旁放一个名为claude的脚本，zn 会选择 Windows 能运行的那个。 - 已经通过
zn-gate run -- ...运行且带有密钥占位符的 PowerShell 命令，hook 会原样放行。1.12.0 之前它会被拒绝。
已知限制
- WSL：未测试。 我们没有在 Windows Subsystem for Linux 中运行过 zn-gate，因此本页不涉及它。
- Claude Code 是我们在 Windows 上测试的途径，包括它的 PowerShell 工具。
- Codex CLI： 我们在 PowerShell 和
cmd.exe中手动运行过 hook 命令，它不属于我们的自动化测试。 - Cursor 和 OpenCode： 未在 Windows 上测试。对于 OpenCode，
zn run的包装是为 bash 编写的：当 OpenCode 的 shell 是 PowerShell 时，带密钥标记的命令会失败而不是运行（不会暴露任何值）。 zn-gate check： 在 Windows 上，它不会启动以zn hook <agent>形式安装的 hook，而是改为检查 zn 对该智能体的规则，并在输出中说明。- 2.1.299 之前的 Claude Code，且没有 Git for Windows： hook 无法运行时，
PreToolUse会放行调用。请更新 Claude Code 或安装 Git for Windows。 - 无法运行的 hook（例如缺少
node）会让 Claude Code 和 Codex 中的工具调用不经检查，并在 Claude Code 中拦截提示词。各智能体支持什么。 - 超过 100 KB 的 shell、PowerShell 或 Monitor 命令会被拦截，因为 zn 无法在智能体等待 hook 的时间内检查完。
确认它在工作
打开新的终端并运行：
npx.cmd -y zn-gate check对于你设置的每个智能体，它都应显示 OK。输出的含义。
延伸阅读
- 安装 zn-gate：所有智能体和一条命令完成设置。
- 把 .env 中的值存入加密保险库