Brave Search API Setup for web_search Provider

OpenClaw uses the Brave Search API as a web_search provider.

Get an API key

Sign up for a Brave Search API account at https://brave.com/search/api/
Inside the dashboard, pick the Search plan and generate an API key.
Save the key in your configuration or export BRAVE_API_KEY in the Gateway environment.

Config example

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
            mode: "web", // or "llm-context"
            baseUrl: "https://api.search.brave.com", // optional proxy/base URL override
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "brave",
        maxResults: 5,
        timeoutSeconds: 30,
      },
    },
  },
}

Provider-specific Brave search configuration is located under plugins.entries.brave.config.webSearch.*; that path is the canonical location.

The Brave transport is managed by webSearch.mode:

web (default): standard Brave web search returning titles, URLs, and snippets
llm-context: Brave LLM Context API delivering pre-extracted text chunks and sources for grounding

webSearch.baseUrl lets you route Brave requests through a trusted Brave-compatible proxy or gateway. OpenClaw adds /res/v1/web/search or /res/v1/llm/context to the configured base URL and includes the base URL in the cache key. Public endpoints must use https://; http:// is allowed only for trusted loopback or private-network proxy hosts.

Tool parameters

query (string, required), The search query.
count (number, default: 5), How many results to return, from 1 to 10.
country (string), A 2-letter ISO country code, for example US or DE.
language (string), An ISO 639-1 language code for results, like en, de, or fr.
search_lang (string), A Brave search-language code, such as en, en-gb, or zh-hans.
ui_lang (string), An ISO language code for the UI elements.
freshness (day' | 'week' | 'month' | 'year), A time filter; day means the last 24 hours.
date_after (string), Only results published on or after this date (YYYY-MM-DD).
date_before (string), Only results published on or before this date (YYYY-MM-DD).

Examples:

// Country and language-specific search
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// Recent results (past week)
await web_search({
  query: "AI news",
  freshness: "week",
});

// Date range search
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

Notes

OpenClaw relies on the Brave Search plan. If you hold an older subscription (for instance, the original Free plan granting 2,000 queries each month), it stays active but lacks newer capabilities such as LLM Context or elevated rate limits.
Every Brave plan provides $5/month in recurring free credit. Since the Search plan charges $5 per 1,000 requests, that credit covers 1,000 queries per month. To prevent surprise costs, configure your usage cap in the Brave dashboard. Check the Brave API portal for up-to-date plan details.
The Search plan grants access to the LLM Context endpoint and AI inference rights. If you want to store results for training or fine-tuning models, you need a plan that explicitly permits storage. Refer to the Brave Terms of Service.
In llm-context mode, the response returns grounded source entries rather than the typical web-search snippet format.
llm-context mode supports freshness and bounded date_after + date_before ranges. It does not support ui_lang; date_before without date_after is rejected because Brave requires custom freshness ranges to include both a start and an end date.
ui_lang must contain a region subtag such as en-US.
By default, results are cached for 15 minutes (this can be changed with cacheTtlMinutes).
Custom webSearch.baseUrl values are part of the Brave cache key, so proxy-specific responses do not interfere with each other.
During troubleshooting, turn on the brave.http diagnostics flag to record Brave request URLs and query parameters, response status and timing, and search-cache hit/miss/write events. The flag never logs the API key or response bodies, though search queries may themselves be sensitive.

Overview of Web Search, supported providers and automatic detection
Perplexity Search, domain-filtered, structured results
Exa Search, neural search with content retrieval