diff --git a/docs/docs.json b/docs/docs.json index 66385de78c2..688e283c2f6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -92,6 +92,10 @@ "source": "/duckduckgo-search", "destination": "/tools/duckduckgo-search" }, + { + "source": "/exa-search", + "destination": "/tools/exa-search" + }, { "source": "/gemini-search", "destination": "/tools/gemini-search" @@ -1127,6 +1131,7 @@ "tools/web", "tools/brave-search", "tools/duckduckgo-search", + "tools/exa-search", "tools/firecrawl", "tools/gemini-search", "tools/grok-search", diff --git a/docs/tools/brave-search.md b/docs/tools/brave-search.md index 12cd78c358f..d3d5d43cf97 100644 --- a/docs/tools/brave-search.md +++ b/docs/tools/brave-search.md @@ -90,4 +90,8 @@ await web_search({ - The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service). - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`). -See [Web tools](/tools/web) for the full web_search configuration. +## Related + +- [Web Search overview](/tools/web) -- all providers and auto-detection +- [Perplexity Search](/tools/perplexity-search) -- structured results with domain filtering +- [Exa Search](/tools/exa-search) -- neural search with content extraction diff --git a/docs/tools/duckduckgo-search.md b/docs/tools/duckduckgo-search.md index c65198e7008..a8ee667156b 100644 --- a/docs/tools/duckduckgo-search.md +++ b/docs/tools/duckduckgo-search.md @@ -13,52 +13,23 @@ OpenClaw supports DuckDuckGo as a **key-free** `web_search` provider. No API key or account is required. - DuckDuckGo is an **unofficial, HTML-based** integration. It scrapes - DuckDuckGo's non-JavaScript search pages, not an official API or SDK. - Expect occasional breakage from bot-challenge pages or HTML changes. - Use it as a convenient fallback, not a production-grade provider. + DuckDuckGo is an **unofficial, HTML-based** integration, not an official API. + Expect occasional breakage from bot-challenge pages or HTML changes. Use it + as a convenient fallback, not a production-grade provider. -## Quick start +## Setup -DuckDuckGo requires no API key. Just set it as your provider: +No API key needed. Set DuckDuckGo as your provider: -```bash -openclaw configure --section web -# Select "duckduckgo" as the provider -``` - -Or set the provider directly in config: - -```json5 -{ - tools: { - web: { - search: { - provider: "duckduckgo", - }, - }, - }, -} -``` - -That's it — no keys, no plugin config, no environment variables. - -## How it works - -Unlike API-backed providers (Brave, Perplexity, Tavily), DuckDuckGo search -works by: - -1. Sending an HTTP request to DuckDuckGo's non-JavaScript search endpoint -2. Parsing the HTML response to extract search results -3. Returning structured results with titles, URLs, and snippets - -This approach means: - -- **No API key needed** — works out of the box -- **No rate limits from an API plan** — but DuckDuckGo may serve bot-challenge - pages under heavy use -- **Results may differ** from what you see in DuckDuckGo's full web interface + + + ```bash + openclaw configure --section web + # Select "duckduckgo" as the provider + ``` + + ## Config @@ -67,7 +38,6 @@ This approach means: tools: { web: { search: { - enabled: true, provider: "duckduckgo", }, }, @@ -75,43 +45,38 @@ This approach means: } ``` -No `plugins.entries` config is needed — DuckDuckGo has no API key or plugin-specific settings. +No `plugins.entries` config is needed — DuckDuckGo has no API key or +plugin-specific settings. -## Supported parameters +## Tool parameters -DuckDuckGo search supports the standard `query` and `count` parameters. -Provider-specific filters like `country`, `language`, `freshness`, and -`domain_filter` are not supported. +| Parameter | Description | +| --------- | ------------------------------ | +| `query` | Search query (required) | +| `count` | Results to return (default: 5) | -## Limitations +DuckDuckGo does not support provider-specific filters like `country`, +`language`, `freshness`, or `domain_filter`. -- **Unofficial integration** — not backed by a DuckDuckGo API or SDK +## Notes + +- **No API key** — works out of the box, zero configuration +- **Unofficial** — scrapes DuckDuckGo's non-JavaScript search pages, not an + official API or SDK - **Bot-challenge risk** — DuckDuckGo may serve CAPTCHAs or block requests under heavy or automated use -- **HTML parsing** — results depend on DuckDuckGo's page structure, which can - change without notice -- **No advanced filters** — only `query` and `count` are supported -- **Best-effort reliability** — treat this as a fallback, not a primary - provider for production use +- **HTML parsing** — results depend on page structure, which can change without + notice +- **Best-effort reliability** — treat as a fallback for development, demos, or + environments where no API key is available -## When to use DuckDuckGo - - - - Quick local development, demos, testing, or environments where no API key - is available - - - Production gateways, high-volume search, or workflows requiring reliable - uptime - - - -For production use, consider [Brave Search](/tools/brave-search) (free tier -available) or another API-backed provider. + + For production use, consider [Brave Search](/tools/brave-search) (free tier + available) or another API-backed provider. + ## Related - [Web Search overview](/tools/web) -- all providers and auto-detection - [Brave Search](/tools/brave-search) -- structured results with free tier -- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers (also no search-specific key if you have a Gemini key) +- [Exa Search](/tools/exa-search) -- neural search with content extraction diff --git a/docs/tools/exa-search.md b/docs/tools/exa-search.md new file mode 100644 index 00000000000..1a1fe280500 --- /dev/null +++ b/docs/tools/exa-search.md @@ -0,0 +1,119 @@ +--- +summary: "Exa AI search -- neural and keyword search with content extraction" +read_when: + - You want to use Exa for web_search + - You need an EXA_API_KEY + - You want neural search or content extraction +title: "Exa Search" +--- + +# Exa Search + +OpenClaw supports [Exa AI](https://exa.ai/) as a `web_search` provider. Exa +offers neural, keyword, and hybrid search modes with built-in content +extraction (highlights, text, summaries). + +## Get an API key + + + + Sign up at [exa.ai](https://exa.ai/) and generate an API key from your + dashboard. + + + Set `EXA_API_KEY` in the Gateway environment, or configure via: + + ```bash + openclaw configure --section web + ``` + + + + +## Config + +```json5 +{ + plugins: { + entries: { + exa: { + config: { + webSearch: { + apiKey: "exa-...", // optional if EXA_API_KEY is set + }, + }, + }, + }, + }, + tools: { + web: { + search: { + provider: "exa", + }, + }, + }, +} +``` + +**Environment alternative:** set `EXA_API_KEY` in the Gateway environment. +For a gateway install, put it in `~/.openclaw/.env`. + +## Tool parameters + +| Parameter | Description | +| ------------- | ----------------------------------------------------------------------------- | +| `query` | Search query (required) | +| `count` | Results to return (1-100) | +| `type` | Search mode: `auto`, `neural`, `fast`, `deep`, `deep-reasoning`, or `instant` | +| `freshness` | Time filter: `day`, `week`, `month`, or `year` | +| `date_after` | Results after this date (YYYY-MM-DD) | +| `date_before` | Results before this date (YYYY-MM-DD) | +| `contents` | Content extraction options (see below) | + +### Content extraction + +Exa can return extracted content alongside search results. Pass a `contents` +object to enable: + +```javascript +await web_search({ + query: "transformer architecture explained", + type: "neural", + contents: { + text: true, // full page text + highlights: { numSentences: 3 }, // key sentences + summary: true, // AI summary + }, +}); +``` + +| Contents option | Type | Description | +| --------------- | --------------------------------------------------------------------- | ---------------------- | +| `text` | `boolean \| { maxCharacters }` | Extract full page text | +| `highlights` | `boolean \| { maxCharacters, query, numSentences, highlightsPerUrl }` | Extract key sentences | +| `summary` | `boolean \| { query }` | AI-generated summary | + +### Search modes + +| Mode | Description | +| ---------------- | --------------------------------- | +| `auto` | Exa picks the best mode (default) | +| `neural` | Semantic/meaning-based search | +| `fast` | Quick keyword search | +| `deep` | Thorough deep search | +| `deep-reasoning` | Deep search with reasoning | +| `instant` | Fastest results | + +## Notes + +- `freshness` and `date_after`/`date_before` cannot be combined — use one + time-filter mode +- Results are cached for 15 minutes by default (configurable via + `cacheTtlMinutes`) +- Exa is an official API integration with structured JSON responses + +## Related + +- [Web Search overview](/tools/web) -- all providers and auto-detection +- [Brave Search](/tools/brave-search) -- structured results with country/language filters +- [Perplexity Search](/tools/perplexity-search) -- structured results with domain filtering diff --git a/docs/tools/firecrawl.md b/docs/tools/firecrawl.md index 01740ed303e..0ba5ac1ad95 100644 --- a/docs/tools/firecrawl.md +++ b/docs/tools/firecrawl.md @@ -137,4 +137,8 @@ than basic-only scraping. 2. Firecrawl (if configured) 3. Basic HTML cleanup (last fallback) -See [Web Search](/tools/web) for the full provider setup and comparison. +## Related + +- [Web Search overview](/tools/web) -- all providers and auto-detection +- [Web Fetch](/tools/web-fetch) -- web_fetch tool with Firecrawl fallback +- [Tavily](/tools/tavily) -- search + extract tools diff --git a/docs/tools/perplexity-search.md b/docs/tools/perplexity-search.md index 0d8e2735b42..41001325ab7 100644 --- a/docs/tools/perplexity-search.md +++ b/docs/tools/perplexity-search.md @@ -170,5 +170,9 @@ await web_search({ - OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`) -See [Web tools](/tools/web) for the full web_search configuration. -See [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) for more details. +## Related + +- [Web Search overview](/tools/web) -- all providers and auto-detection +- [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) -- official Perplexity documentation +- [Brave Search](/tools/brave-search) -- structured results with country/language filters +- [Exa Search](/tools/exa-search) -- neural search with content extraction diff --git a/docs/tools/tavily.md b/docs/tools/tavily.md index 25a31a74f76..8b055a35116 100644 --- a/docs/tools/tavily.md +++ b/docs/tools/tavily.md @@ -122,4 +122,8 @@ Tips: | Search with depth, topic, AI answers | `tavily_search` | | Extract content from specific URLs | `tavily_extract` | -See [Web Search](/tools/web) for the full provider setup and comparison. +## Related + +- [Web Search overview](/tools/web) -- all providers and auto-detection +- [Firecrawl](/tools/firecrawl) -- search + scraping with content extraction +- [Exa Search](/tools/exa-search) -- neural search with content extraction diff --git a/docs/tools/web.md b/docs/tools/web.md index 7238d47d4bb..8f682f244a9 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -52,6 +52,9 @@ returns results. Results are cached by query for 15 minutes (configurable). Key-free fallback. No API key needed. Unofficial HTML-based integration. + + Neural + keyword search with content extraction (highlights, text, summaries). + Structured results. Best paired with `firecrawl_search` and `firecrawl_scrape` for deep extraction. @@ -78,6 +81,7 @@ returns results. Results are cached by query for 15 minutes (configurable). | -------------------------------------- | -------------------------- | ------------------------------------------------ | ------------------------------------------- | | [Brave](/tools/brave-search) | Structured snippets | Country, language, time, `llm-context` mode | `BRAVE_API_KEY` | | [DuckDuckGo](/tools/duckduckgo-search) | Structured snippets | -- | None (key-free) | +| [Exa](/tools/exa-search) | Structured + extracted | Neural/keyword mode, date, content extraction | `EXA_API_KEY` | | [Firecrawl](/tools/firecrawl) | Structured snippets | Via `firecrawl_search` tool | `FIRECRAWL_API_KEY` | | [Gemini](/tools/gemini-search) | AI-synthesized + citations | -- | `GEMINI_API_KEY` | | [Grok](/tools/grok-search) | AI-synthesized + citations | -- | `XAI_API_KEY` |