Claude Code 深度学习手册

主题

工具参考（完整工具表/LSP/monitor） ​

Claude Code 全部内置工具的权威清单与逐工具行为/权限说明，工具名即写权限规则、subagent、hook、skill 时使用的精确字符串。

是什么 ​

这是 Claude Code 官方的「Tools reference」页面，列出 Claude Code 可用的全部内置工具，并逐工具说明其行为与权限要求。工具名是写 permission 规则、subagent tools 列表、hook matcher、skill allowed-tools 时使用的精确字符串。页面包含一张完整工具表（含每个工具是否需要 Permission），以及 Agent/Bash/Edit/Glob/Grep/LSP/Monitor/NotebookEdit/PowerShell/Read/WebFetch/WebSearch/Write 等逐工具的详细行为说明。

怎么工作 ​

  • 完整工具表是权威清单：表里的工具名就是写 permission 规则、subagent tools 列表、hook matcher 时要用的精确字符串。要彻底禁用某工具，把名字加到 permission settings 的 deny 数组。
  • 新增自定义工具靠连接 MCP server；想扩展可复用的 prompt 工作流则写 skill —— skill 通过既有的 Skill 工具运行，不会新增工具条目。
  • 权限规则统一格式 ToolName(specifier)，specifier 因工具而异。多个工具共用一种格式（如 Read/Grep/Glob/LSP 共用路径匹配 Read(...)，Edit/Write/NotebookEdit 共用 Edit(...)，Bash/Monitor 共用 Bash(...) 命令匹配）。Edit(...) 的 allow 规则同时授予同路径读权限。
  • Agent 工具在独立 context window 里跑 subagent，自主完成任务后只把一段文本结果返回父对话，父对话看不到中间的工具调用/输出。前台 subagent 会照常弹权限提示；后台 subagent 不弹提示，用会话已授予的权限运行，遇到本会弹窗的调用直接 auto-deny 后继续。
  • Bash 每条命令在独立进程跑：主会话 cd 会延续到后续命令（只要落在项目目录或 --add-dir 加的目录内），落到目录外会重置回项目目录并在结果追加 Shell cwd was reset to <dir>；环境变量不延续；启动时 source ~/.zshrc/~/.bashrc/~/.profile 捕获 alias/函数/shell 选项并应用到每条命令。
  • Edit 是精确字符串替换（非 regex/非模糊）。要通过三道检查：read-before-edit（必须在当前对话读过该文件且磁盘未变动，最先检查）、Match（old_string 须逐字出现，连一个空白/缩进差异都会 miss）、Uniqueness（须唯一出现，否则要么给更长上下文锁定，要么 replace_all: true 全替）。
  • LSP 由运行中的 language server 提供代码智能：每次文件编辑后自动报 type errors/warnings，让 Claude 不用单独 build 就能改；也可直接调用做跳转定义、查引用、取类型信息、列文件/工作区符号、查接口实现、追调用层级。
  • Monitor 让 Claude 在后台盯一个东西并在变化时插话而不中断对话：Claude 写一个小脚本在后台跑，每产生一行输出就回传给它。典型用途：tail 日志标记报错、轮询 PR/CI 状态、监视目录文件变化、跟踪长跑脚本输出。
  • WebFetch 取 URL 后把 HTML 转 Markdown，再用一个小而快的模型按 prompt 抽取——多数情况下 Claude 拿到的是该模型的答案而非原始页面，因此是 lossy by design；prompt 决定了能传回什么。HTTP 自动升级 HTTPS；跨 host 重定向不自动跟随，而是返回原始/目标 URL 让 Claude 第二次 fetch。
  • WebSearch 走 Anthropic 的 web search backend，只返回标题和 URL，不抓页面正文；要读正文需再用 WebFetch。单次调用内部最多发起 8 次后台搜索来精炼结果。

怎么配置 / 用法 ​

权限/配置位置与语法（均引用官方原文）：

  1. 在哪里引用工具名（都用 ToolName(specifier) 规则格式）：
  • settings 的 permissions.allow / permissions.deny，以及 /permissions 界面
  • CLI flag：--allowedTools / --disallowedTools
  • Agent SDK 的 allowedTools / disallowedTools
  • subagent frontmatter 的 tools / disallowedTools
  • skill frontmatter 的 allowed-tools
  • hook 的 if 条件
  1. 规则格式对照（specifier 因工具而异，多个工具共用同一格式）：
  • Bash(npm run *) → Bash, Monitor（命令模式匹配）
  • PowerShell(Get-ChildItem *) → PowerShell
  • Read(~/secrets/**) → Read, Grep, Glob, LSP（路径匹配）
  • Edit(/src/**) → Edit, Write, NotebookEdit（路径匹配）
  • Skill(deploy *) → Skill
  • Agent(Explore) → Agent
  • WebFetch(domain:example.com) → WebFetch
  • WebSearch → 无 specifier，整工具 allow/deny
  1. 禁用某工具：把工具名加进 permission settings 的 deny 数组。
  2. hook 的 matcher 字段用裸工具名，不是带括号的规则格式。
  3. Edit(...) 的 allow 规则同时授予同路径的读权限，无需再写 Read(...)。

LSP 启用：需为对应语言安装 code intelligence plugin（plugin 自带 language server 配置，server 二进制需另行单独安装），未装前 LSP 处于 inactive。

Monitor 启用前提：需 Claude Code v2.1.98+；复用 Bash 的权限规则；当设置了 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 时不可用；Plugin 可声明随插件激活自动启动的 monitor（见 plugin monitors）。

PowerShell 启用：

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

Windows 设 0 退出 rollout；Linux/macOS/WSL 需 PowerShell 7+（装 pwsh 并加入 PATH）。相关 shell 选择设置：settings.json 的 "defaultShell": "powershell"、command hook 的 "shell": "powershell"、skill frontmatter 的 shell: powershell。尊重机器执行策略：CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。

查看当前会话已加载哪些工具：直接问 Claude "What tools do you have access to?"；MCP 精确名用 /mcp。

什么时候用 ​

  • 想精确控制或禁用某工具的权限时，用工具表的精确工具名写进 permissions/CLI flag/subagent/hook/skill 配置。
  • 用 LSP 做代码导航与编辑后自动报错——前提是已装对应语言的 code intelligence plugin。
  • 用 Monitor 后台盯日志/CI/目录并在事件发生时让 Claude 插话——前提 v2.1.98+ 且非 Bedrock/Vertex/Foundry、未开 DISABLE_TELEMETRY。
  • 抓网页用 WebFetch（lossy，需原始页面改用 curl）；只要检索标题+URL 用 WebSearch（读正文再接 WebFetch）。
  • 别用 Read 读目录（用 Bash ls）；部分修改用 Edit 而非 Write。

限制 / 坑 ​

  • Bash 超时默认 2 分钟，Claude 可用 timeout 参数请求最多 10 分钟；可用 BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS 覆盖默认值与上限。
  • Bash 输出长度默认 30,000 字符，超出会把完整输出存到 session 目录文件并只给 Claude 文件路径+开头预览；可用 BASH_MAX_OUTPUT_LENGTH 调高，硬上限 150,000 字符。
  • Bash 环境变量不跨命令持久；export 在下一条命令不可用。要持久化需用 CLAUDE_ENV_FILE 或 SessionStart hook。
  • Glob 结果按修改时间排序且最多 100 个文件；命中上限会给 truncation flag。默认不遵守 .gitignore（会同时找到被忽略文件），设 CLAUDE_CODE_GLOB_NO_IGNORE=false 才遵守。
  • Grep 基于 ripgrep（非 POSIX grep），正则元字符需转义（如找 interface{} 要写 interface{}）；遵守 .gitignore，被忽略文件会跳过（需直接传路径才能搜）。
  • Edit 单字符空白/缩进差异即匹配失败；old_string 多次出现会因 uniqueness 失败。Bash 里只有 cat/head/tail/sed -n 'X,Yp' 对单文件且无管道/重定向/其他 flag 才满足 read-before-edit。
  • LSP 在装对应语言 code intelligence plugin 之前 inactive；plugin 只带配置，server 二进制要单独装。
  • Monitor：需 v2.1.98+；不可用于 Amazon Bedrock / Google Vertex AI / Microsoft Foundry；设了 DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 时不可用。
  • Read：整文件读超 token 限制会返回首页加 PARTIAL view 提示；若已显式传 offset/limit 仍超限则返回 error。PDF 超过 10 页要用 pages 参数分段读，每次最多 20 页。大图会被缩放/重压，可能看不清像素级细节。Read 不读目录。
  • WebFetch：lossy by design——结果说页面没提到某事，可能只是 prompt 没问到；HTTP 强制升 HTTPS；大页面会被截断到固定字符上限；响应缓存 15 分钟；跨 host 重定向不自动跟随。HTML→Markdown 转换步骤不可配置。
  • WebSearch：单次最多 8 次后台搜索；allowed_domains 与 blocked_domains 不能在同一次调用里组合；搜索 backend 不可配置；权限规则无 specifier。WebSearch 在 Amazon Bedrock 不提供 server-side web search。
  • PushNotification / RemoteTrigger / ScheduleWakeup / Monitor 的推送/路由走 Anthropic 托管基础设施，无法从 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 访问。
  • PowerShell 预览期限制：不加载 PowerShell profiles；Windows 上不支持 sandboxing。
  • TodoWrite 自 v2.1.142 起默认禁用（改用 TaskCreate/TaskGet/TaskList/TaskUpdate），设 CLAUDE_CODE_ENABLE_TASKS=0 可重新启用。TaskOutput 已废弃，改用 Read 读任务输出文件路径。

硬事实速查（27 条） ​

  • 需要 Permission 的工具（表中 Permission Required = Yes）：Bash、Edit、ExitPlanMode、Monitor、NotebookEdit、PowerShell、ShareOnboardingGuide、Skill、WebFetch、WebSearch、Workflow、Write。其中 Workflow = 跑一个动态工作流（后台编排多个 subagent 的脚本，返回一份合并结果）。
  • 不需要 Permission（No）的工具包括：Agent、AskUserQuestion、CronCreate、CronDelete、CronList、EnterPlanMode、EnterWorktree、ExitWorktree、Glob、Grep、ListMcpResourcesTool、LSP、PushNotification、Read、ReadMcpResourceTool、RemoteTrigger、ScheduleWakeup、SendMessage、TaskCreate、TaskGet、TaskList、TaskOutput、TaskStop、TaskUpdate、TeamCreate、TeamDelete、TodoWrite、ToolSearch、WaitForMcpServers。
  • 权限规则统一格式：ToolName(specifier)。
  • 规则共用关系：Bash(...) 适用 Bash 和 Monitor；Read(...) 适用 Read/Grep/Glob/LSP；Edit(...) 适用 Edit/Write/NotebookEdit。
  • Edit(...) 的 allow 规则同时授予同路径读权限，不需另写 Read(...)。
  • Bash 超时默认 2 分钟，最高 10 分钟；env 变量：BASH_DEFAULT_TIMEOUT_MS、BASH_MAX_TIMEOUT_MS。
  • Bash 输出默认 30,000 字符，硬上限 150,000 字符；env：BASH_MAX_OUTPUT_LENGTH。
  • Bash cd 越界重置时追加文本：Shell cwd was reset to <dir>；禁用 cd 延续：CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1。
  • Bash 启动 source 的文件：~/.zshrc、~/.bashrc、~/.profile（按 shell 而定）。env：CLAUDE_ENV_FILE 用于持久化环境变量。
  • Glob 结果上限 100 个文件，按修改时间排序；env：CLAUDE_CODE_GLOB_NO_IGNORE=false 使其遵守 .gitignore。
  • Grep 基于 ripgrep；三种 output mode：files_with_matches（默认）、content、count；参数 glob、type、multiline: true；可用 type 如 py、rust。
  • Edit 三道检查：read-before-edit、Match、Uniqueness；多匹配可用 replace_all: true。
  • 满足 read-before-edit 的 Bash 命令：cat、head、tail、sed -n 'X,Yp'（单文件、无管道/重定向/其他 flag）。
  • LSP 需安装 code intelligence plugin；server 二进制单独安装；编辑后自动报 type errors/warnings。
  • Monitor 需 Claude Code v2.1.98 或更高；复用 Bash 权限规则；不可用于 Bedrock/Vertex/Foundry；DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 设置时不可用。
  • NotebookEdit 按 cell_id 定位；三种 edit mode：replace（默认）、insert（需 cell_type 为 code 或 markdown，无 cell_id 时插到笔记本开头）、delete；权限用 Edit(...) 路径格式（如 Edit(notebooks/**)）。
  • PowerShell：启用 env CLAUDE_CODE_USE_POWERSHELL_TOOL=1（可写在 settings.json env）；Linux/macOS/WSL 需 PowerShell 7+（pwsh 在 PATH）；spawn 时用 -ExecutionPolicy Bypass（process scope）；尊重机器策略用 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1；Windows 自动探测 pwsh.exe（7+）回退 powershell.exe（5.1）。
  • PowerShell 相关设置：settings.json 的 defaultShell: powershell；command hook 的 shell: powershell；skill frontmatter 的 shell: powershell。
  • Read：PDF 超 10 页用 pages 参数（如 "1-5"），每次最多 20 页；超 token 限制返回 PARTIAL view 提示，用 offset/limit 续读。
  • WebFetch：HTTP 自动升 HTTPS；响应缓存 15 分钟；跨 host 重定向返回 URL 不自动跟随；User-Agent 以 Claude-User 开头，Accept header 优先 Markdown；默认与 acceptEdits 模式下首次访问新域名会提示，auto 与 bypassPermissions 模式跳过提示；预先放行域名用 WebFetch(domain:example.com)。
  • WebSearch：单次最多 8 次后台搜索；参数 allowed_domains、blocked_domains（不可在同一次调用组合）；权限规则无 specifier（只能裸 WebSearch）；在 Vertex AI 需 Claude 4 模型（Opus/Sonnet/Haiku），Amazon Bedrock 不提供。
  • TodoWrite：自 v2.1.142 默认禁用，env CLAUDE_CODE_ENABLE_TASKS=0 重新启用；WaitForMcpServers 标注 min-version 2.1.142。
  • TaskOutput 已废弃，改用 Read 读任务输出文件路径；TaskStop 按 ID 杀后台任务；后台任务用 /tasks 列出与停止。
  • Agent 工具 maxTurns 在 subagent 定义里设；tools/disallowedTools 同时设时 disallowedTools 优先。
  • SendMessage、TeamCreate、TeamDelete 仅在 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 时可用。
  • CronCreate 任务为 session-scoped，--resume 或 --continue 未过期会恢复。
  • 查看已加载工具：问 Claude；MCP 精确名用 /mcp 命令。

官方出处：https://code.claude.com/docs/en/tools-reference