Claude Code 的权限系统通过 Allow/Ask/Deny 三种规则按 deny→ask→allow 顺序求值，精确控制 AI 可访问的文件、命令和网络范围。配置方式包括在 settings.json 中编写规则、使用 /permissions 命令交互，或通过 PreToolUse Hook 扩展权限。权限模式（plan、acceptEdits、auto 等）通过 defaultMode 设置；企业级托管设置可禁止用户覆盖关键策略，沙箱提供 OS 级隔离作为纵深防御。规则不阻止 Bash 子进程的间接文件访问（如 cat .env），需要完整保护请启用沙箱。

Claude Code 权限配置：Allow/Ask/Deny 规则与权限模式 #

Claude Code 支持细粒度权限，你可以精确指定 AI 可以做什么、不能做什么。权限设置可以提交到版本仓库分发给整个团队，也可以由个人开发者自定义。

权限系统分层 #

管理权限 #

运行 /permissions 可以查看和管理所有工具权限。界面显示所有规则及其来源的 settings.json 文件。

• Allow 规则：Claude Code 使用指定工具时无需手动确认。
• Ask 规则：每次使用前弹出确认。
• Deny 规则：完全阻止使用。

规则按 deny → ask → allow 顺序求值，第一个匹配的规则生效，因此 deny 优先级最高。

权限规则由 Claude Code（而非模型）强制执行。你在提示词或 CLAUDE.md 中的指令影响 Claude 尝试做什么，但不改变 Claude Code 允许什么。要授予或撤销权限，请使用 /permissions、本页描述的规则、权限模式 或 PreToolUse Hook。

权限模式 #

在 settings 文件 中设置 defaultMode：

bypassPermissions 模式跳过所有权限提示，包括对 .git、.claude、.vscode、.idea、.husky 的写操作。针对文件系统根目录或家目录的删除（如 rm -rf /、rm -rf ~）仍会提示作为模型错误的断路器。仅在容器或虚拟机等隔离环境中使用此模式。管理员可通过在 托管设置 中将 permissions.disableBypassPermissionsMode 设为 "disable" 来禁止此模式。

要禁止使用 bypassPermissions 或 auto 模式，在任何 settings 文件 中将 permissions.disableBypassPermissionsMode 或 permissions.disableAutoMode 设为 "disable"。这在 托管设置 中最有用，因为无法被覆盖。

权限规则语法 #

规则格式为 工具名 或 工具名(指定器)。

匹配工具的所有用法 #

仅使用工具名不加括号：

Bash(*) 等同于 Bash，匹配所有 Bash 命令。作为 deny 规则时，两种形式都会将工具从 Claude 的上下文中移除。

精细匹配 #

在括号中添加指定器匹配具体用法：

通配符模式 #

Bash 规则支持 * 通配符，可出现在命令任意位置。此配置允许 npm 和 git commit 命令，同时阻止 git push：

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

* 前的空格有影响：Bash(ls *) 匹配 ls -la 但不匹配 lsof；Bash(ls*) 两者都匹配。:* 后缀是尾随通配符的等价写法，Bash(ls:*) 与 Bash(ls *) 匹配相同命令。:* 形式仅在模式末尾识别，如 Bash(git:* push) 中的冒号被视为字面字符。

工具特定规则 #

Bash #

通配符可出现在任意位置：

• Bash(npm run build) 精确匹配 npm run build
• Bash(npm run test *) 匹配以 npm run test 开头的命令
• Bash(npm *) 匹配以 npm 开头的命令
• Bash(* install) 匹配以 install 结尾的命令
• Bash(git * main) 匹配 git checkout main、git log --oneline main 等

单个 * 匹配任意字符（包括空格），因此 Bash(git *) 匹配 git log --oneline --all，Bash(git * main) 匹配 git push origin main 和 git merge main。

* 末尾有空格时（如 Bash(ls *)）施加词边界，要求前缀后跟空格或字符串结束；Bash(ls*) 无空格则无词边界约束。

复合命令 #

Claude Code 能识别 Shell 运算符，因此 Bash(safe-cmd *) 不会给予它运行 safe-cmd && other-cmd 的权限。识别的命令分隔符包括 &&、||、;、|、|&、& 和换行符。规则必须独立匹配每个子命令。

当批准一个带“以后不再询问”的复合命令时，Claude Code 会为每个需要审批的子命令单独保存一条规则，而非整个复合字符串。例如批准 git status && npm test 会为 npm test 保存规则。一个复合命令最多保存 5 条规则。

进程包装器 #

匹配 Bash 规则前，Claude Code 会剥离一组固定的进程包装器，因此 Bash(npm test *) 也能匹配 timeout 30 npm test。识别的包装器：timeout、time、nice、nohup、stdbuf。裸 xargs 也会被剥离，所以 Bash(grep *) 匹配 xargs grep pattern（仅当 xargs 无参数时）。

此包装器列表内置不可配置。像 direnv exec、devbox run、mise exec、npx、docker exec 不在列表中，因此 Bash(devbox run *) 会匹配其后任何命令（包括 devbox run rm -rf .）。允许环境内部的命令时，写包含内外命令的规则，如 Bash(devbox run npm test)。

watch、setsid、ionice、flock 等执行包装器总是会提示，不能通过 Bash(watch *) 自动批准。find 配合 -exec 或 -delete 同理，Bash(find *) 不覆盖此类形式。

只读命令 #

Claude Code 识别一组内置的只读 Bash 命令，在所有模式下运行时不提示，包括 ls、cat、echo、pwd、head、tail、grep、find、wc、which、diff、stat、du、cd 以及只读形式的 git。此集合不可配置；要要求这些命令提示，请添加 ask 或 deny 规则。

所有标志都是只读的命令允许未加引号的 glob 模式，如 ls *.ts、wc -l src/*.py 不提示。可能包含写或执行标志的命令（如 find、sort、sed、git）在未加引号的 glob 时会提示，因为 glob 可能展开为 -delete 等标志。

cd 到工作目录或 额外目录 内的路径也是只读的。复合命令 cd packages/api && ls 在每个部分单独符合条件时不提示。cd 与 git 在一个复合命令中时总是会提示。

Bash 权限模式尝试约束命令参数很脆弱。例如 Bash(curl http://github.com/ *) 想限制 curl 仅为 GitHub URL，但无法匹配变体：选项在 URL 前、不同协议、重定向、变量、多余空格等。更可靠的 URL 过滤方案：

• 用 deny 规则阻断 curl、wget 等，再通过 WebFetch(domain:github.com) 允许授权域名
• 使用 PreToolUse Hook 验证 URL 并阻止不允许的域名
• 在 CLAUDE.md 中描述允许的 curl 模式（仅影响尝试，不强制边界，需配合前两种方案）

仅使用 WebFetch 并不能阻止网络访问。如果允许 Bash，Claude 仍可使用 curl、wget 等工具访问任何 URL。

PowerShell #

PowerShell 规则形状与 Bash 相同。通配符 * 可在任何位置匹配，:* 后缀等价于尾随 *，裸 PowerShell 或 PowerShell(*) 匹配所有命令。此配置允许 Get-ChildItem 和 git commit 命令，阻止 Remove-Item：

{
  "permissions": {
    "allow": [ "PowerShell(Get-ChildItem *)", "PowerShell(git commit *)" ],
    "deny": [ "PowerShell(Remove-Item *)" ]
  }
}

常见别名在被匹配前会规范化为命令名称。为 cmdlet 名称写的规则也会匹配其别名，因此 PowerShell(Get-ChildItem *) 也匹配 gci、ls、dir。匹配不区分大小写。

Claude Code 会解析 PowerShell AST，独立检查复合命令中的每个命令。管道运算符 |、语句分隔符 ; 以及 PowerShell 7+ 的链运算符 && 和 || 将复合命令拆分为子命令。规则必须匹配所有子命令才能允许。

Read 和 Edit #

Edit 规则适用于所有内置文件编辑工具。Claude 会尽力将 Read 规则应用到所有内置文件读取工具（如 Grep、Glob）、提示中的 @file 引用，以及连接的 IDE 共享的选中和打开文件上下文。

Read 和 Edit deny 规则适用于 Claude 的内置文件工具以及 Claude Code 在 Bash 中识别的文件命令（如 cat、head、tail、sed）。它们不适用于间接读写文件的任意子进程，例如自行打开文件的 Python 或 Node 脚本。需要 OS 级别阻止所有进程访问路径时，请 启用沙箱。

Read 和 Edit 规则遵循 gitignore 规范，支持四种路径模式：

模式 /Users/alice/file 不是绝对路径，它相对于项目根。使用 //Users/alice/file 表示绝对路径。

Windows 上路径在匹配前被规范化为 POSIX 形式。C:\Users\alice 变为 /c/Users/alice，因此使用 //c/**/.env 匹配该驱动器上的任何 .env 文件。要跨所有驱动器匹配，使用 //**/.env。

示例：

• Edit(/docs/**)：匹配 <项目>/docs/ 内的编辑（并非 /docs/，也非 <项目>/.claude/docs/）
• Read(~/.zshrc)：读取家目录的 .zshrc
• Edit(//tmp/scratch.txt)：编辑绝对路径 /tmp/scratch.txt
• Read(src/**)：从 <当前目录>/src/ 读取

规则仅在其锚定范围内匹配叶子，因此锚定决定 deny 规则的影响范围。裸文件名遵循 gitignore 语义，在任何深度都匹配，故 Read(.env) 和 Read(**/.env) 等价：

gitignore 模式中，* 匹配单个目录内的文件，** 递归跨目录匹配。要允许所有文件访问，直接使用工具名不加括号：Read、Edit、Write。

当 Claude 访问符号链接时，权限规则检查两条路径：链接本身及其解析目标。Allow 和 deny 规则处理这对路径不同：

• Allow 规则：仅当链接路径和其目标都匹配时才适用。链接在允许目录内但指向外部仍会提示。
• Deny 规则：当链接路径或目标之一匹配时即适用。指向被拒绝文件的链接本身也被拒绝。

例如，Read(./project/**) 允许且 Read(~/.ssh/**) 拒绝，./project/key 指向 ~/.ssh/id_rsa 的链接会被阻止：目标不满足 allow 规则且匹配 deny 规则。

WebFetch #

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

MCP #

• mcp__puppeteer 匹配 puppeteer 服务器提供的任何工具（服务器名在 Claude Code 中配置）
• mcp__puppeteer__* 通配符语法，也匹配 puppeteer 服务器的所有工具
• mcp__puppeteer__puppeteer_navigate 匹配 puppeteer 服务器提供的 puppeteer_navigate 工具

子代理（Agent） #

使用 Agent(AgentName) 规则控制 Claude 可以使用的 子代理：

• Agent(Explore) 匹配 Explore 子代理
• Agent(Plan) 匹配 Plan 子代理
• Agent(my-custom-agent) 匹配名为 my-custom-agent 的自定义子代理

将规则添加到设置中的 deny 数组或使用 --disallowedTools CLI 标志来禁用特定代理。禁用 Explore 代理：

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

通过 Hooks 扩展权限 #

Claude Code Hooks 提供注册自定义 Shell 命令以在运行时执行权限评估的方式。工具调用时，PreToolUse Hook 在权限提示前运行。Hook 输出可以拒绝工具调用、强制提示或跳过提示。

Hook 的决策不会绕过权限规则。deny 和 ask 规则无论 PreToolUse Hook 返回什么都会被评估，因此匹配的 deny 规则会阻止调用，匹配的 ask 规则仍会提示（即使 Hook 返回了 "allow" 或 "ask"）。这保持了 管理权限 中描述的 deny 优先顺序，包括托管设置中的 deny 规则。

阻止型 Hook（退出码 2）的优先级也高于 allow 规则。退出码 2 的 Hook 在权限规则评估前停止工具调用，即使 allow 规则允许调用也会被阻止。要允许所有 Bash 命令不提示但阻止少数命令，将 "Bash" 添加到 allow 列表并注册一个拒绝特定命令的 PreToolUse Hook。参见 阻止对受保护文件的编辑 了解可改编的 Hook 脚本。

工作目录 #

默认 Claude 只能访问启动时的目录。可以扩展访问：

• 启动时：使用 --add-dir <path> CLI 参数
• 会话中：使用 /add-dir 命令
• 持久配置：在 settings 文件 中添加 additionalDirectories

额外目录中的文件遵循与原始工作目录相同的权限规则：可无提示读取，文件编辑权限受当前权限模式控制。

额外目录提供文件访问，而非配置 #

添加目录扩展了 Claude 读写文件的范围，但不会使其成为完整配置根：大多数 .claude/ 配置不会从额外目录发现，只有少数例外。

从 --add-dir 目录加载的配置：

子代理、命令和输出样式从当前工作目录及其父目录、用户目录 ~/.claude/ 以及托管设置中发现。Hooks 和其他 settings.json 键从当前工作目录的 .claude/ 文件夹加载（无父目录回退），同时从用户 ~/.claude/settings.json 和托管设置加载。要在项目间共享此类配置，使用以下方法之一：

• 用户级别配置：将文件放在 ~/.claude/agents/、~/.claude/output-styles/ 或 ~/.claude/settings.json 中以在每个项目中可用
• 插件：将配置打包为 插件 供团队安装
• 从配置目录启动：从包含 .claude/ 配置的目录运行 Claude Code

权限与沙箱的交互 #

权限和 沙箱 是互补的安全层：

• 权限：控制 Claude Code 可以使用哪些工具以及访问哪些文件或域名，适用于所有工具（Bash、Read、Edit、WebFetch、MCP 等）
• 沙箱：提供 OS 级别执行，限制 Bash 工具的文件系统和网络访问，仅适用于 Bash 命令及其子进程

同时使用实现纵深防御：

• 权限 deny 规则阻止 Claude 尝试访问受限资源
• 沙箱限制即使通过提示注入绕过了 Claude 的决策，也能阻止 Bash 命令访问边界外的资源
• 沙箱中的文件系统限制结合了 sandbox.filesystem 设置与 Read 和 Edit deny 规则，全部合并到最终沙箱边界
• 网络限制结合 WebFetch 权限规则与沙箱的 allowedDomains 和 deniedDomains 列表

当沙箱启用且 autoAllowBashIfSandboxed: true（默认）时，沙箱内的 Bash 命令即使权限包含 ask: Bash(*) 也不提示。沙箱边界替代了逐命令提示。明确的 deny 规则仍然适用，针对 /、家目录或其他关键系统路径的 rm 或 rmdir 命令仍会触发提示。参见 沙箱模式 更改此行为。

托管设置（Managed Settings） #

对于需要集中控制 Claude Code 配置的组织，管理员可以部署用户或项目设置无法覆盖的托管设置。这些策略设置遵循与常规 settings 文件相同的格式，可通过 MDM/OS 级别策略、托管设置文件或 服务器托管设置 交付。参见 settings 文件 了解交付机制和文件位置。

仅托管设置中生效的设置 #

以下设置仅从托管设置中读取。放在用户或项目设置中无效。

disableBypassPermissionsMode 通常放在托管设置中以执行组织策略，但可在任何范围生效。用户可在自己的设置中设置它以锁定自己。

在 Team 和 Enterprise 计划中，管理员在 Claude Code 管理设置 中组织级启用或禁用 Remote Control 和 web sessions。Remote Control 还可通过 disableRemoteControl 托管设置按设备禁用。Web sessions 没有按设备的托管设置键。

设置优先级 #

权限规则遵循与其他所有设置相同的 设置优先级：

1. 托管设置（最高）——无法被任何其他级别覆盖，包括命令行参数
2. 命令行参数——临时会话覆盖
3. 本地项目设置（.claude/settings.local.json）
4. 共享项目设置（.claude/settings.json）
5. 用户设置（~/.claude/settings.json，最低）

如果某个工具在任何级别被 deny，其他级别无法 allow 它。例如，托管设置的 deny 无法被 --allowedTools 覆盖，而 --disallowedTools 可以在托管设置定义的基础上增加限制。

嵌入宿主可以通过 SDK 的 managedSettings 选项提供额外的托管策略（当 parentSettingsBehavior 设置为 "merge" 时）；嵌入者的值可以收紧策略但不能松弛。

例如，用户设置 allow 某权限但项目设置 deny 了它，则 deny 规则阻止它。反之亦然：用户级 deny 阻止项目级 allow，因为来自任何范围的 deny 规则都在 allow 之前求值。

示例配置 #

此 仓库 包含常见部署场景的入门设置配置。可作为起点，根据需求调整。

参见 #

• 设置：完整配置参考，包含权限设置表
• 配置 auto 模式：告知 auto 模式分类器你的组织信任哪些基础设施
• 沙箱：Bash 命令的 OS 级文件系统和网络隔离
• 认证：为用户设置访问 Claude Code
• 安全：安全防护措施和最佳实践
• Hooks：自动化工作流和扩展权限评估

常见问题 #

Claude Code 权限配置不生效/规则没起作用怎么办？ #

检查设置优先级：托管设置 > 命令行参数 > 本地项目设置 > 共享项目设置 > 用户设置。同一工具在任何级别被 deny 就无法在其他级别 allow。使用 /permissions 命令查看最终生效的规则列表。另外确认规则语法是否正确，例如 Bash 命令是否包含空格或通配符不符合预期。

如何阻止 Claude 访问 .env 或 secrets/ 里的敏感文件？ #

在权限规则中添加 deny: ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]。注意 Read/Edit 规则只阻止 Claude 的内置文件工具，不阻止 Bash 中的 cat .env。要彻底阻止所有进程访问，需要结合沙箱的 filesystem.denyRead 设置。同时建议在 CLAUDE.md 中说明敏感文件位置指导 Claude 避开。

bypassPermissions 模式有什么风险，如何禁用？ #

此模式跳过所有权限提示（包括对 .git、.claude、.vscode 等目录的写操作），仅保留根目录和家目录删除的断路器提示。风险极大，应仅在完全隔离的容器或虚拟机中使用。企业管理员可在托管设置中将 permissions.disableBypassPermissionsMode 设为 "disable" 来强制禁止此模式，用户无法自行覆盖。