文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

工具参考

Claude Code 可以使用的工具的完整参考，包括权限要求和每工具行为。

Claude Code 可以访问一组内置工具，帮助它理解和修改你的代码库。工具名称是你在权限规则、subagent 工具列表和钩子匹配器中使用的确切字符串。要完全禁用工具，将其名称添加到你的权限设置中的 deny 数组。

要添加自定义工具，连接 MCP 服务器。要使用可重用的基于提示的工作流扩展 Claude，编写技能，它通过现有的 Skill 工具运行，而不是添加新的工具条目。

使用权限规则和钩子配置工具

大多数情况下，Claude 决定何时使用这些工具，你不需要在与 Claude 交互时自己命名它们。你在定义权限和其他配置时直接引用工具名称：

• 在设置中的 permissions.allow 和 permissions.deny 以及 /permissions 界面中
• 在 --allowedTools 和 --disallowedTools CLI 标志中
• 在 Agent SDK 的 allowedTools 和 disallowedTools 选项中
• 在 subagent 的 tools 或 disallowedTools frontmatter 中
• 在技能的 allowed-tools frontmatter 中
• 在钩子的 if 条件中

所有这些都接受相同的规则格式 ToolName(specifier)。限定符取决于工具，几个工具共享格式：

此处未列出的工具，如 ExitPlanMode 或 ShareOnboardingGuide，仅接受不带限定符的裸工具名称。

Edit(...) 允许规则也授予对相同路径的读取访问，因此你不需要匹配的 Read(...) 规则。

钩子 matcher 字段使用裸工具名称，而不是括号中的规则格式。参见匹配器模式了解匹配规则。每个工具传递给钩子中 tool_input 的字段名称，参见 PreToolUse 输入参考。

Agent 工具行为

Agent 工具在独立的上下文窗口中生成 subagent。Subagent 自主完成任务，然后向父对话返回单个文本结果。父级看不到 subagent 的中间工具调用或输出，只看到最终结果。要限制 subagent 运行的回合数，在 subagent 定义中设置 maxTurns。

同一个 Agent 工具在启用 fork 模式时也启动分叉 subagents。分叉继承完整的父对话而不是从头开始，始终在后台运行，并且仍在你的终端中显示权限提示。本节的其余部分描述命名的 subagents。

命名 subagent 可以使用哪些工具取决于 subagent 定义中的 tools 和 disallowedTools 字段：

• 两个字段都未设置：subagent 继承父级可用的每个工具。
• 仅 tools：subagent 仅获得列出的工具。
• 仅 disallowedTools：subagent 获得除列出的以外的每个父级工具。
• 两者都设置：disallowedTools 优先。同时列出的工具被移除。

启动 subagent 本身不会提示权限。Subagent 自己的工具调用在运行时根据你的权限规则进行检查：

• 前台 subagents 在每次工具调用发生时显示与你在主对话中看到的相同的权限提示。
• 后台 subagents 不显示提示。它们使用会话中已授予的权限运行，自动拒绝任何否则会提示的工具调用。拒绝后，subagent 在没有该工具的情况下继续运行。

要首先限制 subagent 可以访问的内容，缩小其 tools 字段，将 Bash 从列表中移除，或在你的设置中设置拒绝规则，如控制 subagent 能力中所述。关于前台和后台之间的选择，参见在前台或后台运行 subagents。

Bash 工具行为

Bash 工具在单独的进程中运行每个命令，具有以下持久性行为：

• 当 Claude 在主会话中运行 cd 时，新的工作目录会延续到后续的 Bash 命令，只要它保持在项目目录或你通过 --add-dir、/add-dir 或设置中的 additionalDirectories 添加的附加工作目录内。Subagent 会话从不延续工作目录更改。
  • 如果 cd 落在这些目录之外，Claude Code 重置到项目目录并在工具结果中附加 Shell cwd was reset to <dir>。
  • 要禁用此延续使每个 Bash 命令从项目目录开始，设置 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1。
• 环境变量不持久。一个命令中的 export 在下一个命令中不可用。
• Shell 启动文件中定义的别名和 shell 函数可用。在会话开始时，Claude Code 根据你的 shell 加载 ~/.zshrc、~/.bashrc 或 ~/.profile，捕获结果的别名、函数和 shell 选项，并将它们应用于每个 Bash 命令。

在启动 Claude Code 之前激活你的 virtualenv 或 conda 环境。要使环境变量在 Bash 命令之间持久化，在启动 Claude Code 之前设置 CLAUDE_ENV_FILE 为 shell 脚本，或使用 SessionStart 钩子动态填充它。

两个限制约束每个命令：

• 超时：默认两分钟。Claude 可以使用 timeout 参数请求每个命令最多 10 分钟。使用 BASH_DEFAULT_TIMEOUT_MS 和 BASH_MAX_TIMEOUT_MS 覆盖默认值和上限。
• 输出长度：默认 30,000 个字符。当命令产生超过该长度时，Claude Code 将完整输出保存到会话目录中的文件，并给 Claude 文件路径加上开头的简短预览。Claude 在需要其余部分时读取或搜索该文件。使用 BASH_MAX_OUTPUT_LENGTH 提高限制，硬上限为 150,000 个字符。

对于长时间运行的进程如开发服务器或监视构建，Claude 可以设置 run_in_background: true 将命令作为后台任务启动并在运行时继续工作。使用 /tasks 列出和停止后台任务。

Edit 工具行为

Edit 工具执行精确的字符串替换。它接受 old_string 和 new_string 并用第二个替换第一个。它不使用正则表达式或模糊匹配。

编辑要应用必须通过三个检查：

• 先读后编辑：Claude 必须在当前对话中读取了该文件，且该文件自那次读取以来在磁盘上未更改。此检查首先运行，在任何字符串匹配之前。
• 匹配：old_string 必须完全按写入的方式出现在文件中。一个字符的空白或缩进差异就足以导致未命中。
• 唯一性：old_string 必须恰好出现一次。当出现多次时，Claude 要么提供带有足够上下文的更长字符串来定位一次出现，要么设置 replace_all: true 替换所有出现。

当命令是 cat、head、tail 或对单个文件的 sed -n 'X,Yp'（无管道、重定向或其他标志）时，使用 Bash 查看文件也满足先读后编辑要求。管道输出和其他 Bash 命令不算，在这些情况下 Claude 必须在编辑前使用 Read。

这仅影响编辑资格，不影响权限。Read 和 Edit 拒绝规则也适用于 Claude Code 在 Bash 中识别的文件命令，如 cat、head、tail 和 sed，但不适用于间接读取或写入文件的任意子进程，如自行打开文件的 Python 或 Node 脚本。对于覆盖每个进程的操作系统级强制执行，启用沙箱。

Glob 工具行为

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

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

结果按修改时间排序，上限为 100 个文件。如果达到上限，Claude 在结果中看到截断标志并可以缩小模式。

Glob 默认不遵循 .gitignore，因此它在跟踪文件旁边找到 gitignore 文件。这与 Grep 不同，后者跳过 gitignore 文件。要使 Glob 遵循 .gitignore，在启动 Claude Code 之前设置 CLAUDE_CODE_GLOB_NO_IGNORE=false。

Grep 工具行为

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 工具行为

LSP 工具从运行的语言服务器为 Claude 提供代码智能。每次文件编辑后，它自动报告类型错误和警告，以便 Claude 无需单独的构建步骤即可修复问题。Claude 也可以直接调用它来导航代码：

• 跳转到符号的定义
• 查找符号的所有引用
• 获取位置的类型信息
• 列出文件或工作区中的符号
• 查找接口的实现
• 跟踪调用层次结构

在你为语言安装代码智能插件之前，该工具处于非活跃状态。插件捆绑语言服务器配置，你单独安装服务器二进制文件。

Monitor 工具

Monitor 工具让 Claude 在后台监视某些内容并在其发生变化时做出反应，而不暂停对话。要求 Claude：

• 尾随日志文件并在出现错误时标记
• 轮询 PR 或 CI 作业并在状态变化时报告
• 监视目录的文件更改
• 跟踪你指向的任何长时间运行的脚本的输出

Claude 为监视编写一个小脚本，在后台运行它，并在每行输出到达时接收它。你在同一会话中继续工作，当事件到达时 Claude 介入。通过要求 Claude 取消它或结束会话来停止监视。

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

插件可以声明在插件活跃时自动启动的监视器，而不是要求 Claude 启动它们。参见插件监视器。

NotebookEdit 工具行为

NotebookEdit 一次修改一个 Jupyter notebook 单元格，通过 cell_id 定位单元格。它不像 Edit 对普通文件那样跨 notebook 执行字符串替换。

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

• replace：覆盖单元格的源代码。这是默认值。
• insert：在目标之后添加新单元格。没有 cell_id 时，新单元格放在 notebook 的开头。需要 cell_type 设置为 code 或 markdown。
• delete：移除目标单元格。

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

PowerShell 工具

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 自动检测 PowerShell 7+ 的 pwsh.exe，回退到 PowerShell 5.1 的 powershell.exe。启用工具后，Claude 将 PowerShell 视为主要 shell。当安装了 Git Bash 时，Bash 工具仍然可用于 POSIX 脚本。

Claude Code 以 -ExecutionPolicy Bypass 在进程作用域生成 PowerShell，因此 .ps1 脚本和模块导入在默认 Windows 安装上工作而无需更改机器策略。进程作用域绕过不覆盖组策略 MachinePolicy 或 UserPolicy，因此企业锁定仍然适用。要改为遵循机器的有效执行策略，设置 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。

设置、钩子和技能中的 Shell 选择

三个额外设置控制 PowerShell 的使用位置：

• settings.json 中的 "defaultShell": "powershell"：通过 PowerShell 路由交互式 ! 命令。需要 PowerShell 工具已启用。
• 单个命令钩子上的 "shell": "powershell"：在 PowerShell 中运行该钩子。钩子直接生成 PowerShell，因此无论 CLAUDE_CODE_USE_POWERSHELL_TOOL 如何都有效。
• 技能 frontmatter 中的 shell: powershell：在 PowerShell 中运行 !`command` 块。需要 PowerShell 工具已启用。

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

预览限制

PowerShell 工具在预览期间有以下已知限制：

• 不加载 PowerShell 配置文件
• 在 Windows 上不支持沙箱化

Read 工具行为

Read 工具接受文件路径并返回带行号的内容。Claude 被指示始终传递绝对路径。

默认情况下，Read 从开头返回文件。当整文件读取超过令牌限制时，Read 返回第一页并附带 PARTIAL view 通知，告诉 Claude 它收到了多少文件内容以及如何使用 offset 和 limit 读取更多。传递显式 offset 或 limit 但仍超过令牌限制的读取返回错误。

Read 处理几种纯文本之外的文件类型：

• 图像：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送前调整大小并重新压缩大图像以适应模型的图像大小限制，因此 Claude 可能看到大屏幕的缩小版本。如果 Claude 在大图像中错过精细的像素级细节，要求它先裁剪感兴趣的区域，例如通过 Bash 使用 ImageMagick。
• PDF：Claude 完整读取短 .pdf 文件。对于超过 10 页的 PDF，使用 pages 参数按范围读取，例如 "1-5"，一次最多 20 页。
• Jupyter notebooks：.ipynb 文件返回所有单元格及其输出，包括代码、markdown 和可视化。

Read 仅读取文件，不读取目录。Claude 通过 Bash 工具使用 ls 列出目录内容。

WebFetch 工具行为

WebFetch 接受 URL 和描述要提取内容的提示。它获取页面，当服务器返回 HTML 时将响应转换为 Markdown，并使用小型快速模型对内容运行提示。对于大多数获取，Claude 接收该模型的回答，而不是原始页面。转换步骤不可配置。

这使 WebFetch 本质上是有损的。提取提示决定了什么到达 Claude，因此说页面未提及某事的结果可能只是意味着提示没有询问它。要求 Claude 使用更具体的提示再次获取，或通过 Bash 使用 curl 获取未处理的页面。

几个行为塑造 Claude 接收的响应：

• HTTP URL 自动升级到 HTTPS。
• 大页面在处理前被截断到固定的字符限制。
• 响应缓存 15 分钟，因此重复获取同一 URL 会快速返回。
• 当 URL 重定向到不同的主机时，WebFetch 返回命名原始 URL 和重定向目标的文本结果，而不是跟随它。Claude 然后使用第二次 WebFetch 调用获取新 URL。

在默认和 acceptEdits 权限模式下，WebFetch 在首次访问新域名时提示。要提前允许域名而不提示，添加如 WebFetch(domain:example.com) 的权限规则。auto 和 bypassPermissions 权限模式完全跳过提示。

WebFetch 设置以 Claude-User 开头的 User-Agent 头，以及优先选择 Markdown 而不是 HTML 的 Accept 头，以便支持内容协商的服务器可以直接返回 Markdown。沙箱网络规则单独配置，因此你希望沙箱化进程访问的域名仍然需要显式的沙箱权限规则。

WebSearch 工具行为

WebSearch 对 Anthropic 的 Web 搜索后端运行查询并返回结果标题和 URL。它不获取结果页面。要读取 Claude 在搜索结果中找到的页面，它使用 WebFetch 跟进。

该工具每次调用可能发出最多八次后端搜索，在返回结果之前内部优化搜索。Claude 可以使用 allowed_domains 限定结果仅包含某些主机，或使用 blocked_domains 排除它们。两个列表不能在单次调用中组合。

搜索后端不可配置。要使用不同的提供商搜索，添加暴露搜索工具的 MCP 服务器。

WebSearch 权限规则不需要限定符。allow 或 deny 中的裸 WebSearch 条目是唯一形式。

Write 工具行为

Write 工具创建新文件或用提供的完整内容覆盖现有文件。它不追加或合并。

如果目标路径已存在，Claude 必须在当前对话中至少读取了该文件一次才能覆盖它。对未读的现有文件的 Write 会以错误失败。此约束不适用于新文件。

使用 Bash 查看文件也满足此要求，遵循 Edit 工具行为中描述的相同规则。

对于现有文件的部分更改，Claude 使用 Edit 而不是 Write。

检查哪些工具可用

你的确切工具集取决于你的提供商、平台和设置。要检查运行中的会话加载了什么，直接询问 Claude：

你有哪些工具可用？

Claude 提供对话式摘要。对于确切的 MCP 工具名称，运行 /mcp。

另请参阅

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