文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

配置权限

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

Claude Code 支持细粒度权限，以便你可以精确指定代理被允许做什么和不能做什么。权限设置可以检入版本控制并分发给组织中的所有开发者，也可以由个别开发者自定义。

权限系统

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

管理权限

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

• 允许规则让 Claude Code 无需手动批准即可使用指定工具。
• 询问规则在 Claude Code 尝试使用指定工具时提示确认。
• 拒绝规则阻止 Claude Code 使用指定工具。

规则按顺序评估：拒绝 -> 询问 -> 允许。第一个匹配的规则获胜，因此拒绝规则始终优先。

拒绝规则根据是否命名工具或在工具内限定模式而表现不同。裸工具名称如 Bash 会将工具从 Claude 的上下文中完全移除，因此 Claude 永远看不到它。带作用域的规则如 Bash(rm *) 保持工具可用，在 Claude 尝试时阻止匹配的调用。

权限模式

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

要阻止使用 bypassPermissions 或 auto 模式，在任何设置文件中将 permissions.disableBypassPermissionsMode 或 permissions.disableAutoMode 设置为 "disable"。这些在管理设置中最有用，因为它们不能被覆盖。

权限规则语法

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

匹配工具的所有用法

要匹配工具的所有用法，仅使用不带括号的工具名称：

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

使用限定符进行细粒度控制

在括号中添加限定符以匹配特定的工具用法：

通配符模式

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、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 始终提示，无论目标目录是什么。

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 与 Claude 共享的选择和打开文件上下文。

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/ 读取

规则仅匹配其锚点下的文件，因此锚点决定拒绝规则的覆盖范围。裸文件名遵循 gitignore 语义并在任何深度匹配，因此 Read(.env) 和 Read(**/.env) 等效：

当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。允许和拒绝规则对该对的处理方式不同：允许规则回退到提示你，而拒绝规则直接阻止。

• 允许规则：仅当符号链接路径和其目标都匹配时应用。在允许目录内指向外部的符号链接仍会提示你。
• 拒绝规则：当符号链接路径或其目标任一匹配时应用。指向拒绝文件的符号链接本身也被拒绝。

例如，使用 Read(./project/**) 允许和 Read(~/.ssh/**) 拒绝，./project/key 处指向 ~/.ssh/id_rsa 的符号链接被阻止：目标不通过允许规则且匹配拒绝规则。

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 可以使用哪些 subagents：

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

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

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

使用钩子扩展权限

Claude Code 钩子提供了一种注册自定义 shell 命令以在运行时执行权限评估的方式。当 Claude Code 进行工具调用时，PreToolUse 钩子在权限提示之前运行。钩子输出可以拒绝工具调用、强制提示或跳过提示让调用继续。

钩子决定不会绕过权限规则。拒绝和询问规则无论 PreToolUse 钩子返回什么都会被评估，因此匹配的拒绝规则会阻止调用，匹配的询问规则在钩子返回 "allow" 或 "ask" 时仍会提示。这保留了管理权限中描述的拒绝优先顺序，包括在管理设置中设置的拒绝规则。

阻塞钩子也优先于允许规则。以代码 2 退出的钩子在权限规则评估之前停止工具调用，因此即使允许规则会让调用继续，阻塞仍然适用。要在无需提示的情况下运行所有 Bash 命令（除少数你想阻止的），将 "Bash" 添加到你的允许列表并注册一个拒绝这些特定命令的 PreToolUse 钩子。参见阻止对受保护文件的编辑了解你可以适配的钩子脚本。

工作目录

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

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

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

附加目录授予文件访问权限，而非配置

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

这些例外仅适用于通过 --add-dir 标志或 /add-dir 命令添加的目录。在设置文件中列出的 permissions.additionalDirectories 目录仅授予文件访问权限，不加载下面的任何配置。

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

Subagents、命令和输出样式从当前工作目录及其父目录、~/.claude/ 处的用户目录以及管理设置中发现。钩子和其他 settings.json 键从当前工作目录的 .claude/ 文件夹加载，不回退到父目录，同时加载你的用户 ~/.claude/settings.json 和管理设置。要跨项目共享该配置，使用以下方法之一：

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

权限如何与沙箱交互

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

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

两者结合使用以实现纵深防御：

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

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

管理设置

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

仅管理设置

以下设置仅从管理设置中读取。将它们放在用户或项目设置文件中没有效果。

disableBypassPermissionsMode 通常放在管理设置中以强制执行组织策略，但它在任何作用域下都有效。用户可以在自己的设置中设置它来锁定自己退出绕过模式。

设置优先级

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

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

如果工具在任何级别被拒绝，其他级别都不能允许它。例如，管理设置的拒绝不能被 --allowedTools 覆盖，--disallowedTools 可以添加超出管理设置定义的限制。

嵌入主机可以通过 SDK managedSettings 选项在 parentSettingsBehavior 设置为 "merge" 时提供额外的管理策略；嵌入器的值可以收紧策略但不能放松。

例如，如果用户设置允许某个权限而项目设置拒绝它，拒绝规则会阻止它。反之亦然：用户级拒绝会阻止项目级允许，因为来自任何作用域的拒绝规则在允许规则之前评估。

示例配置

此仓库包含常见部署场景的入门设置配置。将这些作为起点并根据需要调整。

另请参阅

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