配置权限

​

权限系统

​

管理权限

• 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 *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

​

工具名称通配符

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

​

工具特定的权限规则

​

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 等命令

​

复合命令

​

进程包装器

​

只读命令

​

PowerShell

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

​

Read 和 Edit

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

• Allow 规则：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。
• Deny 规则：当符号链接路径或其目标匹配时适用。指向被拒绝文件的符号链接本身被拒绝。

​

WebFetch

• WebFetch(domain:example.com) 匹配对 example.com 的请求
• WebFetch(domain:*.example.com) 匹配任何深度的任何子域，如 api.example.com 或 a.b.example.com，但不匹配 example.com 本身
• WebFetch(domain:*) 匹配每个域，等同于裸 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

​

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

• 用户级配置：将文件放在 ~/.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 列表

• 内容范围的 ask 规则（如 Bash(git push *)）仍然强制提示
• 显式 deny 规则仍然适用
• 针对 /、您的主目录或其他关键系统路径的 rm 或 rmdir 命令仍然会触发提示

​

托管设置

​

仅托管设置

​

设置优先级

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

​

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

• 您启动 Claude Code 的目录不在 git 存储库内。
• 会话在您自己的配置主目录中运行：您的主目录或任何您已将其 .claude 子目录设置为 CLAUDE_CONFIG_DIR 的目录。

• Yes, I trust this folder：保存该工作区的信任并在同一会话中应用规则。
• No, continue without these permissions：继续工作，忽略这些规则。对话框将在下一个会话中再次出现。

​

示例配置

​

另请参见

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