权限规则与路径匹配

配置 deny、ask、allow，正确区分工具别名、路径根与 shell 检查。

This page has not been translated into English yet. The original Chinese version is shown below.

权限规则决定调用是否阻止、询问或自动批准。判断优先级为 deny → ask → allow → 当前模式默认行为，按匹配规则处理。

最小配置

{
  "permissions": {
    "allow": ["Bash(git status)", "Read(./docs/**)"],
    "ask": ["Bash(git push *)", "Edit"],
    "deny": ["Read(./.env)"]
  }
}

allow 是自动批准，不是允许注册的工具白名单；ask 也不影响注册。用户、项目与系统 allow 会合并，Auto 还会暂存过宽规则，见Auto 模式。

工具名称

规则形状为 ToolName 或 ToolName(specifier)。常用别名包括 Bash/Shell → run_shell_command、Write/WriteFile → write_file、Grep/SearchFiles → grep_search、Glob/FindFiles → glob、ListFiles → list_directory、WebFetch → web_fetch、Agent → task、Skill → skill，以及 NotebookEdit/NotebookEditTool → notebook_edit。

Read 与 Edit 还是元类别：Read 同时覆盖 read_file、grep_search、glob、list_directory；Edit 同时覆盖 edit、write_file、notebook_edit。只限制文件读取时用 ReadFile 或 read_file，不能用 Read 却假定搜索不受影响。

路径前缀

前缀	含义	示例
//	文件系统绝对根	//etc/passwd
~/	用户 home	~/Documents/*.pdf
/	项目根	/src/*/.ts
./	当前工作目录	./secrets/**
无前缀	等同 ./	secrets/**

规则中的 /src/ 指项目目录，不能按普通 shell 绝对路径理解。

Bash(git *) 按词边界匹配 git 命令，不匹配 gitk；WebFetch(api.example.com) 覆盖该域名及子域名。mcp__puppeteer 可表示该 MCP 服务的全部工具。

Shell 中的等价操作

Read、Edit、WebFetch 规则也会检查支持的等价 shell 操作。例如禁止 Read(./.env) 时，不能通过 cat .env 绕过。

官方列出 cat、grep、curl、wget、cp、mv、rm、chmod 等支持项，同时说明未知或特定安全命令如 git 不受相同文件/网络规则分析。不要把这套识别等同于完整文件系统沙箱；需要执行边界时配置沙箱。

阻止与隐藏

无 specifier 的整个工具 deny 会从 registry 移除内置和 discoveryCommand 发现的工具。MCP 是例外：deny 仍在运行时阻止，工具可以继续显示；要隐藏使用 tools.disabled 或服务 excludeTools。

/tools 用于检查工具集合，/permissions 可交互查看、添加或移除规则。Auto 暂存的过宽 allow 在退出 Auto 后会恢复，中途移除未必修改暂存副本；需要检查重启后的实际配置。