SpyBara
Go Premium

permissions.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 325 additions and 139 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

配置权限

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

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

权限系统

Claude Code 使用分层权限系统来平衡功能和安全性。该表显示了对于每种工具类型，手动模式是否在操作运行前询问。其他权限模式改变了这些提示中的哪些会询问您；在自动模式中，分类器会审查操作而不是您，分类器如何评估操作列出了它看到的操作。

工具类型 示例 需要批准 "是，不再询问"行为
只读 文件读取、Grep 否，在工作目录和其他目录内 不适用
Bash 命令 Shell 执行 是，除了内置的只读命令集合 每个项目目录和命令永久有效
文件修改 Edit/Write 文件 是 直到会话结束
Web 获取 WebFetch 是，除了内置的预批准文档域集合 每个项目目录和域永久有效
Web 搜索 WebSearch 是 每个项目目录永久有效

当您选择"是，不再询问"且批准永久保存时（例如对于 Bash 命令或 WebFetch 域），Claude Code 会将规则保存到 git 项目根目录的 .claude/settings.local.json，通过工作树解析到主检出。该规则适用于该项目中的未来会话，包括在子目录和工作树中启动的会话。文件修改批准不会保存到文件中：如表所示，它仅持续到会话结束。在某些情况下，例如在 git 项目外或在 Windows 上，Claude Code 不使用项目根目录；Claude Code 查找每个文件的位置列出了这些情况以及它保存规则的位置。

在 v2.1.211 之前，Claude Code 总是在启动目录中保存规则，因此在工作树或子目录中授予的批准不适用于项目的其余部分。早期版本在子目录或工作树中保存的规则仍然适用于在那里启动的会话。

有时权限提示仅提供一次性批准，没有"不再询问"选项，也没有允许操作在会话的其余部分进行的选项。Claude Code 仅在提示可以向您显示它们允许的所有内容时才提供这些选项，因此您从提示保存的规则仅涵盖其选项命名的内容。

当您启动 Claude Code 的目录是使选项标签过长的原因时，Claude Code 会在标签中缩短它，用 ~ 替换您的主目录，然后用 … 替换路径的末尾，并保留该选项。您仍然保存相同的规则。Claude Code 在三种情况下省略选项：

  • 命令或编辑： 太大而无法完整显示。
  • 规则将涵盖的命令或路径： 标签无法容纳它们全部。
  • 启动目录过长，未缩短： 它包含 Claude Code 无法安全显示的字符，或者即使是其开头也无法容纳。

批准该操作一次，或在 /permissions 中自己添加规则。

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

您可以在批准或拒绝单个操作时向 Claude 附加注释。在大多数权限提示上，包括 Bash、PowerShell、文件和 MCP 工具提示，移动到是或否并按 Tab 在该选项上打开注释字段。WebFetch 和浏览器提示不提供该字段。允许操作在会话的其余部分进行或保存规则的选项也不接受注释。

打开字段后，输入注释，然后按以下键之一：

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

Claude Code 根据您的回答方式以不同的方式传递注释：

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

管理权限

您可以使用 /permissions 查看和管理 Claude Code 的工具权限。此对话框列出所有权限规则和它们来自的 settings.json 文件。您可以在 Claude 工作时打开此对话框：当您添加或删除规则时，Claude Code 会从 Claude 在同一轮中的下一个工具调用开始应用更改。在 v2.1.234 之前，Claude Code 会将命令排队直到轮次完成。

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

规则按顺序评估：deny、ask，然后 allow。该顺序中的第一个匹配项决定结果，规则特异性不会改变顺序。

一个宽泛的 deny 规则（如 Bash(aws *)）会阻止每个匹配的调用，包括也匹配更具体的 allow 规则（如 Bash(aws s3 ls)）的调用，因此 deny 规则不能包含允许列表例外。ask 和 allow 之间也适用相同的优先级：匹配的 ask 规则即使更具体的 allow 规则也匹配同一调用，也会提示。

Deny 规则的行为取决于它们是命名工具还是在工具内范围化模式。像 Bash 这样的裸工具名称会将工具从 Claude 的上下文中完全移除，因此 Claude 永远看不到它。裸名称移除适用于除了 EndConversation 之外的每个工具：当任何其他工具仍然存在时，deny 规则无法移除它，ask 规则永远不会为其提示。像 Bash(rm *) 这样的范围化规则会保留工具的可用性，并在 Claude 尝试时阻止匹配的调用。

当 auto mode 对您的会话可用时，此对话框还包括 auto mode 分类器规则。选择 Auto mode 选项卡以查看它们。

权限模式

Claude Code 支持多种权限模式来控制工具调用的批准方式。请参阅权限模式了解何时使用每种模式。要更改会话启动时的模式，请在您的设置文件中设置 defaultMode。会话启动时的模式涵盖了每个计划的内置默认值以及 VS Code 扩展读取的内容。

模式 描述
default 在首次使用每个工具时提示权限。在 CLI、VS Code 和 JetBrains 扩展以及桌面应用中标记为 Manual，Claude Code 接受 manual 作为别名。标签和别名需要 Claude Code v2.1.200 或更高版本。桌面应用的标签不依赖于您的 CLI 版本
acceptEdits 自动接受工作目录或 additionalDirectories 中路径的文件编辑和常见文件系统命令，例如 mkdir、touch、mv 和 cp
plan Claude 读取文件并运行只读 shell 命令来探索，但不编辑您的源文件；在自动模式可用的情况下，分类器批准的命令也会运行。在 CLI 和 VS Code 扩展中标记为 Plan
auto 自动批准工具调用，并进行后台安全检查以验证操作与您的请求一致
dontAsk 自动拒绝工具，除非通过 /permissions 或 permissions.allow 规则预先批准。AskUserQuestion、标记为 requiresUserInteraction 的 MCP 工具以及连接器工具您的组织设置为 ask即使您已允许它们也会被拒绝
bypassPermissions 跳过权限提示，除了任何模式都不会自动批准的操作

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

权限规则语法

权限规则遵循格式 Tool 或 Tool(specifier)。括号内的说明符是字面意思，因此包含括号的命令或路径不需要转义。

匹配工具的所有使用

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

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

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

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

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

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

按输入参数匹配

拒绝和询问规则可以使用 Tool(param:value) 匹配任何内置工具上的顶级输入参数。

要匹配 MCP 工具上的参数，请使用 --disallowedTools 传递拒绝规则。当 Claude Code 加载设置文件时，它会跳过任何具有括号的 mcp__ 规则。Claude Code 在交互式会话启动时在无效设置对话框中列出跳过的规则，以及在 claude doctor 输出中列出。

当 Claude 使用该参数设置为该确切值调用工具时，参数规则匹配。一个参数值的允许规则不会确立该调用总体上是安全的，因此允许规则继续使用每个工具自己的说明符语法。这适用于工具接受的任何标量参数：

规则 匹配
Agent(model:opus) 请求 Opus 模型层级的 Agent 调用
Agent(isolation:worktree) 请求 git worktree 的 Agent 调用
Bash(run_in_background:true) 在后台运行的 Bash 调用

参数匹配遵循以下规则：

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

您不能以这种方式匹配工具的主要内容字段：Bash 和 PowerShell 的 command、Read、Edit 和 Write 的 file_path、Grep 和 Glob 的 path、NotebookEdit 的 notebook_path 和 WebFetch 的 url。像 Bash(command:rm *) 这样的规则可以通过复合命令绕过，因此 Claude Code 会忽略它并在启动时发出警告。改用 Bash(rm *)、Read(./path) 或 WebFetch(domain:host)。

通配符模式

Bash 规则中的 * 匹配任何文本，包括空格，因此一个规则涵盖一系列命令。没有 * 的规则匹配一个确切的命令。

编写您希望 Claude 运行而不询问的命令，并用 * 替换变化的部分。使用此配置，Claude Code 运行 npm 脚本和 git 提交而不询问，并拒绝以 git push 开头的命令。以另一种方式编写的推送，例如 git -C . push，不匹配；请参阅 Bash 规则不匹配的内容。

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

* 可以出现在规则中的任何位置：开始、中间或结尾。每行显示一个规则、它匹配的命令以及附近它不匹配的命令：

您编写 匹配 不匹配
Bash(npm run build) npm run build npm run build --watch
Bash(npm run *) npm run build、npm run test --watch、npm run npm install
Bash(git log * main) git log --oneline main、git log -5 main、git log --output=<file> main git log main、git push origin main
Bash(git * main) git merge main、git push origin main、git -c core.fsmonitor=<script> diff main git log
Bash(* --version) node --version、bash -c 'echo hi' --version node -v
Bash(ls *) ls -la、ls lsof
Bash(ls*) ls -la、lsof
Bash(* --help *) npm --help x npm --help

三个匹配规则产生这些行：

  • * 代表其位置上的任何文本。 在 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。

:* 后缀是编写尾部通配符的等效方式，因此 Bash(ls:*) 匹配与 Bash(ls *) 相同的命令。

当您为命令前缀选择"是，不再询问"时，权限对话框会写入空格分隔的形式。:* 形式仅在模式末尾被识别。在像 Bash(git:* push) 这样的模式中，冒号被视为文字字符，不会匹配 git 命令。

工具名称通配符

拒绝和询问规则也接受工具名称位置中的 glob 模式。该模式必须匹配完整的工具名称："*" 匹配每个工具，"mcp__*" 匹配所有服务器中的每个 MCP 工具。由裸名称 glob 拒绝规则匹配的工具会从 Claude 的上下文中移除，与裸工具名称相同，包括 EndConversation 例外：glob 拒绝在任何其他工具保留时无法移除它，glob 询问永远不会提示它。此配置拒绝每个 MCP 工具：

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

允许规则仅在文字 mcp__<server>__ 前缀之后接受工具名称 glob。服务器段必须不含 glob，以便规则命名您配置的特定服务器。mcp__puppeteer__* 匹配来自 puppeteer 服务器的每个工具，mcp__github__get_* 匹配其 get_ 工具。未锚定的允许 glob（如 "*"、"B*" 或 "mcp__*"）会被跳过并显示警告，不会自动批准任何内容。

工具名称不匹配任何已知工具的拒绝或询问规则会在启动时产生警告以捕获拼写错误。包含 _ 或 * 的工具名称不受此检查的约束。

转录本和权限对话框中为工具显示的标签可能与其规范名称不同。例如，转录本中标记为 Stop Task 的工具具有规范名称 TaskStop。权限规则和 hook 匹配器 不匹配标签，因此写作为 Stop Task 的规则不匹配。对于拒绝和询问规则，上面的启动警告会捕获不匹配。使用 工具参考 中列出的规范名称。

工具特定的权限规则

Bash

Bash 规则匹配整个命令文本，其中 * 代表任何文本。通配符模式显示每个规则形状匹配的命令以及在哪里放置 *。本节的其余部分涵盖 Claude Code 如何匹配复合命令和包装器、规则不匹配的内容、只读命令和重定向。

复合命令

Deny 和 ask 规则在任何子命令匹配它们时适用，包括嵌套在子 shell 中的命令、命令替换或控制流体（如 for 循环）中的命令。像 Bash(git clean *) 这样的 ask 规则仍然会提示您 cd /tmp && git clean -f 或 echo "$(git clean -f)"，即使在自动模式中。

当 && 或 || 后面没有任何内容时，例如在 npm test && 中，Claude Code 将命令视为无法解析，不会将其分割为子命令以进行 allow 规则匹配，因此像 Bash(npm *) 这样的规则不会批准它。

当您使用"是，不再询问"批准复合命令时，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，加上 shell 内置命令 command 和 builtin，以及 zsh 的 noglob。每个都将其参数作为实际命令运行。两个相关的形式不被剥离：查询形式 command -v，它查找命令而不是运行命令，以及 zsh 的 nocorrect。

Claude Code 也会剥离某些已知安全的环境变量的前导赋值，因此 Bash(npm test *) 匹配 NODE_ENV=test npm test。Allow 规则不会匹配超过任何其他变量的赋值。Deny 或 ask 规则匹配超过任何前导赋值，因此 deny 中的 Bash(rm *) 仍然匹配 FOO=bar rm -rf tmp/。

裸 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 *) 这样的前缀规则自动批准，因此在 Manual 模式下它们总是提示。同样适用于带有 -exec 或 -delete 的 find：Bash(find *) 规则不涵盖这些形式。要批准特定调用，请为完整命令字符串编写精确匹配规则。

Bash 规则不匹配的内容

Bash 规则匹配 Claude 编写的命令文本，在 Claude Code 分割复合命令和剥离包装器之后。它不匹配以不同形式调用的同一程序，因此 deny 或 ask 规则涵盖 Claude 通常产生的调用，而不是围绕程序的安全边界。deny 或 ask 中的这些规则停止第一种形式，而不是其他形式：

规则 停止 不停止
Bash(curl *) curl https://example.com /usr/bin/curl https://example.com、sh -c 'curl https://example.com'
Bash(rm *) rm -rf build/ /bin/rm -rf build/、bash -c 'rm -rf build/'
Bash(git push *) git push origin main git -C . push origin main、git -c push.default=current push origin main、git 'push' origin main

您的其他规则和权限模式决定最后一列中的命令。

对于不依赖于命令文本的文件系统和网络强制执行，使用沙箱。要在运行前使用您自己的逻辑检查完整的命令文本，使用PreToolUse hook。

只读命令

Claude Code 将一组内置 Bash 命令识别为只读，并在每种模式下无需权限提示即可运行它们，除了由 permissions.blockReadsOutsideWorkingDirectories 限制的路径。该集合包括 ls、cat、echo、pwd、head、tail、grep、find、wc、which、diff、stat、du、cd 和 git 的只读形式。该集合不可配置；要对其中一个命令要求提示，请为其添加 ask 或 deny 规则。

像 ls > out.txt 这样的重定向会在目标上添加检查。请参阅重定向。

对于其每个标志都是只读的命令，允许未引用的 glob 模式，因此 ls *.ts 和 wc -l src/*.py 无需提示即可运行。

在 Manual 模式下，来自此集合的命令在这些情况下仍然提示：

  • 具有写入能力标志的命令的未引用 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 也是只读的，像 cd packages/api && ls 这样的复合命令在每个部分都符合条件时无需提示即可运行。即使每个部分都是只读的，这些组合也会提示：

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

重定向

当命令重定向输出或输入时，Claude Code 会根据您的文件规则检查重定向目标，就像 Claude 直接写入或读取该文件一样：

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

没有文件在其后的目标不被检查：/dev/null、文件描述符形式如 2>&1 和 <&3，以及 here-docs 和 here-strings。

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

要阻止 Claude 的文件工具读取文件或目录，请为其路径添加 Read deny 规则，如 Read(./.env) 或 Read(./secrets/**)；排除敏感文件有一个粘贴就用的示例。

Edit 规则适用于所有编辑文件的内置工具。Claude 尽力将 Read 规则应用于所有读取文件的内置工具，如 Grep 和 Glob，以及您提示中的 @file 提及，以及连接的 IDE 与 Claude 共享的选择和打开文件上下文。

Read deny 规则也会阻止同一路径上的 Edit 和 Write 工具，包括在那里创建新文件。NotebookEdit 不被覆盖，因此为任何工具都不能更改的路径添加 Edit deny 规则。检查需要 Claude Code v2.1.208 或更高版本进行编辑，以及 v2.1.228 或更高版本进行写入。

Claude Code 仅根据 Edit(path) 和 Read(path) 规则检查文件权限。如果您为 Write、NotebookEdit、Glob 或旧版 MultiEdit 工具编写路径规则，Claude Code 接受该规则但从不查询它，并在启动时警告，除了在 --allowedTools 中传递的 Glob 规则。使用 Edit(docs/**) 代替 Write(docs/**)、NotebookEdit(docs/**) 或 MultiEdit(docs/**)，以及 Read(docs/**) 代替 Glob(docs/**)。Claude Code 不会警告没有路径的工具名称规则，如 Write 的 deny 规则；它在任何地方在工具级别匹配该规则。需要 Claude Code v2.1.210 或更高版本。

Read 和 Edit 规则都使用gitignore模式语法，具有四种不同的模式类型；对于单段目录模式，匹配深度也取决于规则类型，本节后面描述：

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

/path 模式锚定在与定义它的设置源关联的目录，因此相同的规则根据您放置它的位置匹配不同的位置：

规则定义在 /path 解析为
.claude/settings.json 处的项目设置 <primary working directory>/path
.claude/settings.local.json 处的本地设置 <primary working directory>/path
~/.claude/settings.json 处的用户设置 ~/.claude/path
使用 --settings <file> 传递的文件 <directory of file>/path
CLI 标志或会话规则 <primary working directory>/path

您通过 /permissions 添加的规则遵循您保存它的设置文件的行。

本地设置规则锚定在会话的主工作目录，而不是 Claude Code 在 v2.1.211 及更高版本中存储文件的存储库根目录。在从存储库根目录启动的会话中，两个目录相同；在worktree会话中，像 Edit(/src/**) 这样的共享规则匹配该 worktree 自己的 src/ 目录。

像 Read(/secrets/**) 这样的 deny 规则在用户设置中阻止 ~/.claude/secrets/**，而不是您项目中的 secrets 目录。要在用户设置中编写适用于每个项目内部的规则，请改用 // 绝对路径或 ~/ 主目录相对路径。

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

示例：

  • 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 目录

一个规则只匹配其锚点下的文件；在该范围内，匹配深度取决于模式形状，以及对于单段目录模式，规则类型，下面描述。裸文件名遵循 gitignore 语义并在任何深度匹配，因此 Read(.env) 和 Read(**/.env) 是等价的：

Deny 规则 阻止 不阻止
Read(.env) 或 Read(**/.env) 当前目录或其下的任何 .env 父目录或另一个项目中的 .env
Read(//**/.env) 文件系统上任何地方的任何 .env 无；规则锚定在文件系统根目录

具有单个目录段的相对模式，如 src/**，根据规则类型在不同深度匹配：

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

每个其他模式形状在每种规则类型中的相同深度匹配：Edit(/src/**) 和 Edit(src/components/**) 仅在其锚定位置匹配，而 Edit(**/src/**) 在任何深度匹配。

以下示例显示了具有顶级 src/ 目录和 vendor/ 下嵌套副本的项目中的每个模式形状：

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js
规则 匹配 src/app.ts 匹配 vendor/pkg/src/lib.js
Edit(src/**) 作为 allow 规则 是 否
Edit(src/**) 作为 deny 或 ask 规则 是 是
Edit(/src/**) 在任何规则类型中 是 否
Edit(**/src/**) 在任何规则类型中 是 是

当您使用"是，不再询问"批准文件路径时，Claude Code 会转义该路径中的 gitignore 模式字符，如 [、] 和 *，因此生成的规则仅匹配您批准的字面路径。您自己编写的规则不会被转义。在 v2.1.202 之前，Claude Code 保存未转义的路径，因此为名为 [2024-06] Reports 的目录生成的规则可能无法匹配其自己的路径或匹配意外的兄弟目录。

您不需要转义路径中的括号，因此 Edit(./Finance (2024)/**) 匹配按拼写的 Finance (2024) 文件夹。

其路径不可用作 gitignore 模式的 deny 或 ask 规则仍然保护该确切路径。其模式不可用的 allow 规则不批准任何内容。

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

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

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

当工具打开已批准的文件时，Claude Code 确认路径仍然解析到权限检查批准的位置。

Grep 和 Glob 搜索 path 参数解析到的目录。Claude Code 将 Read deny 规则应用于该目录。

WebFetch

WebFetch 规则使用 domain: 前缀并针对请求的 URL 的主机名进行匹配。匹配不区分大小写，支持 * 通配符，并从规则和主机名中剥离尾部 .，因此 example.com. 和 example.com 被视为相同。

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

在前导 *. 或裸 * 以外的任何位置，通配符仅匹配两个点之间的文本。WebFetch(domain:example.*) 匹配 example.org，其中 * 变成 org，但不匹配 example.evil.com，其中 * 必须变成 evil.com 并跨越一个点。这防止尾部通配符匹配攻击者可以注册的域。

WebFetch 规则中的通配符需要 Claude Code v2.1.172 或更高版本来匹配获取。

允许或拒绝每次获取

裸 WebFetch 规则是没有 domain: 部分的工具名称，如 "deny": ["WebFetch"]。它和 WebFetch(domain:*) 都涵盖每个 URL，但 Claude Code 以不同方式应用它们，只有 domain: 形式也将其域添加到沙箱的允许或拒绝的域列表。该部分列出沙箱支持的通配符形式和添加裸 * 的版本。

每行显示规则在 allow 列表中和 deny 列表中的作用：

规则 在 allow 中 在 deny 中
WebFetch Claude 无需提示您即可获取。不改变沙箱命令可以到达的主机。 Claude Code 移除 WebFetch 工具，因此 Claude 根本无法获取。不改变沙箱命令可以到达的主机。
WebFetch(domain:*) Claude 无需提示您即可获取，沙箱命令可以到达任何主机。 Claude Code 保留工具并拒绝每次获取，沙箱命令无法到达任何主机。

要让 Claude 自由获取同时保持沙箱允许列表不变，请使用裸形式。此 settings.json 这样做：

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

当您要求 Claude 获取页面时，它无需提示即可获取。当您要求它对沙箱允许列表外的主机运行沙箱 curl 时，Claude Code 仍然会提示您该主机，或在自动模式中将请求发送到分类器，因为裸规则没有将主机添加到允许列表。

MCP

MCP 规则使用在 Claude Code 中配置的服务器名称，可选地后跟该服务器提供的工具的名称。

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

如果您的组织已设置claude.ai 连接器工具为 ask，该设置在您的会话中到达 Claude Code，该工具的 allow 规则不会生效：Claude Code 在每次调用时都会提示，即使在 auto 和 bypassPermissions 模式下。在 dontAsk 模式下（从不提示），Claude Code 会拒绝调用。Claude Code 自己获取的连接器工具显示为 mcp__claude_ai_<server>__<tool>。

在 Claude Desktop 应用中的 Cowork 会话中，Claude 通过 Cowork 的 mcp__workspace__bash 工具而不是内置 Bash 工具运行 shell 命令，Cowork 同样为 web 获取提供 mcp__workspace__web_fetch。Claude Code 也将命名整个 Bash 或 WebFetch 工具的 deny 规则应用于这些 Cowork 工具，因此托管的 Bash deny 规则阻止 Claude 在 Cowork 中运行 shell 命令。当 Claude Code 阻止此类调用时，消息命名 Cowork 工具：Permission to use mcp__workspace__bash has been denied. Allow 规则不会转移：Claude Code 从不将 Bash allow 规则应用于 mcp__workspace__bash。

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)"]
  }
}

Cd

Cd 规则控制 /cd 命令可以将会话移动到哪些目录。Cd 不是模型可调用的工具：Claude 无法调用它，规则仅在您自己运行 /cd 时适用。

裸 Cd deny 规则完全禁用 /cd。Cd(<path-pattern>) deny 规则阻止匹配的目标。Deny 规则检查目标的每个拼写，包括它解析的每个符号链接跳跃，因此为一个路径编写的规则也会阻止解析到它的目标。

添加任何 Cd allow 规则会将 /cd 切换到允许列表模式：解析的目标目录必须匹配您的一个 allow 规则，否则 /cd 拒绝。如果没有配置 Cd 规则，/cd 保持其默认行为并提示您信任不熟悉的目录。

路径模式共享来自 Read 和 Edit 规则的 //、~/ 和 / 锚点，但匹配锚定到整个目录路径而不是 gitignore 风格。* 匹配恰好一个路径段，** 匹配跨段。尾部 /** 也匹配其命名的根。

规则 匹配 不匹配
Cd(~/code/*) ~/code/app ~/code/app/src、~/code
Cd(~/code/**) ~/code 和其下的任何目录 ~/code 外的目录
Cd(**/node_modules) 任何深度的任何 node_modules 目录 node_modules/pkg

使用 hooks 扩展权限

Claude Code hooks 让您可以注册自定义 shell 命令，在运行时评估权限。当 Claude Code 进行工具调用时，PreToolUse hooks 在权限提示之前运行，适用于除了 EndConversation 之外的每个工具。hook 输出可以拒绝工具调用、强制提示或跳过提示以让调用继续。

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

标记为 requiresUserInteraction 的 MCP 工具在 hook 返回 "allow" 时仍然会提示，连接器工具您的组织设置为 ask 的工具在该设置到达 Claude Code 的会话中也是如此。

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

工作目录

默认情况下，Claude 可以访问启动它的目录中的文件。该目录是会话的主工作目录，直到您使用 /cd 移动会话。您可以扩展此访问：

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

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

您无法添加大多数网络路径（例如 UNC 共享 \\server\share）作为工作目录，因为查找它们可能会联系它们命名的主机。在 Windows 上，将共享映射到驱动器号，然后在启动时使用 --add-dir 传递该驱动器。

设置 permissions.blockReadsOutsideWorkingDirectories 以使文件工具在每种权限模式下都拒绝它围栏的路径。在自动模式下，Claude Code 会在 Claude 首次读取工作目录外的文件时提供打开它。

在 macOS 上的后台会话中，会话主机会单独从您的终端请求访问受保护的文件夹（如 ~/Desktop、~/Documents 和 ~/Downloads），当 Claude 需要在那里读取或写入文件时；如果读取失败并显示 Operation not permitted，请参阅如何向后台会话授予文件夹访问权限。

将会话移动到另一个目录

要将会话移动到不同的主工作目录，而不是在当前目录旁添加目录，请运行 /cd <path>。Claude Code 保持对话，加载新目录的 CLAUDE.md，如果您之前未在其中工作过，会提示您信任工作区。之后，当您从新目录运行 --resume 时，Claude Code 找到移动的会话。

移动后，Claude Code 立即应用新目录的项目配置：

Claude Code 还断开前一个目录的项目和本地范围 MCP 服务器，以及移动后不再启用的 plugins 的服务器。它从新目录的设置而不是前一个目录的设置中获取其他目录，并保留您使用 --add-dir 或 /add-dir 添加的目录。移动激活的 Hooks 仍然接收 ${CLAUDE_PROJECT_DIR} 设置为会话启动的项目根目录。

当新目录尚未被信任时，Claude Code 在信任提示中列出目录的设置将激活的允许规则、其他目录、hooks 和辅助命令，以便您可以在接受前查看它们。如果您拒绝，会话保持在原位置。在 v2.1.246 之前，/cd 不会应用新目录的设置、hooks、MCP 服务器或 skills，直到您恢复会话，其信任提示也不会列出目录的设置将激活的内容。

使用 Cd 权限规则限制或禁用 /cd 目标。

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

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

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

Agent SDK 在 TypeScript 中的 additionalDirectories 选项和在 Python 中的 add_dirs 选项也接收这些例外，尽管 TypeScript 选项与设置键共享其名称。SDK 将每个条目作为 --add-dir 传递给 Claude Code，因此这些目录的行为类似于标志添加的目录。来自任何标志添加目录的 Skills、命令和 subagents 通过 project setting source 加载，因此当您在 CLI 上使用 --setting-sources 或在 SDK 中使用 settingSources 排除该源时，它们不会加载，bare mode 跳过其中的命令和 subagents。

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

配置 从 --add-dir 加载
.claude/skills/ 中的 Skills 是，带有实时重新加载
.claude/commands/ 中的命令文件 是，不带实时重新加载。当添加的目录和您的项目都定义了同名命令时，Claude Code 运行您的项目的命令
.claude/agents/ 中的 Subagents 是，不带实时重新加载
.claude/settings.json 和 .claude/settings.local.json 中的设置 仅 enabledPlugins 和 extraKnownMarketplaces 键
CLAUDE.md 文件、.claude/rules/ 和 CLAUDE.local.md 仅当设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 时。CLAUDE.local.md 另外需要 local 设置源，默认启用

要在会话中期从主工作目录的子目录加载 skills、命令和 subagents，请使用该子目录的路径运行 /add-dir。Claude Code 为会话的其余部分加载它们，无需提示您或添加工作目录，因为子目录已经可读。这需要 Claude Code v2.1.257 或更高版本。

Claude Code 从当前工作目录及其父目录、您在 ~/.claude/ 的用户目录和托管设置中发现输出样式。Hooks 和其他 .claude/settings.json 键从当前工作目录的 .claude/ 文件夹加载，没有父目录回退，同时从您的用户 ~/.claude/settings.json 和托管设置加载。.claude/settings.local.json 从 git 存储库根目录加载，即使您在子目录中启动 Claude Code，除了 Claude Code 不使用存储库根目录的情况，例如在 Windows 上；在 v2.1.211 之前，它也仅从当前工作目录加载。Agent SDK 会话在所有版本中从工作目录加载它。

要在项目间共享该配置，请使用以下方法之一：

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

权限如何与沙箱交互

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

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

使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被合并到最终沙箱配置中。

当您启用沙箱并将 autoAllowBashIfSandboxed 保留为其默认值 true 时，沙箱化的 Bash 命令无需提示即可运行，即使您的权限包括裸 Bash ask 规则，或等效的 Bash(*) 形式：沙箱边界替代了该整体工具提示。

在计划模式中，Claude Code 跳过此替代。没有 ask 规则时，内置只读命令仍然无需提示即可运行，任何其他 shell 命令在您仍在计划时通过常规权限流程；请参见计划模式了解 Claude Code 如何在那里控制命令。使用裸 Bash ask 规则时，每个 Bash 命令都会提示，包括沙箱化的只读命令，与沙箱外相同。在 v2.1.212 之前，替代也适用于计划模式。

这些检查仍然适用：

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

不会在沙箱中运行的命令（如排除的命令）按照通常的方式遵守裸 Bash ask 规则。请参见沙箱模式以更改此行为。

托管设置

对于需要集中控制的组织，管理员部署托管设置，用户和项目设置无法覆盖，除了少数安全敏感的密钥。部署托管设置涵盖传递机制、托管层内的优先级以及仅托管设置可以设置的密钥。

其中一个密钥allowManagedPermissionRulesOnly使托管设置成为权限规则的唯一设置来源。其条目列出了 Claude Code 随后忽略的每个来源。

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

设置优先级

权限规则遵循与所有其他 Claude Code 设置相同的设置优先级，托管设置最高：没有其他级别（包括命令行参数）可以覆盖托管权限规则。

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

同样的规则也适用于设置范围：如果用户设置允许某个权限而项目设置拒绝它，deny 规则会阻止它。反之亦然：用户级别的 deny 会阻止项目级别的 allow，因为来自任何范围的 deny 规则在 allow 规则之前被评估。

嵌入主机可以通过 SDK managedSettings 选项提供额外的托管策略，包括权限允许规则，除非管理员设置了 allowManaged*Only 锁；向 Claude Desktop 会话传递策略涵盖了嵌入器策略何时适用。

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

项目的 .claude/settings.json 中的 permissions.allow 规则和 permissions.additionalDirectories 条目授予功能，因此 Claude Code 仅在您接受该文件夹的工作区信任对话框后才应用它们。对话框列出了该文件夹将授予的规则和目录，以便您可以先查看它们。deny 和 ask 规则不受影响，因为它们仅限制。

Claude Code 根据您启动它的位置来保存和存储您接受的信任：

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

Claude Code 仅在交互式会话中显示信任对话框。claude -p 运行或 SDK 会话永远不会显示它，信任父文件夹不计入这些规则，因此在您信任文件夹之前运行什么说明了在这两种情况下 Claude Code 仍然使用哪些存储库内容。

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

.claude/settings.local.json 通常是您自己的文件，因此 Claude Code 应用其允许规则和其他目录而无需信任步骤。当该文件在 git 中被跟踪，或 .claude 是符号链接时，Claude Code 将其视为存储库提供的文件，并暂不应用其规则，直到您信任该文件夹为止。

Claude Code 运行 git 来区分两者，并且仅在您信任该文件夹后才运行 git：您接受了它或其父目录的信任对话框，其信任扩展到它，或您在 -p 或 SDK 会话中，这被视为已接受。在此之前，您启动 Claude Code 的位置决定了该文件规则会发生什么：

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

在版本 2.1.196 至 2.1.199 中，Claude Code 在您的配置主目录中和 git 存储库外也会暂不应用该文件的规则，并在那里打印this workspace has not been trusted警告。在 v2.1.207 之前，Claude Code 在您接受对话框之前应用未跟踪文件的规则。

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

每一行是存储库可以提供的一种内容。列是两种您尚未信任该文件夹本身的情况：您仅信任了父文件夹，或您在那里运行了 claude -p 或 SDK，这永远不会显示信任对话框。父文件夹列不适用于嵌套存储库内：在交互式会话中 Claude Code 为其显示信任对话框，claude -p 或 SDK 运行遵循 claude -p 列。

存储库提供的内容 您仅信任了父文件夹 claude -p 或 SDK，文件夹从未被信任
设置文件中的 Hooks、env 块和辅助命令（如 apiKeyHelper），以及项目技能的 hooks 和 allowed-tools 已使用 已使用。工作区信任在任何会话中都不会限制技能的 allowed-tools
.claude/settings.json 中的 permissions.allow 规则和 additionalDirectories 在您接受信任对话框之前不使用，对话框再次出现列出它们 不使用。Claude Code 向 stderr 打印 this workspace has not been trusted 警告
项目子代理中的 Frontmatter hooks、项目 @skills-dir 插件 和来自存储库或 --add-dir 目录的 extraKnownMarketplaces 条目 不使用，不提供对话框 不使用
来自存储库或 --add-dir 目录的子代理 frontmatter 中的内联 mcpServers。在 v2.1.238 之前，Claude Code 在两种情况下都加载这些服务器 不使用，不提供对话框 不使用
.mcp.json 中的服务器，包括存储库在其自己的设置中批准的服务器 Claude Code 在连接它们之前询问您。存储库自己的批准不计数 连接而不询问，无论是否批准。SDK 仅在 settingSources 包括项目设置时加载它们。同一文件夹中的 claude mcp list 仍然将此类服务器报告为待处理
.mcp.json 中服务器上的 headersHelper。在 v2.1.238 之前，Claude Code 在两种情况下都运行辅助程序 在您接受信任对话框之前不运行，对话框再次出现命名声明辅助程序的位置。Claude Code 仅使用其静态 headers 连接服务器直到那时 不运行。Claude Code 仅使用其静态 headers 连接服务器，并为每个服务器向 stderr 打印 headersHelper not run 行

对于需要此确切文件夹被信任的行，手动信任它：在 ~/.claude.json 中设置 projects["<path>"].hasTrustDialogAccepted 为 true，其中 <path> 是存储库根目录，或存储库外的文件夹本身。Claude Code 在跳过的子代理 hook 或内联 MCP 服务器的调试日志行中打印确切的键，在跳过的允许规则的 stderr 警告中，以及在跳过的辅助程序的 headersHelper not run 行中。

在您未编写的存储库中运行 claude -p 之前，决定它可能在您的机器上运行什么：

  • 传递 --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：自动化工作流并扩展权限评估