Built-in Tools

Every OpenClaw agent has access to a set of built-in tools that extend its capabilities beyond text generation. Tools let agents search the web, perform calculations, read files, make HTTP requests, and more.

How Tools Work

When an agent determines that it needs to perform an action, it issues a tool call. OpenClaw intercepts the call, executes the tool in a sandboxed environment, and returns the result to the agent for further reasoning.

User: "What's the weather in Tokyo?"
Agent: [calls web_search tool with query "weather Tokyo today"]
Tool result: "Tokyo: 22C, partly cloudy..."
Agent: "The weather in Tokyo is currently 22C and partly cloudy."

Enabling Tools

Tools are enabled per agent in config.yaml:

agents:
  my-agent:
    tools:
      - web_search
      - calculator
      - file_read
      - file_write
      - http_request
      - shell

You can also enable all built-in tools at once:

agents:
  my-agent:
    tools: all

Tool Reference

web_search

Searches the web and returns summarized results.

Parameter	Type	Required	Description
query	string	Yes	The search query.
num_results	integer	No	Number of results to return (default: 5, max: 20).
region	string	No	Region code for localized results (e.g., us, jp).

{ "tool": "web_search", "params": { "query": "OpenClaw documentation", "num_results": 3 } }

Permission level: read

calculator

Evaluates mathematical expressions safely.

Parameter	Type	Required	Description
expression	string	Yes	The math expression to evaluate.

{ "tool": "calculator", "params": { "expression": "sqrt(144) + 3^2" } }

Permission level: none (no system access needed)

file_read

Reads the contents of a file from the sandboxed file system.

Parameter	Type	Required	Description
path	string	Yes	Path to the file (relative to sandbox root).
encoding	string	No	File encoding (default: utf-8).

{ "tool": "file_read", "params": { "path": "data/report.csv" } }

Permission level: read

file_write

Writes content to a file in the sandboxed file system.

Parameter	Type	Required	Description
path	string	Yes	Destination path (relative to sandbox root).
content	string	Yes	Content to write.
mode	string	No	overwrite (default) or append.

{ "tool": "file_write", "params": { "path": "output/summary.txt", "content": "Report summary..." } }

Permission level: write

http_request

Makes HTTP requests to external APIs and services.

Parameter	Type	Required	Description
method	string	Yes	HTTP method (GET, POST, PUT, DELETE).
url	string	Yes	The target URL.
headers	object	No	Request headers.
body	string	No	Request body (for POST/PUT).
timeout	integer	No	Timeout in seconds (default: 30).

{
  "tool": "http_request",
  "params": {
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": { "Authorization": "Bearer ${API_KEY}" }
  }
}

Permission level: read (GET/HEAD) or write (POST/PUT/DELETE)

shell

Executes shell commands on the host system within the sandbox.

Parameter	Type	Required	Description
command	string	Yes	The shell command to run.
timeout	integer	No	Max execution time in seconds (default: 30).
working_dir	string	No	Working directory (default: sandbox root).

{ "tool": "shell", "params": { "command": "ls -la /sandbox/data", "timeout": 10 } }

Permission level: execute

caution

The shell tool is powerful and potentially dangerous. Only enable it for trusted agents and always configure the sandbox properly.

memory_store

Stores a key-value pair in the agent's long-term memory.

Parameter	Type	Required	Description
key	string	Yes	A descriptive key for the memory.
value	string	Yes	The value to store.
tags	list	No	Tags for categorization.

Permission level: write

memory_recall

Retrieves memories matching a query from long-term storage.

Parameter	Type	Required	Description
query	string	Yes	Natural language query to search memories.
limit	integer	No	Max results to return (default: 5).

Permission level: read

Tool Permissions Summary

Tool	Permission Level	Risk
calculator	none	Minimal
web_search	read	Low
file_read	read	Low
memory_recall	read	Low
file_write	write	Medium
memory_store	write	Medium
http_request	read/write	Medium
shell	execute	High

Next Steps

• Learn about Browser Automation for web scraping and interaction.
• Understand the Sandbox & Permission Model that governs tool access.