Claw Code 工具：19 個內建 AI 代理工具的完整參考

The claw code tools are the primary mechanism through which the AI agent interacts with the developer's environment. Defined in rust/crates/tools/src/lib.rs, each tool is registered as a ToolSpec containing a name, description, and JSON input_schema. At runtime, the agent selects tools based on the task at hand, and the framework validates inputs, checks permissions, executes the tool, and returns structured results. This page documents all 19 built-in tools, the Python orchestration layer, the ToolPool assembly process, and the permission gating architecture.

工具架構概覽

The claw code tools follow a consistent lifecycle: the LLM emits a tool_use content block specifying a tool name and JSON input, the runtime validates the input against the tool's input_schema, the permission engine checks whether the call is allowed, the tool executes, and the result is returned to the LLM as a tool_result content block. This architecture is split across two layers:

• Rust layer (rust/crates/tools/src/lib.rs) — Defines the 19 ToolSpec registrations with JSON schemas and execution logic
• Python layer (src/tools.py, src/tool_pool.py) — Handles tool discovery, filtering, pool assembly, and shim execution for the orchestration layer

Every tool follows a uniform pattern in the Rust crate: parse the LLM's JSON input, validate required and optional fields against the schema, check permissions via the PermissionEngine, execute the operation, and return a typed result struct. This consistency makes it straightforward to add new tools or modify existing ones without disrupting the rest of the system.

Shell 執行工具

1. bash — Shell Command Execution

The bash tool is the most powerful and most heavily gated tool in the claw code tools suite. It executes arbitrary shell commands in a sandboxed environment, capturing stdout, stderr, and the exit code.

The output is a BashCommandOutput struct containing stdout, stderr, return_code_interpretation, an interrupted flag (set when the command was killed due to timeout), and an optional background_task_id for background commands.

19. PowerShell — Windows Shell Execution

The PowerShell tool provides Windows-native shell execution. It accepts two parameters: command (the PowerShell command to execute) and an optional timeout in milliseconds. This is a conditional tool — only available on Windows platforms — and provides the same sandbox enforcement as the bash tool.

檔案操作工具

2. read_file — File Reading with Offset/Limit

The read_file tool reads files from the local filesystem with optional offset and limit parameters for efficient partial reads of large files.

The tool supports reading text files, images (PNG, JPG — presented visually to the multimodal LLM), PDF files (with the pages parameter for large documents), and Jupyter notebooks (.ipynb files with all cells and outputs). Output is returned in cat -n format with line numbers starting at 1.

3. write_file — File Creation and Overwrite

The write_file tool creates new files or overwrites existing ones. It requires an absolute file_path and the full content to write. The output includes both a structured_patch and a git_diff, making it easy to review exactly what changed. This tool is permission-gated — the agent must have write access to the target path.

4. edit_file — String Replacement Editing

The edit_file tool performs precise string replacement within files. Rather than rewriting entire files, the agent specifies an old_string to find and a new_string to replace it with. This approach minimizes the risk of accidental data loss and produces clean, reviewable diffs.

A critical design decision: the edit fails if old_string is not unique within the file (unless replace_all is true). This forces the agent to provide enough surrounding context to unambiguously identify the edit location, preventing accidental modifications to the wrong part of a file.

13. NotebookEdit — Jupyter Cell Editing

The NotebookEdit tool handles Jupyter notebook cell editing. It supports four commands: replace (overwrite a cell's content), insert_above (add a new cell above a given index), insert_below (add a new cell below a given index), and delete (remove a cell). Each command takes a cell_type (code or markdown), an index identifying the target cell, and optional content.

搜尋與探索工具

5. glob_search — File Pattern Matching

The glob_search tool provides fast file pattern matching across the entire codebase. It accepts a pattern (e.g. **/*.ts, src/**/*.rs) and an optional path to restrict the search directory. Results are sorted by modification time and truncated at 100 files to prevent excessive output.

6. grep_search — Regex Content Search

The grep_search tool is built on ripgrep and provides powerful regex content search across the codebase. It is one of the most frequently invoked claw code tools during code exploration and debugging.

The three output modes serve different purposes: files_with_matches is fastest for locating which files contain a pattern, content shows the actual matching lines with optional context, and count provides match counts per file. The type parameter uses ripgrep's built-in file type definitions, which is more efficient than glob filtering for standard file types.

12. ToolSearch — Deferred Tool Discovery

The ToolSearch tool searches for deferred tools that have not yet been fully loaded into the agent's context. It accepts a query string and an optional max_results parameter (default: 5). Query forms include exact selection (select:Read,Edit,Grep), keyword search, and name-required search (+slack send). When matched, full JSON schema definitions are returned so the discovered tools can be immediately invoked.

網頁互動工具

7. WebFetch — URL Content Retrieval

The WebFetch tool retrieves content from a URL and passes it to the agent with an accompanying prompt. This enables the agent to read documentation, check API responses, and gather information from the web during task execution. All URLs are subject to the permission system's network access rules.

8. WebSearch — Web Search with Domain Filtering

The WebSearch tool performs web searches with optional domain filtering. The agent can restrict results to specific domains (e.g. searching only within documentation sites) to improve relevance. Results are returned as structured data that the agent can parse and act upon.

代理協作工具

11. Agent — Sub-Agent Launcher

The Agent tool launches sub-agents for parallel task execution. Sub-agents run in isolated contexts and can be configured with different models and capabilities.

Sub-agents inherit the parent agent's permission context but run in their own conversation thread. The isolation: "worktree" option creates a separate git worktree, allowing the sub-agent to make file changes without interfering with the parent agent's working directory. This is essential for parallel development tasks where multiple agents modify files simultaneously.

10. Skill — Skill Definition Loader

The Skill tool loads predefined skill definitions that provide specialized domain knowledge and capabilities. It accepts a skill name and optional args. Skills are higher-level abstractions that compose multiple tool calls into structured workflows — for example, a "commit" skill that stages changes, drafts a commit message, and creates the commit in sequence.

任務與工作階段管理工具

9. TodoWrite — Task List Management

The TodoWrite tool manages the agent's internal task list. It accepts a todos array where each item has:

• id — Unique identifier for the task
• content — Description of the task
• status — One of pending, in_progress, or completed
• priority — One of high, medium, or low

The agent uses this tool to track multi-step tasks, mark progress, and ensure nothing is missed during complex operations.

14. Sleep — Execution Pause

The Sleep tool pauses execution for a specified duration without holding a shell process. It accepts a single parameter: duration_ms (milliseconds). Unlike running sleep via the bash tool, this dedicated tool does not occupy a shell resource slot and is the preferred way to introduce delays when waiting for external processes.

15. SendUserMessage — User Communication

The SendUserMessage tool sends a message to the user with optional attachments. It accepts a message string, an attachments array, and a status field (normal or proactive). The proactive status indicates that the agent is providing unsolicited information, such as a progress update during a long-running task.

16. Config — Runtime Settings

The Config tool reads and writes agent configuration settings at runtime. It supports three fields: action (get or set), key (the setting name), and value (for set operations). This allows the agent to inspect its own configuration and make adjustments without requiring a restart.

17. StructuredOutput — JSON Data Return

The StructuredOutput tool returns structured JSON data to the caller. It accepts a single data parameter containing any valid JSON value. This is used when the agent needs to return machine-parseable results rather than natural language — for example, returning a list of found issues as a JSON array for downstream processing.

18. REPL — Language REPL Execution

The REPL tool executes code in a language-specific REPL environment. It accepts a language parameter (identifying the runtime) and a code parameter (the code to execute). Unlike the bash tool, the REPL maintains state between invocations within the same session, making it suitable for exploratory programming and iterative data analysis.

Python 工具層

The Python side of the claw code tools system, defined in src/tools.py, provides the orchestration layer that bridges the LLM's tool calls with the Rust execution engine.

ToolExecution 資料類別

Every tool invocation is tracked as a ToolExecution dataclass with the following fields:

• name — The tool name as specified by the LLM
• source_hint — Where the tool originated (base, MCP server name, etc.)
• payload — The JSON input from the LLM
• handled — Whether the execution has been processed
• message — The result message to return to the LLM

關鍵函式

ToolPool 組裝

The ToolPool (defined in src/tool_pool.py) is the runtime container for all available tools in a given session. It determines exactly which claw code tools the agent can see and invoke.

ToolPool 資料類別

The ToolPool dataclass holds three fields: tools (the filtered list of available tools), simple_mode (boolean restricting to core tools), and include_mcp (boolean controlling whether MCP tools are included).

組裝流程

The assemble_tool_pool() function builds the final tool set through a filtering pipeline:

1. Load all registered base tools from the snapshot
2. If simple_mode, restrict to BashTool, FileReadTool, FileEditTool
3. If include_mcp, add tools from connected MCP servers
4. Apply ToolPermissionContext filtering to remove denied tools
5. Render up to 15 tools in markdown format for the system prompt

On the Rust side, the equivalent structures are ToolManifestEntry (pairing a tool name with a ToolSource — either Base or Conditional) and ToolRegistry (a wrapper around Vec<ToolManifestEntry>). The manifest distinguishes between tools that are always available and tools that are conditionally loaded based on context (e.g. platform-specific tools like PowerShell).

權限控制

Every tool invocation passes through the permission gating system before execution. This is the security boundary that prevents the agent from performing unauthorized actions.

Python-Side: ToolPermissionContext

The ToolPermissionContext contains two filtering mechanisms:

• deny_names — A frozenset of exact tool names that are blocked
• deny_prefixes — A tuple of name prefixes that block any tool starting with that prefix

The blocks(tool_name) method checks the tool name against both lists: first an exact match against deny_names, then a prefix match against deny_prefixes. If either matches, the tool is blocked and will not appear in the agent's available tool set.

Rust-Side: PermissionPolicy

The Rust permission system is more granular, built around three concepts:

When a tool call arrives, the permission engine first checks the per-tool BTreeMap for an explicit override. If none exists, it falls back to the default_mode. Tools in Allow mode execute immediately. Tools in Deny mode return a denial message to the LLM. Tools in Prompt mode pause execution and ask the user for confirmation before proceeding.

ToolSpec Schema 模式

Every one of the 19 claw code tools follows the ToolSpec pattern: a struct containing a name (string identifier used in tool calls), a description (natural language explanation sent to the LLM as part of the system prompt), and an input_schema (JSON Schema defining the accepted parameters). This uniform pattern ensures consistency across all tools and simplifies the tool registration process.

The input schema is a standard JSON Schema object. The required array lists mandatory parameters, while optional parameters are defined in properties without appearing in required. The Rust runtime validates all incoming tool inputs against these schemas before execution, rejecting malformed inputs with a descriptive error message that helps the LLM correct its call.

完整工具參考表

The following table summarizes all 19 claw code tools with their primary function and category: