AI Agent / 系统课时
配置工具允许与拒绝规则
配置工具允许与拒绝规则
权限规则决定 Claude Code 能否读取文件、修改内容、执行命令或调用外部工具。本课将建立一套可落地的最小权限配置,并通过规则匹配顺序避免“允许得过宽”或“拒绝后仍以为能例外放行”。
学习目标
- 掌握
allow、ask、deny三类规则的作用 - 能为文件、命令、网络和 MCP 工具编写精确规则
- 理解拒绝优先于询问、询问优先于允许
权限判定的核心顺序
规则按照 deny、ask、allow 的顺序求值,先匹配者决定结果,规则是否更具体不会改变这个顺序。一个宽泛的拒绝不能通过更窄的允许规则创建例外;同样,只要 ask 命中,即使另有 allow,仍会要求人工确认。:contentReference[oaicite:3]{index=3}

权限规则基本形式是 Tool 或 Tool(specifier)。只写工具名会匹配该工具的所有调用;带限定符则缩小到命令、路径、域名或具体 MCP 工具。:contentReference[oaicite:4]{index=4}
编写一组最小权限规则
下面的项目配置允许读取源码、运行测试和查看 Git 状态;推送代码必须确认;密钥、生产部署命令和未批准的外部下载被拒绝。
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Read(./src/**)",
"Read(./tests/**)",
"Edit(./src/**)",
"Edit(./tests/**)",
"Bash(npm test)",
"Bash(git status *)",
"WebFetch(domain:docs.example.com)"
],
"ask": [
"Bash(git push *)",
"Bash(npm install *)",
"mcp__github__create_pull_request"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Edit(./.github/workflows/**)",
"Bash(curl *)",
"Bash(wget *)",
"Bash(npm run deploy *)"
]
}
}保存后用 /permissions 查看每条规则及其来源。注意示例中的部署拒绝只是演示模式匹配;实际项目应依据真实命令写成可验证的精确前缀,避免依赖含糊的自然语言。
常见工具的规则写法
Read(./.env) 针对当前目录的单个文件,Read(./secrets/**) 针对目录及其后代。Bash(npm run test *) 匹配以该前缀开始的命令,空格会形成命令边界;WebFetch(domain:*.example.com) 匹配子域名,但不自动包含根域名。MCP 工具使用 mcp__服务器名__工具名,例如 mcp__github__get_issue。:contentReference[oaicite:5]{index=5}
不要把 Bash 整体加入允许列表,除非环境已经被操作系统级沙箱隔离。Bash 模式只能匹配 Claude Code 看到的命令文本,不能替代容器、文件系统权限和网络策略。任意脚本解释器都可能间接读取文件,因此敏感边界需要与沙箱结合。
验证规则是否按预期生效
先启动 Claude Code,再打开权限面板检查来源和匹配项。
claude预期结果
Claude Code 会话启动,输入 /permissions 可查看当前权限规则。随后分别请求“运行 npm test”“执行 git push”和“读取 .env”。预期行为是测试直接执行、推送弹出确认、密钥读取被阻止。这里验证的是权限结果,不应使用真实生产推送或真实密钥做测试。
三类容易写错的规则
第一,使用宽泛拒绝再期待允许例外,例如拒绝 Bash(git *) 又允许 Bash(git status);拒绝优先,所以状态命令仍被阻止。第二,把团队机器路径写入共享项目设置,导致其他成员无法匹配。第三,只在提示词中说“不要读取密钥”,却没有权限规则;提示词影响模型选择,权限规则才是执行边界。