Tool Catalog

Built-in Tool Overview

web_search

Searches the web and returns structured results (title, URL, snippet). The default provider is DuckDuckGo (no API key required). Google and Bing are available with API keys.

tools:
  enabled: [web_search]
  config:
    web_search:
      provider: duckduckgo    # duckduckgo (default), google, bing
      max_results: 5          # 1–20
      safe_search: moderate   # strict, moderate, off

read_url

Fetches a URL and returns its content as plain text (HTML stripped). JavaScript-rendered pages are supported with the playwright backend (optional install).

    read_url:
      backend: requests        # requests (default) or playwright
      max_content_length: 50000  # truncate long pages
      allowed_domains: []      # whitelist specific domains; empty = allow all
      timeout_seconds: 30

write_file and read_file

File tools operate only within configured allowed directories. The agent cannot read from or write to paths outside those directories — attempts raise TOOL_PERMISSION_DENIED. Enable allowed directories with minimal scope — give the agent permission only to directories it actually needs.

    write_file:
      allowed_dirs: [/tmp/agent-output]
      max_file_size_mb: 10
    read_file:
      allowed_dirs: [/tmp/agent-output, /data/readonly]

execute_code

High risk. Runs code in a sandboxed subprocess. Recommended only for development environments or carefully constrained production use cases. Configure resource limits and network access carefully. Never enable execute_code without understanding and accepting the security implications.

Tool Configuration Pattern

When adding a new tool to your agent, follow this pattern: add the tool name to tools.enabled in your config, add any required configuration under tools.config.{tool_name}, run openclaw config validate to verify, and test the agent with a simple task that exercises the new tool before deploying to production. Validate that the tool works correctly in isolation before including it in a complex multi-tool agent configuration.

Tool Safety Model

OpenClaw's tool safety model is based on explicit opt-in with minimal scope. No built-in tools are enabled by default — you must explicitly list each tool in tools.enabled. File system tools require explicitly listed allowed directories. Network tools can be restricted to a whitelist of allowed domains. The execute_code tool requires an explicit allow_execute_code: true safety acknowledgment in addition to being listed in tools.enabled.

This defense-in-depth approach ensures that a compromise of the agent's decision-making (e.g., a prompt injection attack) cannot cause damage beyond the explicitly configured permissions. An agent configured with only web_search and read_url cannot write files or execute code, regardless of what the LLM is instructed to do.

When designing tool permissions for production agents, apply the principle of least privilege: give the agent only the tools it needs for its task, and configure each tool with the most restrictive scope that still allows the task to complete. A research agent needs web_search and read_url; it does not need execute_code or send_email. An automation agent might need write_file to a specific output directory but not read_file of system configuration files.

Third-Party and Custom Tools

Beyond the built-in catalog, OpenClaw's plugin system supports installing third-party tool packages from PyPI or loading custom tool implementations from local Python modules. Installed tools appear in the tools.enabled pool alongside built-in tools. The openclaw plugin list command shows all installed plugins and their provided tools.

Before installing third-party tools, review the tool's source code and permissions requirements. Third-party tools run with the same privileges as built-in tools — a malicious or compromised tool package could read files, make network requests, or execute code within the agent's configured permissions. Treat third-party tool packages with the same scrutiny as any other dependency that has access to your production environment.

Tool Result Handling

Understanding how tool results are passed back to the LLM helps you design better tools. After a tool executes, its return value is serialized to a string and inserted into the conversation as a tool result message. The LLM then reasons about the tool result in its next step. This means:

Tool results should be information-rich but concise. A tool that returns a 50,000-token web page verbatim will fill the context window and prevent the agent from completing further steps. Tools should return the most relevant extracted information, not raw content. OpenClaw's read_url tool automatically truncates content to max_content_length characters and extracts text from HTML for this reason.

Tool results should be clearly structured when they contain multiple pieces of information. JSON responses are easier for the LLM to parse and reason about than unstructured text. When implementing custom tools, return dictionaries with clearly named keys rather than concatenated strings — the LLM will be able to reference specific fields more reliably.

Building Custom Tools

When the built-in tool catalog doesn't cover your use case, build a custom tool. The tool interface requires three things: a Python function that performs the action, a JSON Schema describing the function's arguments (so the LLM can format calls correctly), and a human-readable description (so the LLM knows when to use the tool). Custom tools integrate identically to built-in tools — once installed via openclaw plugin install, they appear in the tools.enabled pool and are included in the {{tools}} prompt variable automatically. See the plugin development guide for the complete walkthrough.