Understanding OpenClaw's Web Search Tool

OpenClaw's web_search tool enables you to perform real-time, internet-based research directly within your agent workflows. It integrates with powerful search providers like Brave Search and Perplexity Sonar, delivering up-to-date, structured results from the web.

How It Works

The web_search tool functions as a lightweight, non-JavaScript search engine client. When you make a search query, OpenClaw contacts your configured search provider (default: Brave Search) and retrieves a list of results including titles, URLs, and text snippets.

Unlike full browser automation, web_search does not load web pages in a browser, navigate interactive elements, or execute JavaScript. It is designed for fast, programmatic access to search engine data, making it ideal for research, fact-checking, and information gathering.

Key Features

• Real-time Search: Access the latest information from the web.
• Structured Results: Get clean, machine-readable data (title, URL, snippet) for easy processing.
• Provider Flexibility: Use Brave Search for traditional results or Perplexity Sonar for AI-synthesized, citated answers.
• Caching: Search results are cached for 15 minutes to improve efficiency on repeated queries.
• Configurable: Control the number of results, freshness filters, and region/language settings.

Setup Requirements

To use the web_search tool, you must configure an API key from one of the supported providers.

Setting Up Brave Search (Recommended)

1. Create an Account: Sign up at https://brave.com/search/api/.
2. Generate an API Key: In the dashboard, select the Data for Search plan and create a new API key.
3. Configure OpenClaw:
   • Run openclaw configure --section web and follow the prompts to store your Brave API key, or
   • Set the BRAVE_API_KEY environment variable in your OpenClaw environment (e.g., in ~/.openclaw/.env).

Setting Up Perplexity Sonar

1. Create an Account: Sign up at https://openrouter.ai/.
2. Get an API Key: Generate a key in your account settings. (OpenRouter supports free-tier usage with cryptocurrency and prepaid options, requiring no credit card.)
3. Configure OpenClaw: Set the OPENROUTER_API_KEY environment variable, or configure it directly in your OpenClaw config under tools.web.search.perplexity.apiKey.

Using the Web Search Tool

Once configured, you can use web_search in your agent code:

await web_search({
  query: "latest advancements in AI voice assistants",
  count: 5,
  country: "US",
  freshness: "pw", // Past week
});

Parameters

• query (required): The search term or question.
• count (1–10): Number of results to return.
• country: Two-letter country code (e.g., "DE", "US", "ALL") for region-specific results.
• search_lang: ISO language code for the search results.
• freshness: Filter results by time (e.g., pd for past day, pw for past week).

When to Use Web Search

Use web_search when you need to quickly gather information from the web without the overhead of a browser. It's perfect for:

• Answering factual questions
• Researching current events
• Finding relevant articles or documentation
• Competitor analysis

For websites that require JavaScript, user login, or complex interactions, use the browser tool instead.

Why It's Blocked in This Project

In the ClawMakers project, the Web Search Tool Guide was previously marked as blocked because the system's Brave API key was missing. This guide provides the necessary steps to resolve that issue and unlock the tool's full potential.

With your API key configured, you can now seamlessly integrate real-time web search into your agent workflows, making web_search a powerful addition to your OpenClaw toolkit.