配置权限

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

Claude Code 支持细粒度权限，因此您可以精确指定代理允许执行的操作和不允许执行的操作。权限设置可以检入版本控制并分发给组织中的所有开发人员，也可以由个别开发人员自定义。

权限系统

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

管理权限

您可以使用 /permissions 查看和管理 Claude Code 的工具权限。此 UI 列出所有权限规则和它们来自的 settings.json 文件。

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

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

权限模式

Claude Code 支持多种权限模式来控制工具的批准方式。请参阅权限模式了解何时使用每种模式。在您的设置文件中设置 defaultMode：

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

权限规则语法

权限规则遵循格式 Tool 或 Tool(specifier)。

匹配工具的所有使用

要匹配工具的所有使用，只需使用工具名称而不带括号：

Bash(*) 等同于 Bash 并匹配所有 Bash 命令。

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

在括号中添加说明符以匹配特定的工具使用：

通配符模式

Bash 规则支持带有 * 的 glob 模式。通配符可以出现在命令中的任何位置。此配置允许 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) 这样的模式中，冒号被视为文字字符，不会匹配 git 命令。

工具特定的权限规则

Bash

Bash 权限规则支持带有 * 的通配符匹配。通配符可以出现在命令中的任何位置，包括开头、中间或结尾：

• Bash(npm run build) 匹配确切的 Bash 命令 npm run build
• Bash(npm run test *) 匹配以 npm run test 开头的 Bash 命令
• 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 *) 匹配 ls -la 但不匹配 lsof。相比之下，Bash(ls*) 没有空格匹配 ls -la 和 lsof 两者，因为没有单词边界约束。

复合命令

当您使用"是，不再询问"批准复合命令时，Claude Code 会为需要批准的每个子命令保存一个单独的规则，而不是为完整的复合字符串保存单个规则。例如，批准 git status && npm test 会为 npm test 保存一个规则，因此将来的 npm test 调用被识别，无论 && 前面是什么。诸如 cd 进入子目录之类的子命令会为该路径生成自己的 Read 规则。单个复合命令最多可能保存 5 个规则。

进程包装器

在匹配 Bash 规则之前，Claude Code 会剥离一组固定的进程包装器，因此像 Bash(npm test *) 这样的规则也匹配 timeout 30 npm test。识别的包装器是 timeout、time、nice、nohup 和 stdbuf。

裸 xargs 也被剥离，所以 Bash(grep *) 匹配 xargs grep pattern。剥离仅在 xargs 没有标志时适用：像 xargs -n1 grep pattern 这样的调用被匹配为 xargs 命令，因此为内部命令编写的规则不涵盖它。

此包装器列表是内置的，不可配置。开发环境运行器，如 direnv exec、devbox run、mise exec、npx 和 docker exec 不在列表中。因为这些工具将其参数作为命令执行，像 Bash(devbox run *) 这样的规则匹配 run 之后的任何内容，包括 devbox run rm -rf .。要批准环境运行器内的工作，请编写一个包含运行器和内部命令的特定规则，如 Bash(devbox run npm test)。为您想要允许的每个内部命令添加一个规则。

Exec 包装器，如 watch、setsid、ionice 和 flock 总是提示，无法通过像 Bash(watch *) 这样的前缀规则自动批准。同样适用于带有 -exec 或 -delete 的 find：Bash(find *) 规则不涵盖这些形式。要批准特定调用，请为完整命令字符串编写精确匹配规则。

只读命令

Claude Code 将一组内置 Bash 命令识别为只读，并在每种模式下无需权限提示即可运行它们。这些包括 ls、cat、head、tail、grep、find、wc、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 总是提示，无论目标目录如何。

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。

Read 和 Edit 规则都遵循 gitignore 规范，具有四种不同的模式类型：

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

示例：

• Edit(/docs/**)：编辑 <project>/docs/ 中的文件（不是 /docs/ 也不是 <project>/.claude/docs/）
• Read(~/.zshrc)：读取您主目录的 .zshrc
• Edit(//tmp/scratch.txt)：编辑绝对路径 /tmp/scratch.txt
• Read(src/**)：从 <current-directory>/src/ 读取

一个规则只匹配其锚点下的文件，因此锚点决定了 deny 规则的范围。裸文件名遵循 gitignore 语义并在任何深度匹配，因此 Read(.env) 和 Read(**/.env) 是等价的：

当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：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（subagents）

使用 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 命令以在运行时执行权限评估。当 Claude Code 进行工具调用时，PreToolUse hooks 在权限提示之前运行。hook 输出可以拒绝工具调用、强制提示或跳过提示以让调用继续。

Hook 决定不会绕过权限规则。Deny 和 ask 规则在 hook 返回 "allow" 或 "ask" 后仍然被评估，因此匹配的 deny 规则仍然会阻止调用，匹配的 ask 规则即使在 hook 返回 "allow" 或 "ask" 时仍然提示。这保留了管理权限中描述的 deny 优先级，包括在托管设置中设置的 deny 规则。

阻止 hook 也优先于 allow 规则。以退出代码 2 退出的 hook 在权限规则被评估之前停止工具调用，因此即使 allow 规则会让调用继续，阻止也适用。要运行所有 Bash 命令而无需提示，除了您想要阻止的少数几个，将 "Bash" 添加到您的 allow 列表，并注册一个 PreToolUse hook 来拒绝那些特定命令。请参见阻止对受保护文件的编辑以获取您可以调整的 hook 脚本。

工作目录

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

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

其他目录中的文件遵循与原始工作目录相同的权限规则：它们变为可读的而无需提示，文件编辑权限遵循当前权限模式。

其他目录授予文件访问权限，而不是配置

添加目录扩展 Claude 可以读取和编辑文件的位置。它不会使该目录成为完整的配置根目录：大多数 .claude/ 配置不是从其他目录发现的，尽管有几种类型作为例外被加载。

以下配置类型从 --add-dir 目录加载：

其他所有内容，包括子代理、命令、输出样式、hooks 和其他设置，仅从当前工作目录及其父目录、您在 ~/.claude/ 的用户目录和托管设置中发现。要在项目间共享该配置，请使用以下方法之一：

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

权限如何与沙箱交互

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

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

使用两者进行深度防御：

• 权限 deny 规则阻止 Claude 甚至尝试访问受限资源
• 沙箱限制防止 Bash 命令到达定义边界之外的资源，即使提示注入绕过 Claude 的决策制定
• 沙箱中的文件系统限制结合 sandbox.filesystem 设置与 Read 和 Edit deny 规则；两者都合并到最终的沙箱边界中
• 网络限制结合 WebFetch 权限规则与沙箱的 allowedDomains 和 deniedDomains 列表

当沙箱启用 autoAllowBashIfSandboxed: true（这是默认值）时，沙箱化的 Bash 命令无需提示即可运行，即使您的权限包括 ask: Bash(*)。沙箱边界替代了每个命令的提示。显式 deny 规则仍然适用，针对 /、您的主目录或其他关键系统路径的 rm 或 rmdir 命令仍然会触发提示。请参见沙箱模式以更改此行为。

托管设置

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

仅托管设置

以下设置仅在托管设置中有效。将它们放在用户或项目设置文件中无效。

disableBypassPermissionsMode 通常放在托管设置中以强制执行组织策略，但它可以从任何范围工作。用户可以在自己的设置中设置它以将自己锁定在绕过模式之外。

设置优先级

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

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

如果工具在任何级别被拒绝，没有其他级别可以允许它。例如，托管设置 deny 无法被 --allowedTools 覆盖，--disallowedTools 可以添加超出托管设置定义的限制。

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

示例配置

此存储库包括常见部署场景的启动设置配置。将这些用作起点并根据您的需要调整它们。

另请参见

• Settings：完整的配置参考，包括权限设置表
• Configure auto mode：告诉自动模式分类器您的组织信任哪些基础设施
• Sandboxing：Bash 命令的 OS 级文件系统和网络隔离
• Authentication：设置用户对 Claude Code 的访问
• Security：安全保障和最佳实践
• Hooks：自动化工作流并扩展权限评估