配置权限

​

权限系统

​

在回答权限提示时添加注释

• Enter：提交您的答案并附加注释。如果您将字段留空，Claude Code 会提交答案而不附加注释。
• Tab：关闭字段而不回答。Claude Code 保留您输入的文本，如果您使用该选项回答，仍会发送它。
• Shift+Tab：在文件提示上，例如 Edit 或 Write 提示，关闭字段的方式与 Tab 相同。在 v2.1.235 之前，在字段内按 Shift+Tab 会选择允许操作在会话的其余部分进行的选项，因此 Claude Code 批准了会话其余部分的操作并丢弃了注释。

• 是：Claude Code 运行操作，然后在结果后将您的注释发送给 Claude。
• 否：Claude Code 将您的注释作为拒绝原因发送给 Claude，Claude 继续工作。如果您在来自主对话的提示上选择否而不附加注释，Claude Code 会停止该轮。

​

管理权限

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

​

权限模式

​

权限规则语法

​

匹配工具的所有使用

​

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

​

按输入参数匹配

• 参数名称必须是工具输入的直接字段，例如 Agent 工具上的 model。嵌套在对象或数组内的字段不可匹配
• 每个规则命名一个参数。要对 model 和 isolation 进行门控，请编写两个规则 Agent(model:opus) 和 Agent(isolation:worktree)，而不是在一个规则中组合它们
• 该值支持 * 作为通配符，匹配任何字符序列，因此 Agent(isolation:*) 匹配任何显式隔离值。没有 * 时匹配是精确的
• 模型省略的参数永远不会被匹配，因此 Agent(model:*) 不匹配留下 model 未设置的调用
• 该值与 Claude 发送的文字输入进行比较，在任何规范化之前。Agent(model:opus) 匹配别名 opus 但不匹配完整模型 ID。使用 --verbose 运行以查看每个工具调用中的确切参数名称和值
• 冒号周围的空格被忽略

​

通配符模式

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

• * 代表其位置上的任何文本。 在 Bash(git * main) 中，它代表子命令，因此 Claude Code 匹配每个 git 子命令和它之前的每个选项。这包括 -c，它使 git 运行您命名的程序。在 Bash(* --version) 中，* 代表程序，因此任何程序都匹配。
• 末尾的 *，前面有空格，也匹配裸命令。 Bash(ls *) 匹配 ls，Bash(git log *) 匹配 git log。这仅在尾部 * 是规则的唯一通配符时成立：Bash(* --help *) 匹配 npm --help x 但不匹配 npm --help。
• 尾部 * 前的空格是规则的一部分。 Bash(ls *) 在 ls 后需要一个空格，因此 lsof 不匹配。Bash(ls*) 没有空格，因此它也匹配 lsof。

​

工具名称通配符

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

​

工具特定的权限规则

​

Bash

​

复合命令

​

包装器

​

Bash 规则不匹配的内容

​

只读命令

• 具有写入能力标志的命令的未引用 glob：具有写入能力或执行能力标志的命令，如 find、sort、sed 和 git，在存在未引用的 glob 时提示，因为 glob 可能扩展为像 -delete 这样的标志。
• docker 指向另一个守护程序：当命令携带选择不同守护程序的标志时，docker 的只读形式提示，如 -H、--context 或 Podman 的 --url 和 --connection。
• file 带有路径打开标志：当 file 传递 -m/--magic-file 或 -f/--files-from 时，file 提示，因为这些标志使 file 打开标志值中命名的路径。
• Windows 上的网络路径：其参数包括网络 (UNC) 路径的命令，如 \\server\share\file，提示是因为访问网络路径可能会将您的 Windows 凭据发送到它命名的主机。同样的检查适用于PowerShell 工具命令。
• 分析无法解析的命令：当 Claude Code 无法完全解析命令时，它会要求批准而不是将命令视为只读。超过 10,000 个字符的命令总是提示，因为它们超过了分析解析的内容。

• cd 与 git：当 cd 改变到不同目录时提示，因为在新目录中运行 git 可以执行该目录的钩子。cd 的目标解析到当前工作目录是无操作的，不会触发提示。
• cd 与重定向：当 Claude Code 无法确定在 cd 运行后重定向目标解析到哪个目录时提示。仅重定向目标为 /dev/null 的命令，如 cd app; grep -r pattern . 2>/dev/null，不提示，因为 /dev/null 不依赖于工作目录。

​

重定向

• 输出重定向：对于 > file、>> file 或 2> file，检查涵盖您的 Edit allow 和 deny 规则、受保护的路径和工作目录。像 Bash(git commit *) 这样的规则允许命令，而不是目标。以 ~ 开头或包含 glob 字符的目标需要您的批准。
• 输入重定向：对于 < file，检查涵盖您的 Read allow 和 deny 规则和工作目录。工作目录外的目标需要您的批准，除非 allow 规则涵盖它。包含 glob 模式的目标，或在同一命令中跟随 cd 的相对路径，即使 allow 规则涵盖它也需要您的批准。Claude Code 在 v2.1.257 及更高版本中检查输入目标。

​

PowerShell

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

​

Read 和 Edit

• Edit(/docs/**)：编辑 <primary working directory>/docs/ 中的文件，而不是 /docs/ 或 <primary working directory>/.claude/docs/
• Read(~/.zshrc)：读取您主目录的 .zshrc
• Edit(//tmp/scratch.txt)：编辑绝对路径 /tmp/scratch.txt
• Read(src/**)：作为 allow 规则，仅从 <current-directory>/src/ 读取；作为 deny 或 ask 规则，匹配当前目录下任何深度的 src 目录

• Allow 规则：Edit(src/**) 仅匹配 <cwd>/src 及其下的文件。要允许任何深度的目录名，请编写 Edit(**/src/**)。
• Deny 和 ask 规则：Read(secrets/**) 匹配当前目录下任何深度的名为 secrets 的目录，因此规则也适用于嵌套副本。

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js

• Claude Code 读取 ! 模式相对于当前目录，即使 /、~/ 或 // 跟随 !，因此模式无法到达用其中一个前缀锚定的规则。Read(!~/notes/public/**) 从 Read(~/notes/**) 中切割不出任何内容。
• 切割不能重新打开规则作为整体阻止的目录内的文件。使用 Read(secrets/**) 和 Read(!secrets/public/**)，Claude Code 仍然阻止 secrets/public 以及 secrets 的其余部分。

​

符号链接

• Allow 规则：仅在请求的路径和它解析到的文件都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。
• Deny 规则：当请求的路径或它解析到的文件匹配时适用。指向被拒绝文件的符号链接本身被拒绝。例如，使用 Read(./project/**) 允许和 Read(~/.ssh/**) 拒绝，./project/key 处的符号链接指向 ~/.ssh/id_rsa 被阻止：目标未通过 allow 规则，并匹配 deny 规则。

• 解析到工作目录外：当请求的路径在您的工作目录内，而它解析到的文件不在时，在acceptEdits 模式中写入不会自动批准。在自动模式中，除非 allow 规则批准写入，否则您会被提示而不是分类器决定。提示命名写入解析到的路径。
• 解析到请求的路径不命名的受保护路径：受保护的路径表给出每个权限模式的结果，除了表将写入路由到分类器的地方，此写入改为提示您。

​

WebFetch

• WebFetch(domain:example.com) 匹配对 example.com 的请求
• WebFetch(domain:*.example.com) 匹配任何深度的任何子域，如 api.example.com 或 a.b.example.com，但不匹配 example.com 本身
• WebFetch(domain:*) 匹配每个域。它与裸 WebFetch 规则不同；请参阅允许或拒绝每次获取

​

允许或拒绝每次获取

{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

​

MCP

• mcp__puppeteer 匹配由 puppeteer 服务器提供的任何工具
• mcp__puppeteer__* 使用通配符语法，也匹配来自 puppeteer 服务器的所有工具
• mcp__puppeteer__puppeteer_navigate 匹配由 puppeteer 服务器提供的 puppeteer_navigate 工具

​

Agent（subagents）

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

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

​

Cd

​

使用 hooks 扩展权限

​

工作目录

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

​

将会话移动到另一个目录

• 其项目设置，包括其权限规则和 hooks
• 其 .mcp.json 服务器，受与启动时相同的服务器批准约束，以及您在其中注册的本地范围 MCP 服务器
• 其设置启用的 plugins、其 skills 和其 subagents
• 其 env 值，应用在前一个目录的设置中的环境变量之上，这些变量保持有效

​

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

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

​

权限如何与沙箱交互

• 权限控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 规则无法阻止 EndConversation，而任何其他工具仍然存在。
• 沙箱提供 OS 级别的强制执行，限制 shell 命令的文件系统和网络访问。它仅适用于 Bash、PowerShell 和 Monitor 命令及其子进程。

• 内容范围的 ask 规则（如 Bash(git push *)）仍然强制提示
• 显式 deny 规则仍然适用
• 针对关键路径的 rm 或 rmdir 命令仍然通过常规权限流程

​

托管设置

​

设置优先级

​

项目允许规则和工作区信任

• 在存储库中，Claude Code 根据 git 存储库根目录来保存信任，因此信任覆盖整个存储库，除了其中嵌套的任何 git 存储库（如子模块）。在工作树中，它使用主检出的根目录，就像它对保存的规则所做的那样。
• 在存储库外，Claude Code 根据您启动它的目录来保存信任，信任覆盖该目录的任何子目录，除了其中嵌套的 git 存储库（如克隆）。每个被覆盖的子目录随后都被视为一个您信任其父目录的文件夹。
• 当您从主目录启动时，Claude Code 仅在当前会话期间保持信任，不会将其写入磁盘；请参阅其他保护措施说明。

​

当您的本地设置文件需要信任时

• 在您的配置主目录中： Claude Code 立即应用该文件夹的 .claude/settings.local.json 而无需运行 git。您的配置主目录是您的主目录，或一个您已将其 .claude 子目录设置为 CLAUDE_CONFIG_DIR 的目录。如果该 CLAUDE_CONFIG_DIR 目录位于 git 存储库内，并且 Claude Code 改为将您的本地设置保留在存储库根目录，它会像在其他任何地方一样暂不应用这些规则。
• 其他任何地方： Claude Code 像对待项目设置一样暂不应用该文件的规则。一旦检查运行，Claude Code 应用未跟踪文件的规则，或位于任何 git 存储库外的目录中的文件的规则，即使您尚未信任该确切文件夹。

​

在您信任文件夹之前运行什么

• 传递 --setting-sources user，或设置 SDK 的 settingSources 而不包括项目设置，以便 Claude Code 既不读取项目的设置文件也不读取其 .mcp.json
• 使用 --bare 启动，以便 Claude Code 不读取项目中的 hooks、skills、自定义命令、子代理、插件或 .mcp.json 服务器。项目的 env 块和 awsAuthRefresh 等辅助程序在其设置文件中仍然适用，Claude Code 仅从 --settings 读取 apiKeyHelper
• 传递 --settings '{"disableAllHooks": true}' 以关闭该运行的 hooks。仅在您的用户设置中设置它是不够的，因为存储库的项目设置优先于您的设置，可以将其设置回 false
• 添加 disabledMcpjsonServers 条目以在每个会话类型中按名称拒绝 .mcp.json 服务器

​

示例配置

​

另请参见

• 所有设置：每个设置键，包括权限键
• 配置自动模式：告诉自动模式分类器您的组织信任哪些基础设施
• 沙箱隔离：Bash 命令的 OS 级文件系统和网络隔离
• 身份验证：设置用户对 Claude Code 的访问
• 安全：安全保障和最佳实践
• Hooks：自动化工作流并扩展权限评估