zn-gate（本地）

配置

zn-gate 的环境变量、命令行参数和自定义规则。

查看 .md

zn-gate 无需任何配置即可运行。以下内容均为可选。

环境变量

变量 默认值 作用
ZN_CLOUD off 设为 1 后，提示词分析（analyze_prompt、zn-gate analyze、Python analyze()）还会请求云端模型给出第二意见。需要设置 ZN_API_KEY。
ZN_API_KEY unset 来自控制台的 API 密钥。未设置 ZN_CLOUD=1 时无效。
ZN_LOCAL_ONLY unset 设为 true 可强制仅本地运行，即使已设置 ZN_CLOUD=1。
ZN_STAGE v30 云端端点：v30（当前生产 API）或 prod（旧版端点）。
ZN_API_URL unset 覆盖云端端点 URL。优先级高于 ZN_STAGE。
ZN_VERBOSE unset 设置任意值即可将调试日志输出到 stderr。

npx -y zn-gate status 会输出当前使用的引擎以及你的配置会发送哪些数据。参见哪些数据会离开你的设备。

为单个 MCP 服务器开启云端

将变量添加到该服务器在你的代理配置中的条目里，例如 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "zn-gate": {
      "command": "npx",
      "args": ["-y", "zn-gate", "mcp"],
      "env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_your_key" }
    }
  }
}

命令行参数

参数 作用
--local-only 即使设置了 ZN_CLOUD=1，也不使用云端
--key <api_key> 可选云端功能的 API 密钥（与 ZN_API_KEY 相同；仍需设置 ZN_CLOUD=1）
--stage v30 或 --stage prod，--url <url> 选择云端端点
--shadow 用于 init 或 shield：仅记录检测结果，不拦截或修改流量
--all、--include .rst,.xml、--exclude fixtures 控制 scan 读取哪些文件
--verbose 将调试日志输出到 stderr

运行 npx -y zn-gate --help 查看所有选项。

自定义规则

在 Node.js 包中，可在 zn-gate 运行所在目录的 .znrules 或 zn.config.json 中为项目添加禁止的模式和禁止访问的路径：

# .znrules
path:.env.production
path:/etc/secrets
CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

以 path: 开头的行会阻止包含该路径的任何输入。其他行是不区分大小写的正则表达式，会阻止与其匹配的任何输入。以 # 开头的行为注释。JSON 格式如下：

{ "bannedPatterns": ["CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+"], "forbiddenPaths": [".env.production", "/etc/secrets"] }

由自定义规则触发的拦截会报告 custom:banned_pattern 或 custom:forbidden_path。Python 包不读取这些文件。

zn-gate 写入的文件

文件 说明
~/.zn/evidence.jsonl shield 决策的本地审计日志（详情）
<config>.bak.<timestamp> init 修改的每个代理配置的备份；init --revert 可恢复最新的备份