配置权限

使用细粒度权限规则、模式和托管策略来控制 Claude Code 可以访问和执行的操作。

权限系统

Claude Code 使用分层权限系统来平衡功能和安全性：

工具类型	示例	需要批准	“是，不再询问”行为
只读	文件读取、Grep	否	不适用
Bash 命令	Shell 执行	是	每个项目目录和命令永久有效
文件修改	Edit/Write 文件	是	直到会话结束

管理权限

使用 /permissions 查看和管理 Claude Code 的工具权限：

• Allow 规则让 Claude Code 使用指定的工具而无需手动批准
• Ask 规则在 Claude Code 尝试使用指定工具时提示确认
• Deny 规则防止 Claude Code 使用指定的工具

规则按顺序评估：deny -> ask -> allow。第一个匹配的规则获胜，deny 规则始终优先。

权限模式

模式	描述
default	标准行为：在首次使用每个工具时提示权限
acceptEdits	自动接受会话的文件编辑权限
plan	Plan Mode：Claude 可以分析但不能修改文件
dontAsk	自动拒绝工具，除非预先批准
bypassPermissions	跳过所有权限提示

警告：bypassPermissions 模式仅在隔离环境（如容器或虚拟机）中使用。

权限规则语法

匹配工具的所有使用

规则	效果
Bash	匹配所有 Bash 命令
WebFetch	匹配所有网络获取请求
Read	匹配所有文件读取

使用说明符进行细粒度控制

规则	效果
Bash(npm run build)	匹配确切的命令
Read(./.env)	匹配读取 .env 文件
WebFetch(domain:example.com)	匹配对 example.com 的获取请求

通配符模式

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

工具特定的权限规则

Bash

Bash 规则支持带有 * 的通配符匹配：

• Bash(npm run build) - 匹配确切的命令
• Bash(npm run test *) - 匹配以 npm run test 开头的命令
• Bash(npm *) - 匹配任何以 npm 开头的命令
• Bash(* install) - 匹配任何以 install 结尾的命令

提示：Claude Code 知道 shell 运算符（如 &&），因此前缀匹配规则不会给它权限运行组合命令。

Read 和 Edit

Read 和 Edit 规则支持四种路径类型：

模式	含义	示例
//path	绝对路径	Read(//Users/alice/secrets/**)
~/path	主目录路径	Read(~/.zshrc)
/path	相对项目根目录	Edit(/src/**/*.ts)
path 或 ./path	相对当前目录	Read(*.env)

注意：像 /Users/alice/file 这样的模式不是绝对路径，它相对于项目根目录。对于绝对路径，请使用 //Users/alice/file。

WebFetch

• WebFetch(domain:example.com) - 匹配对 example.com 的获取请求

MCP

• mcp__puppeteer - 匹配由 puppeteer 服务器提供的任何工具
• mcp__puppeteer__* - 通配符语法，匹配所有工具
• mcp__puppeteer__puppeteer_navigate - 匹配特定工具

Agent（subagents）

使用 Agent(AgentName) 规则来控制 Claude 可以使用哪些 subagents：

• Agent(Explore) - 匹配 Explore subagent
• Agent(Plan) - 匹配 Plan subagent
• Agent(my-custom-agent) - 匹配自定义 subagent

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

使用 hooks 扩展权限

PreToolUse hooks 在权限系统之前运行，可以确定是否批准或拒绝工具调用。

工作目录

默认情况下，Claude 可以访问启动它的目录中的文件。扩展访问：

• 启动期间：使用 --add-dir <path> CLI 参数
• 会话期间：使用 /add-dir 命令
• 持久配置：添加到设置文件中的 additionalDirectories

权限与沙箱交互

• 权限控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域
• 沙箱提供 OS 级别的强制执行，限制 Bash 工具的文件系统和网络访问

使用两者进行深度防御。

托管设置

对于组织部署，管理员可以部署托管设置：

仅托管设置

设置	描述
disableBypassPermissionsMode	防止 bypassPermissions 模式
allowManagedPermissionRulesOnly	仅允许托管权限规则
allowManagedHooksOnly	仅允许托管 hooks
allowManagedMcpServersOnly	仅允许托管 MCP servers
blockedMarketplaces	被阻止的插件市场
sandbox.network.allowManagedDomainsOnly	仅允许托管域
allow_remote_sessions	允许或阻止远程会话

设置优先级

权限规则遵循设置优先级：托管设置具有最高优先级，其次是命令行参数、本地项目、共享项目和用户设置。

如果权限在用户设置中被允许但在项目设置中被拒绝，项目设置优先。

示例配置

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Read(/src/**/*.ts)",
      "Edit(/src/**/*.ts)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Write(*.env)"
    ]
  }
}

---

本文档来自 Claude Code 官方文档