Claw Code 工具：19 个内置 AI 代理工具完整参考

claw code 工具是 AI 代理与开发者环境交互的主要机制。定义在 rust/crates/tools/src/lib.rs 中，每个工具注册为包含名称、描述和 JSON input_schema 的 ToolSpec。在运行时，代理根据当前任务选择工具，框架验证输入、检查权限、执行工具并返回结构化结果。本页记录了所有 19 个内置工具、Python 编排层、ToolPool 组装流程和权限门控架构。

工具架构概述

claw code 工具遵循一致的生命周期：LLM 发出指定工具名称和 JSON 输入的 tool_use 内容块，运行时根据工具的 input_schema 验证输入，权限引擎检查调用是否被允许，工具执行，结果作为 tool_result 内容块返回给 LLM。此架构分为两层：

• Rust 层（rust/crates/tools/src/lib.rs）— 定义 19 个带 JSON schema 和执行逻辑的 ToolSpec 注册
• Python 层（src/tools.py、src/tool_pool.py）— 处理工具发现、过滤、池组装和编排层的垫片执行

每个工具在 Rust crate 中遵循统一模式：解析 LLM 的 JSON 输入，根据 schema 验证必需和可选字段，通过 PermissionEngine 检查权限，执行操作，并返回类型化的结果结构体。这种一致性使得添加新工具或修改现有工具变得简单，而不会影响系统的其余部分。

Shell 执行工具

1. bash — Shell 命令执行

bash 工具是 claw code 工具套件中最强大且权限门控最严格的工具。它在沙盒环境中执行任意 shell 命令，捕获 stdout、stderr 和退出码。

输出是一个 BashCommandOutput 结构体，包含 stdout、stderr、return_code_interpretation、interrupted 标志（命令因超时被终止时设置）和可选的用于后台命令的 background_task_id。

19. PowerShell — Windows Shell 执行

PowerShell 工具提供 Windows 原生 shell 执行。它接受两个参数：command（要执行的 PowerShell 命令）和可选的 timeout（毫秒）。这是一个条件工具——仅在 Windows 平台上可用——并提供与 bash 工具相同的沙盒执行。

文件操作工具

2. read_file — 带偏移/限制的文件读取

read_file 工具从本地文件系统读取文件，支持可选的 offset 和 limit 参数，实现大文件的高效部分读取。

该工具支持读取文本文件、图像（PNG、JPG——以视觉方式呈现给多模态 LLM）、PDF 文件（对大文档使用 pages 参数）和 Jupyter 笔记本（.ipynb 文件，包含所有单元格和输出）。输出以 cat -n 格式返回，行号从 1 开始。

3. write_file — 文件创建和覆盖

write_file 工具创建新文件或覆盖现有文件。它需要绝对 file_path 和要写入的完整 content。输出包括 structured_patch 和 git_diff，便于精确审查更改内容。此工具受权限门控——代理必须拥有目标路径的写入权限。

4. edit_file — 字符串替换编辑

edit_file 工具在文件内执行精确的字符串替换。代理不是重写整个文件，而是指定要查找的 old_string 和要替换的 new_string。这种方法最大限度地降低了意外数据丢失的风险，并产生干净、可审查的差异。

一个关键的设计决策：如果 old_string 在文件中不唯一，编辑将失败（除非 replace_all 为 true）。这迫使代理提供足够的周围上下文来明确标识编辑位置，防止意外修改文件的错误部分。

13. NotebookEdit — Jupyter 单元格编辑

NotebookEdit 工具处理 Jupyter 笔记本单元格编辑。它支持四个命令：replace（覆盖单元格内容）、insert_above（在给定索引上方添加新单元格）、insert_below（在给定索引下方添加新单元格）和 delete（删除单元格）。每个命令接受 cell_type（code 或 markdown）、标识目标单元格的 index 和可选的 content。

搜索和发现工具

5. glob_search — 文件模式匹配

glob_search 工具提供跨整个代码库的快速文件模式匹配。它接受 pattern（如 **/*.ts、src/**/*.rs）和可选的 path 来限制搜索目录。结果按修改时间排序，截断为 100 个文件以防止过多输出。

6. grep_search — 正则内容搜索

grep_search 工具基于 ripgrep 构建，提供跨代码库的强大正则内容搜索。它是代码探索和调试期间最常被调用的 claw code 工具之一。

三种输出模式用途不同：files_with_matches 最适合定位包含模式的文件，content 显示实际匹配行及可选上下文，count 提供每个文件的匹配计数。type 参数使用 ripgrep 的内置文件类型定义，对于标准文件类型比 glob 过滤更高效。

12. ToolSearch — 延迟工具发现

ToolSearch 工具搜索尚未完全加载到代理上下文中的延迟工具。它接受 query 字符串和可选的 max_results 参数（默认：5）。查询形式包括精确选择（select:Read,Edit,Grep）、关键词搜索和名称必需搜索（+slack send）。匹配后返回完整的 JSON schema 定义，以便立即调用发现的工具。

Web 交互工具

7. WebFetch — URL 内容获取

WebFetch 工具从 URL 获取内容并连同提示一起传递给代理。这使代理能够在任务执行期间阅读文档、检查 API 响应和从网络收集信息。所有 URL 都受权限系统的网络访问规则约束。

8. WebSearch — 带域名过滤的网络搜索

WebSearch 工具执行带可选域名过滤的网络搜索。代理可以将结果限制在特定域名（如仅在文档站点内搜索）以提高相关性。结果作为代理可以解析和处理的结构化数据返回。

代理编排工具

11. Agent — 子代理启动器

Agent 工具启动子代理进行并行任务执行。子代理在隔离的上下文中运行，可以配置不同的模型和能力。

子代理继承父代理的权限上下文，但在自己的对话线程中运行。isolation: "worktree" 选项创建单独的 git worktree，允许子代理进行文件更改而不干扰父代理的工作目录。这对于多个代理同时修改文件的并行开发任务至关重要。

10. Skill — 技能定义加载器

Skill 工具加载提供专业领域知识和能力的预定义技能定义。它接受 skill 名称和可选的 args。技能是将多个工具调用组合成结构化工作流的高级抽象——例如，一个"commit"技能可以按顺序暂存更改、起草提交消息和创建提交。

任务和会话管理工具

9. TodoWrite — 任务列表管理

TodoWrite 工具管理代理的内部任务列表。它接受 todos 数组，每个项目包含：

• id — 任务的唯一标识符
• content — 任务描述
• status — pending、in_progress 或 completed 之一
• priority — high、medium 或 low 之一

代理使用此工具跟踪多步骤任务、标记进度，并确保在复杂操作中不遗漏任何事项。

14. Sleep — 执行暂停

Sleep 工具在不占用 shell 进程的情况下暂停执行指定时长。它接受单个参数：duration_ms（毫秒）。与通过 bash 工具运行 sleep 不同，此专用工具不占用 shell 资源槽，是等待外部进程时引入延迟的首选方式。

15. SendUserMessage — 用户通信

SendUserMessage 工具向用户发送带可选附件的消息。它接受 message 字符串、attachments 数组和 status 字段（normal 或 proactive）。proactive 状态表示代理正在提供主动信息，如长时间运行任务期间的进度更新。

16. Config — 运行时设置

Config 工具在运行时读写代理配置设置。它支持三个字段：action（get 或 set）、key（设置名称）和 value（用于 set 操作）。这允许代理检查自己的配置并进行调整，无需重启。

17. StructuredOutput — JSON 数据返回

StructuredOutput 工具向调用者返回结构化 JSON 数据。它接受包含任何有效 JSON 值的单个 data 参数。当代理需要返回机器可解析的结果而非自然语言时使用——例如，将找到的问题列表作为 JSON 数组返回以供下游处理。

18. REPL — 语言 REPL 执行

REPL 工具在特定语言的 REPL 环境中执行代码。它接受 language 参数（标识运行时）和 code 参数（要执行的代码）。与 bash 工具不同，REPL 在同一会话内的调用之间保持状态，适合探索性编程和迭代数据分析。

Python 工具层

claw code 工具系统的 Python 端定义在 src/tools.py 中，提供桥接 LLM 工具调用和 Rust 执行引擎的编排层。

ToolExecution 数据类

每次工具调用都作为 ToolExecution 数据类进行跟踪，包含以下字段：

• name — LLM 指定的工具名称
• source_hint — 工具来源（base、MCP 服务器名称等）
• payload — 来自 LLM 的 JSON 输入
• handled — 执行是否已处理
• message — 返回给 LLM 的结果消息

关键函数

ToolPool 组装

ToolPool（定义在 src/tool_pool.py 中）是给定会话中所有可用工具的运行时容器。它精确决定代理可以看到和调用哪些 claw code 工具。

ToolPool 数据类

ToolPool 数据类包含三个字段：tools（过滤后的可用工具列表）、simple_mode（限制为核心工具的布尔值）和 include_mcp（控制是否包含 MCP 工具的布尔值）。

组装流程

assemble_tool_pool() 函数通过过滤管道构建最终工具集：

1. 从快照加载所有已注册的基础工具
2. 如果 simple_mode，限制为 BashTool、FileReadTool、FileEditTool
3. 如果 include_mcp，添加来自已连接 MCP 服务器的工具
4. 应用 ToolPermissionContext 过滤以移除被拒绝的工具
5. 以 markdown 格式渲染最多 15 个工具用于系统提示词

在 Rust 端，等效结构是 ToolManifestEntry（将工具名称与 ToolSource——Base 或 Conditional——配对）和 ToolRegistry（Vec<ToolManifestEntry> 的包装器）。清单区分始终可用的工具和根据上下文条件加载的工具（如特定平台的工具如 PowerShell）。

权限门控

每次工具调用在执行前都通过权限门控系统。这是防止代理执行未经授权操作的安全边界。

Python 端：ToolPermissionContext

ToolPermissionContext 包含两种过滤机制：

• deny_names — 被阻止的确切工具名称的 frozenset
• deny_prefixes — 阻止任何以该前缀开头的工具的名称前缀 tuple

blocks(tool_name) 方法根据两个列表检查工具名称：首先对 deny_names 进行精确匹配，然后对 deny_prefixes 进行前缀匹配。如果任一匹配，工具将被阻止且不会出现在代理的可用工具集中。

Rust 端：PermissionPolicy

Rust 权限系统更为精细，围绕三个概念构建：

当工具调用到达时，权限引擎首先检查每工具 BTreeMap 中是否有显式覆盖。如果没有，则回退到 default_mode。Allow 模式的工具立即执行。Deny 模式的工具向 LLM 返回拒绝消息。Prompt 模式的工具暂停执行并在继续之前询问用户确认。

ToolSpec Schema 模式

19 个 claw code 工具中的每一个都遵循 ToolSpec 模式：一个包含 name（工具调用中使用的字符串标识符）、description（作为系统提示词一部分发送给 LLM 的自然语言说明）和 input_schema（定义接受参数的 JSON Schema）的结构体。这种统一模式确保了所有工具的一致性并简化了工具注册流程。

输入 schema 是标准的 JSON Schema 对象。required 数组列出必需参数，而可选参数在 properties 中定义但不出现在 required 中。Rust 运行时在执行前根据这些 schema 验证所有传入的工具输入，以描述性错误消息拒绝格式错误的输入，帮助 LLM 纠正调用。

完整工具参考表

下表总结了所有 19 个 claw code 工具的主要功能和分类：