配置权限

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

权限系统

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

工具类型	示例	需要批准	”是，不再询问”行为
只读	文件读取、Grep	否	不适用
Bash 命令	Shell 执行	是	每个项目目录和命令永久有效
文件修改	Edit/Write 文件	是	直到会话结束

管理权限

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

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

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

权限模式

Claude Code 支持多种权限模式来控制工具的批准方式。在您的设置文件中设置 defaultMode：

模式	描述
`default`	标准行为：在首次使用每个工具时提示权限
`acceptEdits`	自动接受会话的文件编辑权限
`plan`	Plan Mode：Claude 可以分析但不能修改文件或执行命令
`delegate`	代理团队负责人的协调专用模式。将负责人限制为团队管理工具，因此所有实现工作都通过队友进行。仅在代理团队活跃时可用。有关详细信息，请参阅委托模式。
`dontAsk`	自动拒绝工具，除非通过 `/permissions` 或 `permissions.allow` 规则预先批准
`bypassPermissions`	跳过所有权限提示（需要安全环境，请参阅下面的警告）

bypassPermissions 模式禁用所有权限检查。仅在隔离环境（如容器或虚拟机）中使用此模式，其中 Claude Code 无法造成损害。管理员可以通过在托管设置中将 disableBypassPermissionsMode 设置为 "disable" 来防止此模式。

权限规则语法

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

匹配工具的所有使用

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

规则	效果
`Bash`	匹配所有 Bash 命令
`WebFetch`	匹配所有网络获取请求
`Read`	匹配所有文件读取

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

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

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

规则	效果
`Bash(npm run build)`	匹配确切的命令 `npm run build`
`Read(./.env)`	匹配读取当前目录中的 `.env` 文件
`WebFetch(domain:example.com)`	匹配对 example.com 的获取请求

通配符模式

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

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 merge main

当 * 出现在末尾且前面有空格时（如 Bash(ls *)），它强制执行单词边界，要求前缀后跟空格或字符串结尾。例如，Bash(ls *) 匹配 ls -la 但不匹配 lsof。相比之下，Bash(ls*) 没有空格匹配 ls -la 和 lsof 都因为没有单词边界约束。

Claude Code 知道 shell 运算符（如 &&），因此前缀匹配规则（如 Bash(safe-cmd *)）不会给它权限运行命令 safe-cmd && other-cmd。

尝试约束命令参数的 Bash 权限模式很脆弱。例如，Bash(curl http://github.com/ *) 旨在将 curl 限制为 GitHub URL，但不会匹配变体，如：

URL 前的选项：curl -X GET http://github.com/...
不同的协议：curl https://github.com/...
重定向：curl -L http://bit.ly/xyz（重定向到 github）
变量：URL=http://github.com && curl $URL
额外空格：curl http://github.com

为了更可靠的 URL 过滤，请考虑：

限制 Bash 网络工具：使用 deny 规则阻止 curl、wget 和类似命令，然后对允许的域使用带有 WebFetch(domain:github.com) 权限的 WebFetch 工具
使用 PreToolUse hooks：实现一个 hook 来验证 Bash 命令中的 URL 并阻止不允许的域
通过 CLAUDE.md 指导 Claude Code 了解您允许的 curl 模式

请注意，仅使用 WebFetch 不会阻止网络访问。如果允许 Bash，Claude 仍然可以使用 curl、wget 或其他工具来访问任何 URL。

Read 和 Edit

Edit 规则适用于所有编辑文件的内置工具。Claude 尽力尝试将 Read 规则应用于所有读取文件的内置工具，如 Grep 和 Glob。 Read 和 Edit 规则都遵循 gitignore 规范，具有四种不同的模式类型：

模式	含义	示例	匹配
`//path`	来自文件系统根目录的绝对路径	`Read(//Users/alice/secrets/**)`	`/Users/alice/secrets/**`
`~/path`	来自主目录的路径	`Read(~/Documents/*.pdf)`	`/Users/alice/Documents/*.pdf`
`/path`	相对于设置文件的路径	`Edit(/src/*/.ts)`	`<settings file path>/src/*/.ts`
`path` 或 `./path`	相对于当前目录的路径	`Read(*.env)`	`<cwd>/*.env`

像 /Users/alice/file 这样的模式不是绝对路径。它相对于您的设置文件。对于绝对路径，请使用 //Users/alice/file。

示例：

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

在 gitignore 模式中，* 匹配单个目录中的文件，而 ** 递归匹配目录。要允许所有文件访问，请使用不带括号的工具名称：Read、Edit 或 Write。

WebFetch

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

MCP

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

Task（subagents）

使用 Task(AgentName) 规则来控制 Claude 可以使用哪些 subagents：

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

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

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

使用 hooks 扩展权限

Claude Code hooks 提供了一种方法来注册自定义 shell 命令以在运行时执行权限评估。当 Claude Code 进行工具调用时，PreToolUse hooks 在权限系统之前运行，hook 输出可以确定是否批准或拒绝工具调用来代替权限系统。

工作目录

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

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

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

权限如何与沙箱交互

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

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

使用两者进行深度防御：

权限 deny 规则阻止 Claude 甚至尝试访问受限资源
沙箱限制防止 Bash 命令到达定义边界之外的资源，即使提示注入绕过 Claude 的决策制定
沙箱中的文件系统限制使用 Read 和 Edit deny 规则，而不是单独的沙箱配置
网络限制结合 WebFetch 权限规则与沙箱的 allowedDomains 列表

托管设置

对于需要对 Claude Code 配置进行集中控制的组织，管理员可以将 managed-settings.json 文件部署到系统目录。这些策略文件遵循与常规设置文件相同的格式，不能被用户或项目设置覆盖。 托管设置文件位置：

macOS：/Library/Application Support/ClaudeCode/managed-settings.json
Linux 和 WSL：/etc/claude-code/managed-settings.json
Windows：C:\Program Files\ClaudeCode\managed-settings.json

这些是系统范围的路径（不是用户主目录，如 ~/Library/...），需要管理员权限。它们设计用于由 IT 管理员部署。

仅托管设置

某些设置仅在托管设置中有效：

设置	描述
`disableBypassPermissionsMode`	设置为 `"disable"` 以防止 `bypassPermissions` 模式和 `--dangerously-skip-permissions` 标志
`allowManagedPermissionRulesOnly`	当为 `true` 时，防止用户和项目设置定义 `allow`、`ask` 或 `deny` 权限规则。仅应用托管设置中的规则
`allowManagedHooksOnly`	当为 `true` 时，防止加载用户、项目和插件 hooks。仅允许托管 hooks 和 SDK hooks
`strictKnownMarketplaces`	控制用户可以添加哪些插件市场。请参阅托管市场限制

设置优先级

权限规则遵循与所有其他 Claude Code 设置相同的设置优先级：托管设置具有最高优先级，其次是命令行参数、本地项目、共享项目和用户设置。如果权限在用户设置中被允许但在项目设置中被拒绝，项目设置优先，权限被阻止。

示例配置

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

另请参阅

Settings：完整的配置参考，包括权限设置表
Sandboxing：Bash 命令的操作系统级文件系统和网络隔离
Authentication：设置用户对 Claude Code 的访问
Security：安全保障和最佳实践
Hooks：自动化工作流并扩展权限评估

入门指南

核心概念

平台和集成

使用 Claude 构建

部署

管理

配置

参考

资源

更新日志

权限系统

管理权限

权限模式

权限规则语法

匹配工具的所有使用

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

通配符模式

工具特定的权限规则

Bash

Read 和 Edit

WebFetch

MCP

Task（subagents）

使用 hooks 扩展权限

工作目录

权限如何与沙箱交互

托管设置

仅托管设置

设置优先级

示例配置

另请参阅

​权限系统

​管理权限

​权限模式

​权限规则语法

​匹配工具的所有使用

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

​通配符模式

​工具特定的权限规则

​Bash

​Read 和 Edit

​WebFetch

​MCP

​Task（subagents）

​使用 hooks 扩展权限

​工作目录

​权限如何与沙箱交互

​托管设置

​仅托管设置

​设置优先级

​示例配置

​另请参阅

权限系统

管理权限

权限模式

权限规则语法

匹配工具的所有使用

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

通配符模式

工具特定的权限规则

Bash

Read 和 Edit

WebFetch

MCP

Task（subagents）

使用 hooks 扩展权限

工作目录

权限如何与沙箱交互

托管设置

仅托管设置

设置优先级

示例配置

另请参阅