diff --git a/docs/brave-search.md b/docs/brave-search.md index f596f0c8c82..11fb19b2824 100644 --- a/docs/brave-search.md +++ b/docs/brave-search.md @@ -26,6 +26,7 @@ OpenClaw supports Brave Search API as a `web_search` provider. config: { webSearch: { apiKey: "BRAVE_API_KEY_HERE", + mode: "web", // or "llm-context" }, }, }, @@ -46,6 +47,11 @@ OpenClaw supports Brave Search API as a `web_search` provider. Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`. Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path. +`webSearch.mode` controls the Brave transport: + +- `web` (default): normal Brave web search with titles, URLs, and snippets +- `llm-context`: Brave LLM Context API with pre-extracted text chunks and sources for grounding + ## Tool parameters | Parameter | Description | @@ -54,6 +60,7 @@ Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but | `count` | Number of results to return (1-10, default: 5) | | `country` | 2-letter ISO country code (e.g., "US", "DE") | | `language` | ISO 639-1 language code for search results (e.g., "en", "de", "fr") | +| `search_lang` | Brave search-language code (e.g., `en`, `en-gb`, `zh-hans`) | | `ui_lang` | ISO language code for UI elements | | `freshness` | Time filter: `day` (24h), `week`, `month`, or `year` | | `date_after` | Only results published after this date (YYYY-MM-DD) | @@ -88,6 +95,9 @@ await web_search({ - OpenClaw uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits. - Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans. - 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). +- `llm-context` mode returns grounded source entries instead of the normal web-search snippet shape. +- `llm-context` mode does not support `ui_lang`, `freshness`, `date_after`, or `date_before`. +- `ui_lang` must include a region subtag like `en-US`. - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`). See [Web tools](/tools/web) for the full web_search configuration. diff --git a/docs/perplexity.md b/docs/perplexity.md index bd7d6b30733..4bf64c91329 100644 --- a/docs/perplexity.md +++ b/docs/perplexity.md @@ -112,8 +112,14 @@ These parameters apply to the native Perplexity Search API path. | `max_tokens` | Total content budget (default: 25000, max: 1000000) | | `max_tokens_per_page` | Per-page token limit (default: 2048) | -For the legacy Sonar/OpenRouter compatibility path, only `query` and `freshness` are supported. -Search API-only filters such as `country`, `language`, `date_after`, `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page` return explicit errors. +For the legacy Sonar/OpenRouter compatibility path: + +- `query`, `count`, and `freshness` are accepted +- `count` is compatibility-only there; the response is still one synthesized + answer with citations rather than an N-result list +- Search API-only filters such as `country`, `language`, `date_after`, + `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page` + return explicit errors **Examples:** @@ -168,6 +174,7 @@ await web_search({ - Perplexity Search API returns structured web search results (`title`, `url`, `snippet`) - OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility +- Sonar/OpenRouter compatibility returns one synthesized answer with citations, not structured result rows - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`) See [Web tools](/tools/web) for the full web_search configuration. diff --git a/docs/reference/api-usage-costs.md b/docs/reference/api-usage-costs.md index b059b94792f..48cd6e81b23 100644 --- a/docs/reference/api-usage-costs.md +++ b/docs/reference/api-usage-costs.md @@ -96,10 +96,11 @@ See [Memory](/concepts/memory). - **Gemini (Google Search)**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey` - **Grok (xAI)**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey` - **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey` -- **Ollama Web Search**: key-free, but requires a reachable Ollama host plus `ollama signin` +- **Ollama Web Search**: key-free by default, but requires a reachable Ollama host plus `ollama signin`; can also reuse normal Ollama provider bearer auth when the host requires it - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**: `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey` - **DuckDuckGo**: key-free fallback (no API billing, but unofficial and HTML-based) +- **SearXNG**: key-free/self-hosted (no hosted API billing) Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface. diff --git a/docs/tools/web.md b/docs/tools/web.md index 42518d0c992..3bef2eb2d3f 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -96,19 +96,19 @@ local while `web_search` and `x_search` can use xAI Responses under the hood. ### Provider comparison -| Provider | Result style | Filters | API key | -| ----------------------------------------- | -------------------------- | ------------------------------------------------ | ------------------------------------------- | -| [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` | -| [Kimi](/tools/kimi-search) | AI-synthesized + citations | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | -| [Ollama Web Search](/tools/ollama-search) | Structured snippets | -- | None by default; `ollama signin` required | -| [Perplexity](/tools/perplexity-search) | Structured snippets | Country, language, time, domains, content limits | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | -| [SearXNG](/tools/searxng-search) | Structured snippets | Categories, language | None (self-hosted) | -| [Tavily](/tools/tavily) | Structured snippets | Via `tavily_search` tool | `TAVILY_API_KEY` | +| Provider | Result style | Filters | API key | +| ----------------------------------------- | -------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- | +| [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` | +| [Kimi](/tools/kimi-search) | AI-synthesized + citations | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | +| [Ollama Web Search](/tools/ollama-search) | Structured snippets | -- | None by default; `ollama signin` required, can reuse Ollama provider bearer auth | +| [Perplexity](/tools/perplexity-search) | Structured snippets | Country, language, time, domains, content limits | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | +| [SearXNG](/tools/searxng-search) | Structured snippets | Categories, language | None (self-hosted) | +| [Tavily](/tools/tavily) | Structured snippets | Via `tavily_search` tool | `TAVILY_API_KEY` | ## Auto-detection @@ -150,25 +150,27 @@ If native Codex search is enabled but the current model is not Codex-capable, Op ## Setting up web search Provider lists in docs and setup flows are alphabetical. Auto-detection keeps a -separate precedence order: +separate precedence order. If no `provider` is set, OpenClaw checks providers in this order and uses the first one that is ready: -1. **Brave** -- `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey` -2. **Gemini** -- `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey` -3. **Grok** -- `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey` -4. **Kimi** -- `KIMI_API_KEY` / `MOONSHOT_API_KEY` or `plugins.entries.moonshot.config.webSearch.apiKey` -5. **Perplexity** -- `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` or `plugins.entries.perplexity.config.webSearch.apiKey` -6. **Firecrawl** -- `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey` -7. **Exa** -- `EXA_API_KEY` or `plugins.entries.exa.config.webSearch.apiKey` -8. **Tavily** -- `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey` -9. **DuckDuckGo** -- key-free HTML fallback with no account or API key -10. **Ollama Web Search** -- key-free fallback via your configured Ollama host; requires Ollama to be reachable and signed in with `ollama signin` (reuses Ollama provider auth if the host needs bearer auth) +API-backed providers first: -Key-free providers are checked after API-backed providers: +1. **Brave** -- `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey` (order 10) +2. **Gemini** -- `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey` (order 20) +3. **Grok** -- `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey` (order 30) +4. **Kimi** -- `KIMI_API_KEY` / `MOONSHOT_API_KEY` or `plugins.entries.moonshot.config.webSearch.apiKey` (order 40) +5. **Perplexity** -- `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` or `plugins.entries.perplexity.config.webSearch.apiKey` (order 50) +6. **Firecrawl** -- `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey` (order 60) +7. **Exa** -- `EXA_API_KEY` or `plugins.entries.exa.config.webSearch.apiKey` (order 65) +8. **Tavily** -- `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey` (order 70) -11. **SearXNG** -- `SEARXNG_BASE_URL` or `plugins.entries.searxng.config.webSearch.baseUrl` (auto-detect order 200) +Key-free fallbacks after that: + +9. **DuckDuckGo** -- key-free HTML fallback with no account or API key (order 100) +10. **Ollama Web Search** -- key-free fallback via your configured Ollama host; requires Ollama to be reachable and signed in with `ollama signin` and can reuse Ollama provider bearer auth if the host needs it (order 110) +11. **SearXNG** -- `SEARXNG_BASE_URL` or `plugins.entries.searxng.config.webSearch.baseUrl` (order 200) If no provider is detected, it falls back to Brave (you will get a missing-key error prompting you to configure one).