Built-In Tools Deep Dive: Capabilities and Use Cases of All 16 Core Tools

Chapter 14: Complete Built-in Tool Guide — Capability Boundaries and Use Cases for 16 Core Tools

Overview

OpenClaw includes 16 native built-in tools, covering all core capabilities: file operations, command execution, browser control, web search, scheduled task management, memory management, and multi-Agent coordination. Understanding each tool's boundaries and applicable scenarios is a prerequisite for building efficient Agent workflows.

14.1 Tool Overview

14.2 read — File Reading

Description

Reads the contents of a file from the local filesystem. Supports both text and binary files.

Interface Definition

{
  "tool": "read",
  "input": {
    "path": "/path/to/file",
    "encoding": "utf-8",
    "start_line": 1,
    "end_line": 100,
    "max_bytes": 102400
  }
}

Parameter Reference

Applicable Scenarios

• Reading config files, log files, source code files
• Loading data files for analysis
• Checking whether a file exists and its contents

Limitations

• Cannot read paths outside the sandbox by default (controlled by tool policy)
• For large files, use start_line/end_line for chunked reading
• Binary files require encoding: "base64"

14.3 write — File Writing

Description

Creates a new file or overwrites the entire contents of an existing file.

Interface Definition

{
  "tool": "write",
  "input": {
    "path": "/path/to/output.txt",
    "content": "File content goes here",
    "encoding": "utf-8",
    "create_dirs": true,
    "overwrite": true
  }
}

Applicable Scenarios

• Creating new files
• Generating config files, reports, code files
• Writing content that fully replaces existing content (use edit for partial modifications)

Limitations

• Errors if file exists and overwrite: false
• Not suitable for partial modifications of large files (use edit)

14.4 edit — Precise File Editing

Description

Performs precise partial content modifications on files. Supports string replacement, line-number replacement, and regular expression replacement.

Interface Definition

{
  "tool": "edit",
  "input": {
    "path": "/path/to/file.py",
    "operations": [
      {
        "type": "replace_string",
        "old": "def old_function():",
        "new": "def new_function():",
        "replace_all": false
      },
      {
        "type": "replace_lines",
        "start_line": 42,
        "end_line": 45,
        "new_content": "# New code block\nprint('hello')"
      },
      {
        "type": "insert_after_line",
        "line": 10,
        "content": "# Inserted comment"
      }
    ]
  }
}

Decision Logic: read vs edit vs write

Need to read file contents?
    --> Use read

Need to modify a file?
    --> Need to modify the entire file?
        --> Use write
    --> Only need to modify specific parts?
        --> Use edit
            --> Know the exact string? Use replace_string
            --> Know the line number range? Use replace_lines

14.5 exec — Shell Command Execution

Description

Executes a single shell command with sandbox control and timeout management.

Interface Definition

{
  "tool": "exec",
  "input": {
    "command": "ls -la /workspace",
    "cwd": "/workspace",
    "env": {
      "MY_VAR": "value"
    },
    "timeout_seconds": 30,
    "capture_output": true
  }
}

Output Format

{
  "stdout": "file listing content...",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 142
}

14.6 bash — Bash Script Block Execution

Description

Executes multi-line Bash scripts with support for pipes, variables, and complex logic.

Interface Definition

{
  "tool": "bash",
  "input": {
    "script": "#!/bin/bash\nset -e\ncd /workspace\nfor f in *.py; do\n  echo \"Processing: $f\"\n  python -m py_compile \"$f\"\ndone",
    "timeout_seconds": 60,
    "cwd": "/workspace"
  }
}

Differences: exec vs bash

Important: Both tools strip dangerous environment variables before execution, including DYLD_*, LD_*, NODE_OPTIONS, etc.

14.7 process — Process Management

Description

Starts, stops, and queries background processes. Suitable for services that need to run long-term.

Interface Definition

{
  "tool": "process",
  "input": {
    "action": "start",
    "command": "python server.py",
    "cwd": "/workspace",
    "name": "my-server",
    "restart_on_crash": true,
    "log_file": "/var/log/my-server.log"
  }
}

Action Types

Applicable Scenarios

• Starting web servers, databases
• Managing long-running workers
• Starting auxiliary services within Agent workflows

14.8 browser — Browser Control

Description

Controls a headless browser via Playwright/Puppeteer for web automation.

Coordinate Click

{
  "tool": "browser",
  "input": {
    "action": "click",
    "selector": "#submit-button",
    "x": 450,
    "y": 320,
    "click_type": "left"
  }
}

Form Filling

{
  "tool": "browser",
  "input": {
    "action": "fill_form",
    "fields": [
      {"selector": "#username", "value": "admin"},
      {"selector": "#password", "value": "${SECRET_PASSWORD}"},
      {"selector": "#remember-me", "action": "check"}
    ]
  }
}

Navigation

{
  "tool": "browser",
  "input": {
    "action": "navigate",
    "url": "https://example.com"
  }
}

Complete Action Set

Applicable Scenarios

• Automated login, data extraction (web scraping)
• Filling out online forms, submitting applications
• E2E testing of web applications
• Screenshot monitoring of page state

14.9 web_search — Web Search

Description

Integrates multiple search engines and content scraping services to retrieve real-time web information.

Supported Backends

Interface Definition

{
  "tool": "web_search",
  "input": {
    "query": "OpenClaw Agent framework 2026",
    "backend": "tavily",
    "max_results": 5,
    "include_content": true,
    "time_range": "month"
  }
}

Sample Output

{
  "results": [
    {
      "title": "OpenClaw v3.0 Release Notes",
      "url": "https://docs.openclaw.dev/changelog",
      "snippet": "OpenClaw 3.0 introduces...",
      "content": "Full page content...",
      "published_date": "2026-03-15"
    }
  ],
  "total_results": 5
}

14.10 message — Message Sending

Description

Sends messages to users, system logs, or external webhooks. Supports multiple message types.

Interface Definition

{
  "tool": "message",
  "input": {
    "target": "user",
    "content": "Task completed — please review the results",
    "type": "info",
    "attachments": [
      {"type": "file", "path": "/output/report.pdf"}
    ]
  }
}

Message Targets

Message Types

14.11 cron — Scheduled Task Management

Description

Creates, manages, and deletes scheduled tasks. Supports standard Cron expressions.

Cron Expression Syntax

┌─────────── Minute (0-59)
│ ┌─────────── Hour (0-23)
│ │ ┌─────────── Day of month (1-31)
│ │ │ ┌─────────── Month (1-12)
│ │ │ │ ┌─────────── Day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Interface Definition

{
  "tool": "cron",
  "input": {
    "action": "create",
    "name": "daily-report",
    "schedule": "0 9 * * 1-5",
    "task": {
      "type": "agent_run",
      "agent": "report-generator",
      "input": {"date": "${today}"}
    },
    "timezone": "America/New_York",
    "enabled": true
  }
}

Common Cron Expression Examples

# Every day at 9 AM on weekdays
0 9 * * 1-5

# Every hour
0 * * * *

# Every 15 minutes
*/15 * * * *

# First day of every month at midnight
0 0 1 * *

# Every Sunday at 2 AM for backups
0 2 * * 0

# Every day at 3 PM and 6 PM
0 15,18 * * *

Cron Action Types

14.12 memory_search — Semantic Memory Search

Description

Performs semantic similarity searches in the Agent memory store, returning the most relevant memory fragments.

Interface Definition

{
  "tool": "memory_search",
  "input": {
    "query": "user preferred output format settings",
    "top_k": 5,
    "threshold": 0.7,
    "namespace": "user_preferences",
    "filters": {
      "created_after": "2026-01-01",
      "tags": ["preferences", "format"]
    }
  }
}

Sample Output

{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "User prefers JSON output format with 2-space indentation",
      "similarity": 0.92,
      "created_at": "2026-02-15T10:23:00Z",
      "tags": ["preferences", "format"]
    }
  ]
}

14.13 memory_get — Reading Specific Memory Files

Description

Precisely reads a specific memory entry by ID or path, without performing semantic search.

Interface Definition

{
  "tool": "memory_get",
  "input": {
    "id": "mem_abc123",
    "path": "user_preferences/output_format.md",
    "namespace": "global"
  }
}

Decision Logic: memory_search vs memory_get

Do you know what memory you need?
    |
    +-- Know the exact ID or filename --> Use memory_get (precise, fast)
    |
    +-- Know roughly what it's about but not its location --> Use memory_search (semantic search)
    |
    +-- Need to batch-scan related memories --> First memory_search, then memory_get on results

14.14 sessions_spawn — Spawning Sub-Agents

Description

Creates independent sub-Agent sessions for parallel task processing or specialized task division.

Interface Definition

{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {
      "name": "code-reviewer",
      "model": "anthropic/claude-opus-4-6",
      "system_prompt": "You are a professional code review Agent focused on security vulnerability detection",
      "tools": ["read", "web_search"],
      "max_turns": 20
    },
    "initial_message": "Please review all Python files in the /workspace/src directory",
    "delivery_mode": "background",
    "on_complete_notify": true
  }
}

Delivery Modes

Usage Patterns

Pattern A: Parallel Task Decomposition

// Main Agent spawns multiple sub-Agents for different modules simultaneously
{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {"name": "frontend-agent"},
    "initial_message": "Optimize React component performance"
  }
}
// Simultaneously
{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {"name": "backend-agent"},
    "initial_message": "Optimize API endpoint performance"
  }
}

Pattern B: Specialized Division of Labor

{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {
      "name": "security-auditor",
      "system_prompt": "Focus on security auditing, use only the read tool",
      "tools": ["read"],
      "tool_policy": "allowlist"
    }
  }
}

14.15 Canvas Control Tool Group

Canvas tools operate on OpenClaw's visual workspace, supporting the creation of interactive dashboards and workflow visualizations.

Main Operations

{
  "tool": "canvas_create_node",
  "input": {
    "type": "text",
    "content": "Data analysis results",
    "x": 100,
    "y": 200,
    "width": 300,
    "height": 150
  }
}

14.16 Node Device Control Tool Group

Node tools control physical devices and IoT nodes. Suitable for edge computing and industrial automation scenarios.

{
  "tool": "node_send_command",
  "input": {
    "node_id": "sensor-hub-01",
    "command": "read_temperature",
    "params": {"unit": "celsius"}
  }
}

14.17 Combined Tool Usage Patterns

Pattern A: Code Generation and Validation

web_search (look up documentation)
    --> read (read existing code)
    --> write/edit (generate new code)
    --> exec (run tests)
    --> message (report results)

Pattern B: Scheduled Data Collection

cron (trigger schedule)
    --> web_search (search for latest data)
    --> write (save raw data)
    --> sessions_spawn (async analysis Agent)
    --> message (send analysis report)

Pattern C: Automated Web Operations

browser (navigate to target page)
    --> browser (fill out form)
    --> browser (screenshot to confirm)
    --> write (save screenshot)
    --> message (notify completion)

Chapter Summary

• read/write/edit form the complete file operation triangle: reading, full-overwrite writing, and precise partial modification
• exec vs bash: use exec for single commands, bash for multi-step scripts; both strip dangerous environment variables
• browser supports coordinate clicking and batch form filling — the core of web automation
• web_search supports multiple backends including Exa/Tavily/Firecrawl; choose based on need
• cron supports standard Cron expressions with timezone configuration
• memory_search does semantic retrieval; memory_get does precise lookup
• sessions_spawn is the key tool for enabling parallel multi-Agent collaboration

Next chapter will dive deep into tool policy: Allow/Deny rules, sandbox configuration, and the elevated flag.