> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Tools

# 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](/tools/browser).

## 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](/brave-search) and [Perplexity Sonar](/perplexity) 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:

1. **Brave** — `BRAVE_API_KEY` env var or `plugins.entries.brave-search.config.webSearch.apiKey`
2. **Gemini** — `GEMINI_API_KEY` env var or `plugins.entries.gemini-search.config.webSearch.apiKey`
3. **Perplexity** — `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` env var or `plugins.entries.perplexity-search.config.webSearch.apiKey`
4. **Grok** — `XAI_API_KEY` env var or `plugins.entries.grok-search.config.webSearch.apiKey`
5. **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](#using-searxng-self-hosted)).

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:

```json5 theme={"dark"}
{
  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):

```json5 theme={"dark"}
{
  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

1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
2. In the dashboard, choose the **Data for Search** plan (not “Data for AI”) and generate an API key.
3. 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](/help/faq#how-does-openclaw-load-environment-variables).

## 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

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

### Setting up Perplexity search

```json5 theme={"dark"}
{
  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](https://ai.google.dev/gemini-api/docs/grounding),
which returns AI-synthesized answers backed by live Google Search results with citations.

### Getting a Gemini API key

1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
2. Create an API key
3. Set `GEMINI_API_KEY` in the Gateway environment, or configure `plugins.entries.gemini-search.config.webSearch.apiKey`

### Setting up Gemini search

```json5 theme={"dark"}
{
  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](https://searxng.github.io/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`):

```json5 theme={"dark"}
{
  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

```json5 theme={"dark"}
{
  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:**

```javascript theme={"dark"}
// 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

```json5 theme={"dark"}
{
  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](/tools/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).