Web tools

OpenClaw ships two lightweight web tools:

web_search — Search the web via Brave Search API (default), Perplexity Sonar, Gemini with Google Search grounding, Grok, Kimi, or a self-hosted SearXNG instance.
web_fetch — HTTP fetch + readable extraction (HTML → markdown/text).

These are not browser automation. For JS-heavy sites or logins, use the Browser tool.

How it works

web_search calls your configured provider and returns results.
- Brave (default): returns structured results (title, URL, snippet).
- Perplexity: returns AI-synthesized answers with citations from real-time web search.
- Gemini: returns AI-synthesized answers grounded in Google Search with citations.
Results are cached by query for 15 minutes (configurable).
web_fetch does a plain HTTP GET and extracts readable content (HTML → markdown/text). It does not execute JavaScript.
web_fetch is enabled by default (unless explicitly disabled).

Choosing a search provider

Provider	Pros	Cons	API Key
Brave (default)	Fast, structured results, free tier	Traditional search results	`BRAVE_API_KEY`
Gemini	Google Search grounding, AI-synthesized	Requires Gemini API key	`GEMINI_API_KEY`
Perplexity	AI-synthesized answers, citations, real-time	Requires Perplexity or OpenRouter access	`OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY`
Grok	xAI web-grounded responses	Requires xAI API key	`XAI_API_KEY`
Kimi	Moonshot web search capability	Requires Moonshot API key	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
SearXNG	Self-hosted, no API key, full privacy	Requires a self-hosted SearXNG instance	None (uses `baseUrl` config)

See Brave Search setup and Perplexity Sonar for provider-specific details.

Auto-detection

If no provider is explicitly set, OpenClaw auto-detects which provider to use based on available API keys, checking in priority order:

Brave — BRAVE_API_KEY env var or plugins.entries.brave-search.config.webSearch.apiKey
Gemini — GEMINI_API_KEY env var or plugins.entries.gemini-search.config.webSearch.apiKey
Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY env var or plugins.entries.perplexity-search.config.webSearch.apiKey
Grok — XAI_API_KEY env var or plugins.entries.grok-search.config.webSearch.apiKey
Kimi — KIMI_API_KEY / MOONSHOT_API_KEY env var or plugins.entries.kimi-search.config.webSearch.apiKey

Migration note (v2026.5.25+): the per-provider config keys used to live under tools.web.search.<provider>.* (e.g. tools.web.search.perplexity.apiKey). After the plugin extraction the canonical location is now plugins.entries.<provider>-search.config.webSearch.*. The legacy paths are still accepted as a fallback (for compatibility with existing configs and the openclaw configure --section web wizard / secrets registry), but new configs should prefer the plugin-entry form above. Secret refs caveat: the ${secret:…} resolver currently only walks the legacy tools.web.search.*.apiKey paths. If you store API keys as SecretRef-style references rather than literal strings, keep them in the legacy path until the collector is extended to walk plugin entries — otherwise the literal ${secret:…} text is sent upstream as the credential.

SearXNG is not auto-detected — it must be configured explicitly with a baseUrl (see SearXNG setup). If no keys are found, no web_search tool is registered (you’ll see a log message). Configure at least one provider to enable search.

Explicit provider

Set the provider in config:

{
  tools: {
    web: {
      search: {
        provider: "brave-search", // or "perplexity-search" or "gemini-search" or "grok-search" or "kimi-search" or "searxng-search"
      },
    },
  },
}

Example: switch to Perplexity Sonar (direct API):

{
  tools: {
    web: {
      search: {
        provider: "perplexity-search",
      },
    },
  },
  plugins: {
    entries: {
      "perplexity-search": {
        config: {
          webSearch: {
            apiKey: "pplx-...",
            baseUrl: "https://api.perplexity.ai",
            model: "perplexity/sonar-pro",
          },
        },
      },
    },
  },
}

Getting a Brave API key

Create a Brave Search API account at https://brave.com/search/api/
In the dashboard, choose the Data for Search plan (not “Data for AI”) and generate an API key.
Run openclaw configure --section web to store the key in config (recommended), or set BRAVE_API_KEY in your environment.

Brave provides a free tier plus paid plans; check the Brave API portal for the current limits and pricing.

Where to set the key (recommended)

Recommended: run openclaw configure --section web. It stores the key in ~/.openclaw/openclaw.json under plugins.entries.brave-search.config.webSearch.apiKey. Environment alternative: set BRAVE_API_KEY in the Gateway process environment. For a gateway install, put it in ~/.openclaw/.env (or your service environment). See Env vars.

Using Perplexity (direct or via OpenRouter)

Perplexity Sonar models have built-in web search capabilities and return AI-synthesized answers with citations. You can use them via OpenRouter (no credit card required - supports crypto/prepaid).

Getting an OpenRouter API key

Create an account at https://openrouter.ai/
Add credits (supports crypto, prepaid, or credit card)
Generate an API key in your account settings

Setting up Perplexity search

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity-search",
      },
    },
  },
  plugins: {
    entries: {
      "perplexity-search": {
        config: {
          webSearch: {
            // API key (optional if OPENROUTER_API_KEY or PERPLEXITY_API_KEY is set)
            apiKey: "sk-or-v1-...",
            // Base URL (key-aware default if omitted)
            baseUrl: "https://openrouter.ai/api/v1",
            // Model (defaults to perplexity/sonar-pro)
            model: "perplexity/sonar-pro",
          },
        },
      },
    },
  },
}

Environment alternative: set OPENROUTER_API_KEY or PERPLEXITY_API_KEY in the Gateway environment. For a gateway install, put it in ~/.openclaw/.env. If no base URL is set, OpenClaw chooses a default based on the API key source:

PERPLEXITY_API_KEY or pplx-... → https://api.perplexity.ai
OPENROUTER_API_KEY or sk-or-... → https://openrouter.ai/api/v1
Unknown key formats → OpenRouter (safe fallback)

Available Perplexity models

Model	Description	Best for
`perplexity/sonar`	Fast Q&A with web search	Quick lookups
`perplexity/sonar-pro` (default)	Multi-step reasoning with web search	Complex questions
`perplexity/sonar-reasoning-pro`	Chain-of-thought analysis	Deep research

Using Gemini (Google Search grounding)

Gemini models support built-in Google Search grounding, which returns AI-synthesized answers backed by live Google Search results with citations.

Getting a Gemini API key

Go to Google AI Studio
Create an API key
Set GEMINI_API_KEY in the Gateway environment, or configure plugins.entries.gemini-search.config.webSearch.apiKey

Setting up Gemini search

{
  tools: {
    web: {
      search: {
        provider: "gemini-search",
      },
    },
  },
  plugins: {
    entries: {
      "gemini-search": {
        config: {
          webSearch: {
            // API key (optional if GEMINI_API_KEY is set)
            apiKey: "AIza...",
            // Model (defaults to "gemini-2.5-flash")
            model: "gemini-2.5-flash",
          },
        },
      },
    },
  },
}

Environment alternative: set GEMINI_API_KEY in the Gateway environment. For a gateway install, put it in ~/.openclaw/.env.

Notes

Citation URLs from Gemini grounding are automatically resolved from Google’s redirect URLs to direct URLs.
Redirect resolution uses the SSRF guard path (HEAD + redirect checks + http/https validation) before returning the final citation URL.
Redirect resolution uses strict SSRF defaults, so redirects to private/internal targets are blocked.
The default model (gemini-2.5-flash) is fast and cost-effective. Any Gemini model that supports grounding can be used.

Using SearXNG (self-hosted)

SearXNG is a self-hosted, privacy-respecting meta-search engine. There is no API key — you provide your own instance URL.

Setting up SearXNG search

Select the SearXNG provider in tools.web.search, then configure the instance under the searxng-search plugin entry (the SearXNG extension reads its config from plugins.entries.searxng-search.config.webSearch):

{
  tools: {
    web: {
      search: {
        provider: "searxng-search",
      },
    },
  },
  plugins: {
    entries: {
      "searxng-search": {
        config: {
          webSearch: {
            // Required: URL of your SearXNG instance
            baseUrl: "http://localhost:8080",
            // Optional: comma-separated category names (default: "general")
            categories: "general,news",
            // Optional: language code (default: "en")
            language: "en",
          },
        },
      },
    },
  },
}

Environment alternative: set SEARXNG_BASE_URL in the gateway environment (for example in ~/.openclaw/.env) to skip the plugins.entries block entirely.

SearXNG notes

Private-network addresses (localhost, 127.x, 10.x, 192.168.x, 172.16-31.x) are permitted — they are expected when running a local SearXNG instance.
External https:// SearXNG instances are also supported.
SearXNG is never auto-detected; it must be configured explicitly with provider: "searxng-search".
Set SEARXNG_BASE_URL in the gateway environment, or configure plugins.entries.searxng-search.config.webSearch.baseUrl in ~/.openclaw/openclaw.json.

web_search

Search the web using your configured provider.

Requirements

tools.web.search.enabled must not be false (default: enabled)
API key / endpoint for your chosen provider (set via env var or plugins.entries.<provider>-search.config.webSearch.apiKey):
- Brave: BRAVE_API_KEY or plugins.entries.brave-search.config.webSearch.apiKey
- Perplexity: OPENROUTER_API_KEY, PERPLEXITY_API_KEY, or plugins.entries.perplexity-search.config.webSearch.apiKey
- Gemini: GEMINI_API_KEY or plugins.entries.gemini-search.config.webSearch.apiKey
- Grok: XAI_API_KEY or plugins.entries.grok-search.config.webSearch.apiKey
- Kimi: KIMI_API_KEY, MOONSHOT_API_KEY, or plugins.entries.kimi-search.config.webSearch.apiKey
- SearXNG: SEARXNG_BASE_URL or plugins.entries.searxng-search.config.webSearch.baseUrl (no API key needed)

Config

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave-search",
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
  plugins: {
    entries: {
      "brave-search": {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE", // optional if BRAVE_API_KEY env var is set
          },
        },
      },
    },
  },
}

Note: the legacy tools.web.search.apiKey location is still accepted as a fallback for compatibility with existing configs and openclaw configure --section web, but new configs should use the plugins.entries.brave-search.config.webSearch.apiKey form above.

Tool parameters

query (required)
count (1–10; default from config)
country (optional): 2-letter country code for region-specific results (e.g., “DE”, “US”, “ALL”). If omitted, Brave chooses its default region.
search_lang (optional): ISO language code for search results (e.g., “de”, “en”, “fr”)
ui_lang (optional): ISO language code for UI elements
freshness (optional): filter by discovery time
- Brave: pd, pw, pm, py, or YYYY-MM-DDtoYYYY-MM-DD
- Perplexity: pd, pw, pm, py

Examples:

// German-specific search
await web_search({
  query: "TV online schauen",
  count: 10,
  country: "DE",
  search_lang: "de",
});

// French search with French UI
await web_search({
  query: "actualités",
  country: "FR",
  search_lang: "fr",
  ui_lang: "fr",
});

// Recent results (past week)
await web_search({
  query: "TMBG interview",
  freshness: "pw",
});

web_fetch

Fetch a URL and extract readable content.

web_fetch requirements

tools.web.fetch.enabled must not be false (default: enabled)
Optional Firecrawl fallback: set tools.web.fetch.firecrawl.apiKey or FIRECRAWL_API_KEY.

web_fetch config

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // optional if FIRECRAWL_API_KEY is set
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 day)
          timeoutSeconds: 60,
        },
      },
    },
  },
}

web_fetch tool parameters

url (required, http/https only)
extractMode (markdown | text)
maxChars (truncate long pages)

Notes:

web_fetch uses Readability (main-content extraction) first, then Firecrawl (if configured). If both fail, the tool returns an error.
Firecrawl requests use bot-circumvention mode and cache results by default.
web_fetch sends a Chrome-like User-Agent and Accept-Language by default; override userAgent if needed.
web_fetch blocks private/internal hostnames and re-checks redirects (limit with maxRedirects).
maxChars is clamped to tools.web.fetch.maxCharsCap.
web_fetch caps the downloaded response body size to tools.web.fetch.maxResponseBytes before parsing; oversized responses are truncated and include a warning.
web_fetch is best-effort extraction; some sites will need the browser tool.
See Firecrawl for key setup and service details.
Responses are cached (default 15 minutes) to reduce repeated fetches.
If you use tool profiles/allowlists, add web_search/web_fetch or group:web.
If no provider is configured and no API keys are found, web_search is not registered (check logs for provider details).

Getting started

Talking to your AI

Built-in tools

Help

Users

Automation

CLI command reference

Help and FAQ

Media nodes

Setup and onboarding

Voice and realtime

More agent tools

Shohin

Web Tools

Web tools

How it works

Choosing a search provider

Auto-detection

Explicit provider

Getting a Brave API key

Where to set the key (recommended)

Using Perplexity (direct or via OpenRouter)

Getting an OpenRouter API key

Setting up Perplexity search

Available Perplexity models

Using Gemini (Google Search grounding)

Getting a Gemini API key

Setting up Gemini search

Notes

Using SearXNG (self-hosted)

Setting up SearXNG search

SearXNG notes

web_search

Requirements

Config

Tool parameters

web_fetch

web_fetch requirements

web_fetch config

web_fetch tool parameters

​Web tools

​How it works

​Choosing a search provider

​Auto-detection

​Explicit provider

​Getting a Brave API key

​Where to set the key (recommended)

​Using Perplexity (direct or via OpenRouter)

​Getting an OpenRouter API key

​Setting up Perplexity search

​Available Perplexity models

​Using Gemini (Google Search grounding)

​Getting a Gemini API key

​Setting up Gemini search

​Notes

​Using SearXNG (self-hosted)

​Setting up SearXNG search

​SearXNG notes

​web_search

​Requirements

​Config

​Tool parameters

​web_fetch

​web_fetch requirements

​web_fetch config

​web_fetch tool parameters

Web tools

How it works

Choosing a search provider

Auto-detection

Explicit provider

Getting a Brave API key

Where to set the key (recommended)

Using Perplexity (direct or via OpenRouter)

Getting an OpenRouter API key

Setting up Perplexity search

Available Perplexity models

Using Gemini (Google Search grounding)

Getting a Gemini API key

Setting up Gemini search

Notes

Using SearXNG (self-hosted)

Setting up SearXNG search

SearXNG notes

web_search

Requirements

Config

Tool parameters

web_fetch

web_fetch requirements

web_fetch config

web_fetch tool parameters