From 0a8eb7fdf0556d350d07d438b349b1699e19f600 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 22 Mar 2026 21:17:10 -0700 Subject: [PATCH] docs(tools): add DuckDuckGo Search provider page New page: tools/duckduckgo-search.md - Key-free fallback provider, no API key needed - Clear Warning about unofficial HTML-based integration - Limitations section covering bot-challenge risk and reliability - CardGroup showing good-for vs not-recommended-for use cases Updated: tools/web.md with DuckDuckGo in CardGroup and comparison table Updated: docs.json nav and redirect --- docs/docs.json | 5 ++ docs/tools/duckduckgo-search.md | 117 ++++++++++++++++++++++++++++++++ docs/tools/web.md | 4 ++ 3 files changed, 126 insertions(+) create mode 100644 docs/tools/duckduckgo-search.md diff --git a/docs/docs.json b/docs/docs.json index 422c0842e74..66385de78c2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -88,6 +88,10 @@ "source": "/web-fetch", "destination": "/tools/web-fetch" }, + { + "source": "/duckduckgo-search", + "destination": "/tools/duckduckgo-search" + }, { "source": "/gemini-search", "destination": "/tools/gemini-search" @@ -1122,6 +1126,7 @@ "tools/web-fetch", "tools/web", "tools/brave-search", + "tools/duckduckgo-search", "tools/firecrawl", "tools/gemini-search", "tools/grok-search", diff --git a/docs/tools/duckduckgo-search.md b/docs/tools/duckduckgo-search.md new file mode 100644 index 00000000000..c65198e7008 --- /dev/null +++ b/docs/tools/duckduckgo-search.md @@ -0,0 +1,117 @@ +--- +summary: "DuckDuckGo web search -- key-free fallback provider (unofficial, HTML-based)" +read_when: + - You want a web search provider that requires no API key + - You want to use DuckDuckGo for web_search + - You need a zero-config search fallback +title: "DuckDuckGo Search" +--- + +# DuckDuckGo Search + +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. + + +## Quick start + +DuckDuckGo requires no API key. Just set it 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 + +## Config + +```json5 +{ + tools: { + web: { + search: { + enabled: true, + provider: "duckduckgo", + }, + }, + }, +} +``` + +No `plugins.entries` config is needed — DuckDuckGo has no API key or plugin-specific settings. + +## Supported parameters + +DuckDuckGo search supports the standard `query` and `count` parameters. +Provider-specific filters like `country`, `language`, `freshness`, and +`domain_filter` are not supported. + +## Limitations + +- **Unofficial integration** — not backed by a DuckDuckGo 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 + +## 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. + +## 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) diff --git a/docs/tools/web.md b/docs/tools/web.md index 872295d7404..7238d47d4bb 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -49,6 +49,9 @@ returns results. Results are cached by query for 15 minutes (configurable). Structured results with snippets. Supports `llm-context` mode, country/language filters. Free tier available. + + Key-free fallback. No API key needed. Unofficial HTML-based integration. + Structured results. Best paired with `firecrawl_search` and `firecrawl_scrape` for deep extraction. @@ -74,6 +77,7 @@ returns results. Results are cached by query for 15 minutes (configurable). | 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) | | [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` |