diff --git a/docs/docs.json b/docs/docs.json
index 44503345279..cef0331dad2 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1156,6 +1156,7 @@
"tools/grok-search",
"tools/kimi-search",
"tools/perplexity-search",
+ "tools/searxng-search",
"tools/tavily"
]
},
diff --git a/docs/tools/searxng-search.md b/docs/tools/searxng-search.md
new file mode 100644
index 00000000000..5dbbb49853c
--- /dev/null
+++ b/docs/tools/searxng-search.md
@@ -0,0 +1,124 @@
+---
+summary: "SearXNG web search -- self-hosted, key-free meta-search provider"
+read_when:
+ - You want a self-hosted web search provider
+ - You want to use SearXNG for web_search
+ - You need a privacy-focused or air-gapped search option
+title: "SearXNG Search"
+---
+
+# SearXNG Search
+
+OpenClaw supports [SearXNG](https://docs.searxng.org/) as a **self-hosted,
+key-free** `web_search` provider. SearXNG is an open-source meta-search engine
+that aggregates results from Google, Bing, DuckDuckGo, and other sources.
+
+Advantages:
+
+- **Free and unlimited** -- no API key or commercial subscription required
+- **Privacy / air-gap** -- queries never leave your network
+- **Works anywhere** -- no region restrictions on commercial search APIs
+
+## Setup
+
+
+
+ ```bash
+ docker run -d -p 8888:8080 searxng/searxng
+ ```
+
+ Or use any existing SearXNG deployment you have access to. See the
+ [SearXNG documentation](https://docs.searxng.org/) for production setup.
+
+
+
+ ```bash
+ openclaw configure --section web
+ # Select "searxng" as the provider
+ ```
+
+ Or set the env var and let auto-detection find it:
+
+ ```bash
+ export SEARXNG_BASE_URL="http://localhost:8888"
+ ```
+
+
+
+
+## Config
+
+```json5
+{
+ tools: {
+ web: {
+ search: {
+ provider: "searxng",
+ },
+ },
+ },
+}
+```
+
+Plugin-level settings for the SearXNG instance:
+
+```json5
+{
+ plugins: {
+ entries: {
+ searxng: {
+ config: {
+ webSearch: {
+ baseUrl: "http://localhost:8888",
+ categories: "general,news", // optional
+ language: "en", // optional
+ },
+ },
+ },
+ },
+ },
+}
+```
+
+The `baseUrl` field also accepts SecretRef objects.
+
+## Environment variable
+
+Set `SEARXNG_BASE_URL` as an alternative to config:
+
+```bash
+export SEARXNG_BASE_URL="http://localhost:8888"
+```
+
+When `SEARXNG_BASE_URL` is set and no explicit provider is configured, auto-detection
+picks SearXNG automatically (at the lowest priority -- any API-backed provider with a
+key wins first).
+
+## Plugin config reference
+
+| Field | Description |
+| ------------ | ------------------------------------------------------------------ |
+| `baseUrl` | Base URL of your SearXNG instance (required) |
+| `categories` | Comma-separated categories such as `general`, `news`, or `science` |
+| `language` | Language code for results such as `en`, `de`, or `fr` |
+
+## Notes
+
+- **JSON API** -- uses SearXNG's native `format=json` endpoint, not HTML scraping
+- **No API key** -- works with any SearXNG instance out of the box
+- **Auto-detection order** -- SearXNG is checked last (order 200) in auto-detection,
+ so any API-backed provider with a key takes priority over SearXNG, and SearXNG sits
+ behind DuckDuckGo (order 100) as well
+- **Self-hosted** -- you control the instance, queries, and upstream search engines
+- **Categories** default to `general` when not configured
+
+
+ For SearXNG JSON API to work, make sure your SearXNG instance has the `json`
+ format enabled in its `settings.yml` under `search.formats`.
+
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [DuckDuckGo Search](/tools/duckduckgo-search) -- another key-free fallback
+- [Brave Search](/tools/brave-search) -- structured results with free tier
diff --git a/docs/tools/web.md b/docs/tools/web.md
index 60538cc5950..c2dc094522c 100644
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -81,6 +81,9 @@ local while `web_search` and `x_search` can use xAI Responses under the hood.
Structured results with content extraction controls and domain filtering.
+
+ Self-hosted meta-search. No API key needed. Aggregates Google, Bing, DuckDuckGo, and more.
+
Structured results with search depth, topic filtering, and `tavily_extract` for URL extraction.
@@ -98,6 +101,7 @@ local while `web_search` and `x_search` can use xAI Responses under the hood.
| [Grok](/tools/grok-search) | AI-synthesized + citations | -- | `XAI_API_KEY` |
| [Kimi](/tools/kimi-search) | AI-synthesized + citations | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [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
@@ -153,8 +157,13 @@ the first one found:
6. **Firecrawl** -- `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey`
7. **Tavily** -- `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey`
-If no keys are found, it falls back to Brave (you will get a missing-key error
-prompting you to configure one).
+Key-free providers are checked after API-backed providers:
+
+8. **DuckDuckGo** -- no key needed (auto-detect order 100)
+9. **SearXNG** -- `SEARXNG_BASE_URL` or `plugins.entries.searxng.config.webSearch.baseUrl` (auto-detect order 200)
+
+If no provider is detected, it falls back to Brave (you will get a missing-key
+error prompting you to configure one).
All provider key fields support SecretRef objects. In auto-detect mode,