Claude Code 工具名要原样写进权限规则、子代理工具列表和 hooks matcher；这页可直接查到每个内置工具的权限要求、禁用方式，以及 Bash、LSP、Monitor、PowerShell 的实际行为和限制。要启用自定义工具请连接 MCP，若要复用提示工作流则写 skill，它会通过现有 Skill 工具运行。

Claude Code 工具参考：权限配置与 Bash/LSP/PowerShell #

Claude Code 内置了一组工具，用来理解和修改你的代码库。工具名就是你在权限规则、子代理工具列表和 hooks matcher 里要填写的精确字符串。要彻底禁用某个工具，把它的名字加到权限设置里的 deny 数组。要添加自定义工具，连接 MCP。要扩展 Claude 的可复用 prompt 工作流，写 skill；skill 不会新增工具条目，而是通过现有的 Skill 工具执行。

工具一览 #

怎么用权限规则和 hooks 配置工具 #

大多数情况下，Claude 会自己判断何时使用这些工具，你不需要在对话里手工点名。只有在定义权限或其他配置时，才需要直接引用工具名：

• 在设置和 /permissions 界面中的 permissions.allow 和 permissions.deny
• 在 CLI 参数 --allowedTools 和 --disallowedTools 中
• 在 Agent SDK 的 allowedTools 和 disallowedTools 选项中
• 在子代理的 tools 或 disallowedTools frontmatter 中
• 在 skill 的 allowed-tools frontmatter 中
• 在 hook 的 if 条件 中

这些位置都接受同一种规则格式：ToolName(specifier)。specifier 取决于具体工具，部分工具共用同一套格式：

这里没列出的工具，比如 ExitPlanMode 或 ShareOnboardingGuide，只接受裸工具名，不带 specifier。

Edit(...) 的 allow 规则也会授予同一路径的读权限，所以不需要再额外写一条匹配的 Read(...)。

hook 的 matcher 字段用的是裸工具名，不是带括号的规则格式。匹配规则见 matcher patterns。各工具在 hook 的 tool_input 中会传哪些字段，见 PreToolUse input reference。

Agent tool behavior #

Agent 工具会在单独的上下文窗口里启动一个子代理。子代理独立完成任务，然后只把一条文本结果返回给主对话。主对话看不到子代理中途调用了哪些工具，也看不到中间输出，只能看到最终结果。要限制子代理最多运行多少轮，在 subagent definition 里设置 maxTurns。

在启用 fork mode 时，这个 Agent 工具也会启动 forked subagents。fork 会继承完整的父对话，而不是从头开始，并且始终在后台运行，但仍会在终端里显示权限提示。下面这部分描述的是命名子代理。

命名子代理能使用哪些工具，取决于 subagent definition 里的 tools 和 disallowedTools：

• 两个字段都不设置：子代理继承父级可用的所有工具
• 只设置 tools：子代理只能用列表里的工具
• 只设置 disallowedTools：子代理能用父级所有工具，但不能用被列出的那些
• 两个字段都设置：disallowedTools 优先生效。两边都出现的工具会被移除

启动子代理本身不会弹出权限请求。子代理自己的工具调用会在运行时按权限规则检查：

• 前台子代理：在每次工具调用发生时，显示和主对话一样的权限提示
• 后台子代理：不显示提示。它们只使用会话里已经授予的权限，并会自动拒绝任何本来会弹权限窗的工具调用。拒绝后，子代理会继续运行，只是不再使用那个工具

想从源头缩小子代理的可访问范围，可以收紧它的 tools 字段、把 Bash 排除在列表外，或在设置中加 deny 规则，参见 Control subagent capabilities。想了解前台和后台怎么选，参见 Run subagents in foreground or background。

Bash tool behavior #

Bash 工具会把每条命令放在独立进程中执行，持久化行为如下：

• 当 Claude 在主会话里执行 cd 时，只要新工作目录仍在项目目录或通过 --add-dir、/add-dir、additionalDirectories 加入的额外工作目录内，后续 Bash 命令会沿用这个目录。子代理会话不会继承工作目录变化。
  • 如果 cd 落到这些目录之外，Claude Code 会重置回项目目录，并在工具结果里追加 Shell cwd was reset to <dir>。
  • 如果要禁用这种沿用，让每条 Bash 命令都从项目目录开始，把 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 设为 1。
• 环境变量不会持久化。上一条命令里的 export 在下一条里不可用。

在启动 Claude Code 之前先激活 virtualenv 或 conda 环境。要让环境变量跨 Bash 命令持久化，可以在启动前把 CLAUDE_ENV_FILE 指向一个 shell 脚本，或者用 SessionStart hook 动态填充它。

每条命令都受两个限制：

• 超时：默认 2 分钟。Claude 可以通过 timeout 参数把单条命令延长到最多 10 分钟。默认值和上限可由 BASH_DEFAULT_TIMEOUT_MS 和 BASH_MAX_TIMEOUT_MS 覆盖。
• 输出长度：默认 30,000 字符。当命令输出超过这个上限时，Claude Code 会把完整输出保存到会话目录中的文件里，并把文件路径和开头的简短预览返回给 Claude。Claude 需要剩余内容时，会去读取或搜索这个文件。可用 BASH_MAX_OUTPUT_LENGTH 提高上限，最高 150,000 字符。

对 dev server、watch build 这类长时间运行的进程，Claude 可以设置 run_in_background: true 把命令作为后台任务启动，然后继续做别的事。可用 /tasks 查看和停止后台任务。

Edit tool behavior #

Edit 工具使用精确字符串替换。它接收 old_string 和 new_string，把前者替换成后者，不使用正则，也不做模糊匹配。

编辑能真正生效，需要同时通过三项检查：

• 先读后改：Claude 必须在当前对话中读过这个文件，而且自那次读取后文件在磁盘上没有变化。这个检查先于字符串匹配执行。
• 匹配：old_string 必须在文件中以完全相同的文本出现。只差一个空格或缩进都算失败。
• 唯一性：old_string 必须只出现一次。如果出现多次，Claude 要么提供更长的上下文把目标唯一定位，要么设置 replace_all: true 全部替换。

用 Bash 查看文件也能满足先读后改的要求，但前提是命令是对单个文件执行 cat、head、tail 或 sed -n 'X,Yp'，且没有管道、重定向或其他参数。带管道的输出和其他 Bash 命令不算，编辑前仍必须先用 Read。

这只影响编辑资格，不影响权限。Read 和 Edit 的 deny 规则 同样会作用于 Claude Code 能识别的 Bash 文件命令，比如 cat、head、tail 和 sed，但不会作用于 Python 或 Node 这类间接读写文件的子进程。若要在操作系统层面约束每个进程，请启用 sandbox。

Glob tool behavior #

Glob 工具按文件名模式查找文件，支持标准 glob 语法，包括用于递归目录匹配的 **：

• **/*.js 匹配任意深度下的所有 .js 文件
• src/**/*.ts 匹配 src/ 下的所有 .ts 文件
• *.{json,yaml} 匹配当前目录下的 .json 和 .yaml 文件

结果按修改时间排序，最多返回 100 个文件。如果触发上限，Claude 会在结果里看到 truncation 标记，并可以缩小模式范围。

Glob 默认不理会 .gitignore，所以会把被 gitignore 的文件和已跟踪文件一起找出来。这一点和 Grep 不同，后者会跳过 gitignore 文件。要让 Glob 遵守 .gitignore，在启动 Claude Code 前把 CLAUDE_CODE_GLOB_NO_IGNORE=false 设好。

Grep tool behavior #

Grep 工具在文件内容里搜索模式。Glob 是按文件名找文件，Grep 是在文件内部找行。

Grep 基于 ripgrep，使用的是 ripgrep 的正则语法，不是 POSIX grep。包含正则元字符的模式需要转义。比如在 Go 代码里查找 interface{}，模式要写成 interface\{\}。

三种输出模式控制返回内容：

• files_with_matches：只返回文件路径，不返回行内容。默认值。
• content：返回匹配行、文件名和行号。
• count：返回每个文件的匹配次数。

Claude 可以用 glob 参数按文件范围缩小结果，比如 **/*.tsx；也可以用 type 参数按语言缩小，比如 py 或 rust。默认情况下，模式只匹配单行。Claude 可以设置 multiline: true 让匹配跨行。

Grep 会遵守 .gitignore，所以会跳过 gitignore 文件。要搜索被 gitignore 的文件，Claude 会直接传入它的路径。

LSP tool behavior #

LSP 工具通过运行中的语言服务器给 Claude 提供代码智能。每次文件编辑后，它会自动报告类型错误和警告，这样 Claude 不需要单独跑构建步骤也能修问题。Claude 也可以直接调用它来导航代码：

• 跳到某个符号的定义
• 查找某个符号的所有引用
• 获取某个位置的类型信息
• 列出文件或工作区里的符号
• 查找接口的实现
• 追踪调用层级

安装适用于你语言的代码智能插件后，工具才会生效。插件会打包语言服务器配置，语言服务器二进制需要单独安装。

Monitor tool #

Monitor 工具需要 Claude Code v2.1.98 或更高版本。

Monitor 工具让 Claude 在后台盯住某个对象，发生变化时立即响应，而不必暂停对话。你可以让 Claude：

• 盯日志文件，错误出现时及时标记
• 轮询 PR 或 CI 任务，并在状态变化时汇报
• 监控某个目录的文件变化
• 跟踪你指定的任意长时间运行脚本输出

Claude 会为这个监控写一个小脚本，在后台运行，并在每一行输出到达时接收它。你可以继续在同一个会话里工作，事件一到，Claude 就会插话。要停止 monitor，可以让 Claude 取消它，或者结束会话。

Monitor 使用与 Bash 相同的权限规则，所以你为 Bash 设置的 allow 和 deny 模式也同样适用。它在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上不可用；当设置了 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 时也不可用。

插件可以声明 monitor，并在插件激活时自动启动，而不需要先让 Claude 主动创建。参见 plugin monitors。

NotebookEdit tool behavior #

NotebookEdit 会按 cell_id 一次修改一个 Jupyter notebook 单元格。它不会像 Edit 那样在整个 notebook 上做字符串替换。

三种编辑模式控制对目标单元格的操作：

• replace：覆盖单元格源码，默认模式
• insert：在目标后插入新单元格；如果没有 cell_id，新单元格插入到 notebook 开头。需要把 cell_type 设为 code 或 markdown
• delete：删除目标单元格

权限规则使用 Edit(...) 的路径格式。像 Edit(notebooks/**) 这样的规则，会覆盖该目录下的 NotebookEdit 调用。

PowerShell tool #

PowerShell 工具让 Claude 原生运行 PowerShell 命令。在 Windows 上，这意味着命令直接在 PowerShell 中执行，而不是转到 Git Bash。没有安装 Git Bash 的 Windows 会自动启用；装了 Git Bash 的 Windows 会逐步开放；Linux、macOS 和 WSL 上则需要手动开启。

怎么启用 PowerShell 工具 #

在环境变量或 settings.json 中设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1：

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

在 Windows 上，把该变量设为 0 可退出逐步开放。Linux、macOS 和 WSL 需要 PowerShell 7 或更高版本：安装 pwsh 并确保它在 PATH 里。

Windows 上，Claude Code 会自动检测 pwsh.exe（PowerShell 7+），并回退到 powershell.exe（PowerShell 5.1）。启用该工具后，Claude 会把 PowerShell 当作主 shell。若安装了 Git Bash，Bash 工具仍然可用于 POSIX 脚本。

Claude Code 启动 PowerShell 时会在进程级别使用 -ExecutionPolicy Bypass，因此在默认 Windows 安装上，.ps1 脚本和模块导入无需修改系统策略就能工作。进程级 bypass 不会覆盖 Group Policy 的 MachinePolicy 或 UserPolicy，企业级锁定仍然生效。若想改为遵循机器当前的有效执行策略，设置 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。

在 settings、hooks 和 skills 中选择 shell #

三个额外设置控制 PowerShell 在哪里使用：

• settings.json 中 "defaultShell": "powershell"：把交互式 ! 命令路由到 PowerShell。需要先启用 PowerShell 工具。
• 单个 command hooks 中的 "shell": "powershell"：让该 hook 在 PowerShell 中运行。hooks 直接启动 PowerShell，因此不管 CLAUDE_CODE_USE_POWERSHELL_TOOL 是否启用都有效。
• skill frontmatter 中的 shell: powershell：让该 skill 里的 !`command` 块用 PowerShell 执行。需要先启用 PowerShell 工具。

Bash 工具部分提到的主会话工作目录重置行为，同样适用于 PowerShell 命令，包括 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 这个环境变量。

预览版限制 #

PowerShell 工具有这些已知限制：

• PowerShell profiles 不会加载
• 在 Windows 上不支持 sandboxing

Read tool behavior #

Read 工具接收文件路径，并返回带行号的内容。Claude 会被要求始终传绝对路径。

默认情况下，Read 从文件开头读取。若整文件读取超过 token 上限，Read 会返回第一页，并带有 PARTIAL view 提示，说明已收到多少内容，以及如何通过 offset 和 limit 读取更多内容。若显式传入了 offset 或 limit，但仍然超过 token 上限，则会返回错误。

Read 还支持普通文本之外的几类文件：

• 图片：PNG、JPG 和其他图片格式会以视觉内容返回，Claude 能“看到”它，而不是读取原始字节。Claude Code 会先把大图缩放并重新压缩到模型的图片尺寸限制以内再发送，所以 Claude 可能看到的是缩小版截图。如果 Claude 在大图里看不到细节，可以让它先裁剪感兴趣区域，例如通过 Bash 调用 ImageMagick。
• PDF：短于 10 页的 .pdf 会整份读取；超过 10 页的 PDF 会使用 pages 参数按范围读取，例如 "1-5"，每次最多 20 页。
• Jupyter notebooks：.ipynb 文件会返回所有单元格及其输出，包括代码、markdown 和可视化结果。

Read 只读文件，不读目录。列目录内容要用 Bash 的 ls。

WebFetch tool behavior #

WebFetch 接收一个 URL 和一段描述要提取什么内容的 prompt。它会抓取页面，在服务器返回 HTML 时把响应转换成 Markdown，然后用一个小而快的模型基于内容执行 prompt。大多数情况下，Claude 拿到的是这个模型的答案，而不是原始网页。转换步骤不可配置。

这意味着 WebFetch 天生会丢信息。最终 Claude 看到什么，取决于提取 prompt；如果结果说页面没提到某事，往往只代表 prompt 没有问到这点。可以让 Claude 带更具体的 prompt 再抓一次，或者用 Bash 里的 curl 直接拿未加工的页面。

下面这些行为会影响 Claude 最终收到的结果：

• HTTP URL 会自动升级为 HTTPS
• 大页面在处理前会被截断到固定字符上限
• 同一个 URL 的响应会缓存 15 分钟，所以重复抓取会很快
• 当 URL 重定向到不同主机时，WebFetch 不会继续跟随，而是返回一段文本，说明原始 URL 和重定向目标。然后 Claude 再用第二次 WebFetch 去抓新 URL

在默认和 acceptEdits 权限模式下，WebFetch 第一次访问新域名时会弹权限提示。要预先放行某个域名，可以加一条类似 WebFetch(domain:example.com) 的权限规则。auto 和 bypassPermissions 权限模式 会直接跳过提示。

WebFetch 会设置一个以 Claude-User 开头的 User-Agent 头，以及一个偏好 Markdown 而不是 HTML 的 Accept 头，因此支持内容协商的服务器可以直接返回 Markdown。Sandbox 的网络规则是分开配置的，所以即使你想让 sandboxed 进程访问某个域名，也仍然需要单独的 sandbox 权限规则。

WebSearch tool behavior #

WebSearch 会把查询发到 Anthropic 的 web search 后端，并返回结果标题和 URL，不会抓取结果页。要读取搜索结果里的页面，Claude 会继续调用 WebFetch。

该工具单次调用最多会发起 8 次后端搜索，并在返回前在内部不断细化查询。Claude 可以用 allowed_domains 只保留特定主机，或者用 blocked_domains 排除特定主机。两者不能在同一次调用里同时使用。

搜索后端不可配置。要用其他搜索提供商，可以添加一个暴露 search 工具的 MCP 服务器。

WebSearch 的权限规则不带 specifier。只要在 allow 或 deny 里写裸 WebSearch 即可。

WebSearch 可用于 Claude API 和 Microsoft Foundry。在 Google Cloud Vertex AI 上，它可与 Claude 4 模型一起使用，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不提供服务端 web search 工具。

Write tool behavior #

Write 工具会根据提供的完整内容创建新文件，或覆盖已有文件。它不会追加，也不会合并。

如果目标路径已经存在，Claude 必须在当前对话中至少读过这个文件一次，才能覆盖它。对未读过的已有文件执行 Write 会报错。这个限制不适用于新文件。

用 Bash 查看文件，在满足 Edit tool behavior 里相同规则的前提下，也能满足这个要求。

如果只是对已有文件做局部修改，Claude 会使用 Edit，而不是 Write。

怎么查看当前可用工具 #

你的工具集合取决于提供商、平台和设置。要查看当前会话加载了哪些工具，直接问 Claude：

What tools do you have access to?

Claude 会给出一段自然语言总结。要查看精确的 MCP 工具名，运行 /mcp。

相关文档 #

• MCP：连接外部服务器添加自定义工具
• 权限：权限系统、规则语法和工具特定模式
• 子代理：为子代理配置工具访问
• Hooks：在工具执行前后运行自定义命令

常见问题 #

Claude Code 的工具名要怎么写到权限里？ #

直接使用工具名原文，比如 Bash、Edit、WebFetch(domain:example.com)。像 Read、Grep、Glob、LSP 这类路径型规则要写成 Read(/path/**) 这种格式；不带 specifier 的工具就只能写裸名称。

为什么我设置了 allow，Edit 还是会失败？ #

Edit 需要同时满足三项条件：当前对话里已经读过目标文件、old_string 在文件里完全匹配、且该字符串只出现一次。只要空格、缩进或文件内容在磁盘上有变化，编辑就会失败。

如何查看 Claude Code 当前会用到哪些工具？ #

在会话里直接问 Claude：What tools do you have access to?。如果你要看精确的 MCP 工具名，再运行 /mcp。