How to Set Up OpenClaw Web Search: Complete Guide to Every Provider (2026)

Why Your OpenClaw Agent Needs Web Search

Before diving into setup, let's be clear about what web search unlocks:

• **Real-time information:** News, weather, stock prices, sports scores, flight status — anything that changes by the hour
• **Fact verification:** Your agent can check claims against live sources instead of guessing from training data
• **Technical lookups:** Latest API docs, package versions, changelogs, GitHub issues
• **Research depth:** When you ask your agent to research a topic, it pulls from current sources rather than knowledge frozen at a cutoff date
• **Reduced hallucination:** An agent that can search doesn't need to fabricate answers

How OpenClaw Web Search Works (Architecture Overview)

OpenClaw's web search isn't a single integration — it's a pluggable system with 12 providers, auto-detection logic, and caching built in. Here's how the pieces fit:

There are also two companion tools: **`web_fetch`** — fetches a specific URL and extracts readable content (works locally, no API key needed), and **`x_search`** — searches X (formerly Twitter) posts via xAI. All three are part of the `group:web` tool group and can be enabled/disabled independently.

• **Your agent calls `web_search()`** — either automatically when it needs current info, or when you explicitly ask it to look something up
• **OpenClaw routes the request** to your configured provider (or auto-detects one from available API keys)
• **The provider returns results** — structured snippets for most providers, or AI-synthesized answers for Gemini/Grok/Kimi
• **Results are cached** for 15 minutes (configurable) to avoid redundant API calls
• **Your agent reads the results** and incorporates them into its response

Every OpenClaw Web Search Provider Compared

Here's the full comparison of all 12 supported providers as of April 2026:

Brave Search provides structured snippets, requires `BRAVE_API_KEY`, has a free tier of 2,000 req/mo, and is best for general purpose use. DuckDuckGo provides structured snippets, requires no API key, has unlimited free usage, and is best as a zero-config fallback. SearXNG provides structured snippets, requires no API key (self-hosted), has unlimited free usage, and is best for privacy maximalists. Tavily provides structured snippets, requires `TAVILY_API_KEY`, has a free tier of 1,000 req/mo, and is best for AI/RAG applications. Gemini provides AI-synthesized answers with citations, requires `GEMINI_API_KEY`, has a free tier of 1,500 req/day, and is best for Google ecosystem users. Grok provides AI-synthesized answers with citations, requires `XAI_API_KEY`, has a varying free tier, and is best for X/Twitter integration. Kimi provides AI-synthesized answers with citations, requires `KIMI_API_KEY`, has a varying free tier, and is best for Chinese-language search. Perplexity provides structured snippets, requires `PERPLEXITY_API_KEY`, is paid only, and is best for domain filtering and deep content. Exa provides structured and extracted results, requires `EXA_API_KEY`, has a free tier of 1,000 req/mo, and is best for neural/semantic search. Firecrawl provides structured snippets, requires `FIRECRAWL_API_KEY`, has a free tier of 500 pages/mo, and is best for deep web scraping. MiniMax Search provides structured snippets, requires `MINIMAX_CODE_PLAN_KEY`, has a varying free tier, and is best for Asian market coverage. Ollama Web Search provides structured snippets, requires no API key (needs `ollama signin`), has unlimited free usage, and is best for local Ollama users.

**Understanding Result Types:** **Structured snippets** return individual results with titles, URLs, and text snippets — like traditional search engine results. Your agent sees multiple sources and decides what's relevant. **AI-synthesized answers** (Gemini, Grok, Kimi) return a single pre-digested answer with citations. This means the search provider's AI has already interpreted the results. This can be faster for simple questions but gives your agent less raw material to work with. For most users, structured snippets are preferable because they let your OpenClaw agent do its own reasoning over multiple sources.

Quick Start: The Fastest Way to Enable Web Search

If you just want web search working in under 60 seconds, here's the path of least resistance:

**Option A: DuckDuckGo (Zero Config, Zero Cost):** DuckDuckGo requires no API key at all. If OpenClaw can't find any other provider, it falls back to DuckDuckGo automatically. But to set it explicitly:

That's it. No API key, no signup, no billing. The tradeoff: DuckDuckGo's unofficial HTML-based integration is less reliable than API-backed providers and lacks advanced filters.

**Option B: Brave Search (Recommended Default):** Brave is OpenClaw's officially recommended provider. The free tier gives you 2,000 searches per month — plenty for personal use.

**Step 1:** Sign up at api-dashboard.search.brave.com and grab your API key.

**Step 2:** Run the interactive setup:

Select **Brave Search** when prompted and paste your API key.

**Step 3:** Verify it works by asking your agent something time-sensitive:

Your agent should now search the web and give you a current answer.

**Manual Brave Configuration:** If you prefer editing config files directly:

Or set the environment variable:

Brave supports powerful filters that other providers don't:

// openclaw.json
{
  tools: {
    web: {
      search: {
        provider: "duckduckgo"
      }
    }
  }
}

openclaw configure --section web

// openclaw.json
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BSA..." // Your Brave API key
          }
        }
      }
    }
  }
}

# Add to ~/.openclaw/.env
BRAVE_API_KEY=BSAxxxxxxxxxxxxxxxxx

// Country-specific search
await web_search({ query: "best restaurants", country: "JP", language: "ja" });

// Only recent results
await web_search({ query: "OpenClaw update", freshness: "week" });

// Date range
await web_search({
  query: "AI agent news",
  date_after: "2026-03-01",
  date_before: "2026-04-01"
});

Setting Up Every Provider: Step-by-Step

**Gemini Search (Google Grounding):** If you already have a Gemini API key for your model provider, enabling Gemini as your search provider is a natural fit — no extra signup needed.

Or via environment variable:

**What makes Gemini different:** Instead of returning raw search results, Gemini uses Google Search grounding to produce an AI-synthesized answer with inline citations. This means your agent gets a pre-processed answer rather than a list of links. **Best for:** Users already on the Google Gemini ecosystem who want search without adding another API key.

**Grok Search (xAI Web + X Search):** Grok is unique because it also powers `x_search` — letting your agent search X (Twitter) posts natively.

With this configured, your agent gets both `web_search` and `x_search`. **Best for:** Users who need social media monitoring alongside web search.

**Perplexity Search:** Perplexity offers domain filtering and per-page content limits — useful for research workflows where you want to exclude or include specific sources.

**Note:** Perplexity also works via OpenRouter. If you have `OPENROUTER_API_KEY` set, OpenClaw can use it as a Perplexity backend automatically.

**Tavily Search:** Tavily was built specifically for AI agents and RAG (Retrieval-Augmented Generation) pipelines. It returns structured results with built-in content extraction.

You can also connect Tavily as an MCP server for advanced features. **Best for:** Heavy research workflows and users building RAG applications on top of OpenClaw.

**Exa Neural Search:** Exa combines traditional keyword search with neural/semantic search, plus built-in content extraction (highlights, summaries, full text). **Best for:** Research-heavy use cases where you want semantically similar results, not just keyword matches.

**SearXNG (Self-Hosted, Zero Cost):** SearXNG is a self-hosted meta-search engine that aggregates results from Google, Bing, DuckDuckGo, and dozens more — without any API keys or rate limits. The tradeoff: you need to run your own SearXNG instance.

**Step 1:** Deploy SearXNG with Docker:

**Step 2:** Configure OpenClaw to use your SearXNG instance:

Or via environment variable:

**Important security note:** SearXNG accepts `http://` only for trusted private-network or loopback hosts. Public SearXNG endpoints must use `https://`. **Best for:** Privacy-focused users, homelab enthusiasts, and anyone who wants unlimited searches at zero recurring cost.

**Ollama Web Search (Key-Free via Ollama):** If you're already running Ollama for local model inference, you can piggyback on it for web search too — no extra API key needed. Prerequisites: Ollama must be running and reachable, and you need to run `ollama signin` to authenticate. **Best for:** Users who already have Ollama configured and want to minimize external API dependencies.

**Firecrawl and MiniMax:** These are more specialized providers. **Firecrawl** excels at deep web scraping and content extraction. Pair it with `firecrawl_search` and `firecrawl_scrape` for workflows that need to read entire pages. **MiniMax Search** provides structured results via the MiniMax Coding Plan API, with region support for global or Chinese markets.

{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza..." // Your Gemini API key
          }
        }
      }
    }
  }
}

export GEMINI_API_KEY=AIzaSy...

{
  plugins: {
    entries: {
      xai: {
        config: {
          webSearch: {
            apiKey: "xai-..." // Your xAI API key
          },
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            cacheTtlMinutes: 15
          }
        }
      }
    }
  }
}

// Web search
await web_search({ query: "OpenClaw latest features" });

// X/Twitter search
await x_search({
  query: "openclaw tips",
  from_date: "2026-03-01",
  allowed_x_handles: ["openclaw_ai"]
});

{
  plugins: {
    entries: {
      perplexity: {
        config: {
          webSearch: {
            apiKey: "pplx-..." // Your Perplexity API key
          }
        }
      }
    }
  }
}

// Exclude noisy domains
await web_search({
  query: "best AI frameworks 2026",
  domain_filter: ["-reddit.com", "-pinterest.com"],
  max_tokens: 25000,
  max_tokens_per_page: 2048
});

{
  plugins: {
    entries: {
      tavily: {
        config: {
          webSearch: {
            apiKey: "tvly-..." // Your Tavily API key
          }
        }
      }
    }
  }
}

openclaw mcp add --transport http --scope user tavily \
  "https://mcp.tavily.com/mcp/?tavilyApiKey=YOUR_KEY"

{
  plugins: {
    entries: {
      exa: {
        config: {
          webSearch: {
            apiKey: "exa-..." // Your Exa API key
          }
        }
      }
    }
  }
}

# docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888
    restart: unless-stopped

docker compose up -d

{
  tools: {
    web: {
      search: {
        provider: "searxng"
      }
    }
  },
  plugins: {
    entries: {
      searxng: {
        config: {
          webSearch: {
            baseUrl: "http://localhost:8888"
          }
        }
      }
    }
  }
}

export SEARXNG_BASE_URL=http://localhost:8888

{
  tools: {
    web: {
      search: {
        provider: "ollama"
      }
    }
  }
}

{
  plugins: {
    entries: {
      firecrawl: {
        config: {
          webSearch: {
            apiKey: "fc-..." // Your Firecrawl API key
          }
        }
      }
    }
  }
}

{
  plugins: {
    entries: {
      minimax: {
        config: {
          webSearch: {
            apiKey: "..." // Your MiniMax API key
          }
        }
      }
    }
  }
}

Auto-Detection: Let OpenClaw Figure It Out

If you don't explicitly set a provider, OpenClaw checks your available API keys in a specific priority order and uses the first one that works:

**Priority 1-9 (API-backed):** This means if you have both `BRAVE_API_KEY` and `GEMINI_API_KEY` set, OpenClaw will use Brave. To override this, explicitly set `provider` in your config.

• Brave (order 10)
• MiniMax (order 15)
• Gemini (order 20)
• Grok (order 30)
• Kimi (order 40)
• Perplexity (order 50)
• Firecrawl (order 60)
• Exa (order 65)
• Tavily (order 70)
• DuckDuckGo (order 100)
• Ollama Web Search (order 110)
• SearXNG (order 200)

Advanced Configuration

**Caching:** Results are cached for 15 minutes by default. Adjust this based on your needs:

Set to `0` to disable caching entirely (not recommended — it wastes API quota).

**Max Results:** Control how many results your agent receives:

More results give your agent more context but cost more tokens to process. For most use cases, 5 is the sweet spot.

**Tool Profiles and Allowlists:** If you're using OpenClaw's tool profiles, make sure web search is included:

**Native Codex Web Search:** If you're using Codex-capable models, OpenClaw can use the provider's native web search instead of its managed implementation. This only activates for Codex-capable models. Non-Codex models still use the regular managed search.

{
  tools: {
    web: {
      search: {
        cacheTtlMinutes: 30 // Cache for 30 minutes
      }
    }
  }
}

{
  tools: {
    web: {
      search: {
        maxResults: 8 // Default is 5
      }
    }
  }
}

{
  tools: {
    allow: ["web_search", "x_search", "web_fetch"]
    // Or use the group shorthand:
    // allow: ["group:web"]
  }
}

{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "San Francisco",
            timezone: "America/Los_Angeles"
          }
        }
      }
    }
  }
}

Cost Optimization: How to Keep Your Search Bill Under $5/Month

For personal use, you should never need to spend more than a few dollars on web search. Here's how:

Use the free tier for 100% savings — Brave (2K/mo), Tavily (1K/mo), Gemini (1.5K/day). Enable caching for approximately 30-50% savings — the default 15-min cache prevents duplicate queries. Lower max results for approximately 20% savings — set `maxResults: 3` for routine queries. Use DuckDuckGo as fallback for 100% savings — no API costs at all. Self-host SearXNG for 100% savings — only pay for server resources you're already using. Combine free tiers for 100% savings — use Brave as primary, DuckDuckGo as fallback.

**Real-world usage data:** A typical personal OpenClaw agent makes 20-50 web searches per day. At that rate, Brave's free tier of 2,000/month covers you comfortably. If you're doing heavy research (100+ searches/day), consider SearXNG or combining multiple free tiers.

Troubleshooting Common Issues

**"web_search is not available" or "No search provider configured":** No provider is configured and auto-detection found nothing. Fix — run the configuration wizard:

Or manually add any provider config to your `openclaw.json`.

**"BRAVE_API_KEY is missing" Even Though You Set It:** The environment variable isn't reaching the Gateway process. Fixes: Add it to `~/.openclaw/.env` (not your shell's `.env`), restart the gateway, and if running in Docker, ensure it's in your `docker-compose.yml` environment section.

**Search Returns Empty Results:** Causes and fixes: Rate limited — check if you've exceeded your free tier quota and switch to DuckDuckGo temporarily. Network issue — ensure your VPS/server can reach the provider's API endpoint. Timeout — increase the timeout.

**SearXNG Returns 403 or Connection Refused:** Fixes: Verify SearXNG is running with `curl http://localhost:8888`. Check the SearXNG settings file allows JSON output. If running in Docker, ensure both containers are on the same network.

**Agent Doesn't Use Web Search When It Should:** The agent is answering from training data without searching. Fix — you can nudge behavior through your SOUL.md:

**Brave `llm-context` Mode Errors:** Brave's `llm-context` mode rejects certain parameters. Don't use `freshness` or `ui_lang` with llm-context mode. `country` and `language` work fine.

openclaw configure --section web

echo 'BRAVE_API_KEY=BSAxxxxxxxx' >> ~/.openclaw/.env

openclaw gateway restart

{
  tools: {
    web: {
      search: {
        timeoutSeconds: 60 // Default is 30
      }
    }
  }
}

# searxng/settings.yml
search:
  formats:
    - html
    - json

## Web Search Policy
When answering questions about current events, prices, weather, news,
or anything that might have changed since your training data, always
use web_search first. Don't guess — verify.

// DON'T use these with llm-context mode:
await web_search({
  query: "test",
  freshness: "week",    // Not supported in llm-context
  ui_lang: "en-US"      // Not supported in llm-context
});

// DO use:
await web_search({
  query: "test",
  country: "US",        // Works fine
  language: "en"         // Works fine
});

Which Provider Should You Choose? (Decision Guide)

**Start here — Use Brave Search.** It's the officially recommended default, has a generous free tier, and supports the most parameters. For 90% of users, this is the right choice.

**On a budget — DuckDuckGo or SearXNG.** Both are free. DuckDuckGo is zero-config. SearXNG gives you unlimited searches with better quality, but requires running a Docker container.

**Already using Gemini — Add Gemini search.** If `GEMINI_API_KEY` is already configured for your model, you get search with zero additional setup.

**Need X/Twitter monitoring — Grok.** It's the only provider that also gives you `x_search` for social media monitoring.

**Heavy research — Tavily or Exa.** Both offer content extraction and are optimized for RAG workflows.

**Maximum privacy — SearXNG.** Self-hosted, no data leaves your server, no API keys to manage.

**Minimum maintenance — DuckDuckGo.** Literally nothing to configure or pay for.

How to Test Your Web Search Setup

After configuring any provider, run these quick tests:

**Test 1 — Current information:** Ask your agent "What's today's date and what major news happened today?" Your agent should search and return current news.

**Test 2 — Technical lookup:** Ask your agent "What's the latest version of Node.js?" It should return the actual current version, not a stale one.

**Test 3 — Check the provider in use:**

This will show your currently configured provider and settings.

**Test 4 — Check logs for search calls:** Your gateway logs will show `[web_search]` entries when the tool is invoked, including the provider used and result count.

openclaw configure --section web

Setting Up web_fetch Alongside Web Search

While `web_search` finds pages, `web_fetch` reads them. It works locally without any API key by default, converting web pages to clean markdown your agent can read.

For enhanced fetching (JavaScript-rendered pages, anti-bot protection), configure Firecrawl as the `web_fetch` backend:

The typical workflow: `web_search` finds relevant URLs, `web_fetch` extracts the full content, and your agent synthesizes an answer.

{
  tools: {
    web: {
      fetch: {
        provider: "firecrawl"
      }
    }
  },
  plugins: {
    entries: {
      firecrawl: {
        config: {
          webFetch: {
            apiKey: "fc-..."
          }
        }
      }
    }
  }
}

Conclusion

Setting up OpenClaw web search takes anywhere from zero seconds (DuckDuckGo auto-fallback) to about five minutes (Brave with API key). The payoff is massive: your agent goes from a smart-but-blind assistant to one that can actually verify, research, and stay current. For most users, the recommended path is: start with Brave Search (free tier, 2 minutes to set up), add SearXNG if you want unlimited self-hosted backup, enable `x_search` via Grok if you need social media monitoring, and tune caching and max results based on your usage patterns. Your agent is already smart. Give it eyes on the web and watch what happens.

Frequently asked questions