@sage-pai/openclaw-ddg-search

DuckDuckGo web search plugin for OpenClaw — free, no API key, no rate limits, privacy-respecting.

Replaces OpenClaw's built-in web_search tool (Brave/Perplexity/Grok) with DuckDuckGo via the ddg-search library.

Install

openclaw plugins install @sage-pai/openclaw-ddg-search

Required: Disable the Built-in web_search

You must disable the built-in web_search tool first, otherwise the plugin's tool will be silently ignored due to name conflict.

Add this to your OpenClaw config (~/.openclaw/openclaw.json):

{
  tools: {
    web: {
      search: {
        enabled: false,
      },
    },
  },
}

Then restart the gateway:

openclaw gateway restart

Configuration

All options are optional. Configure via the OpenClaw plugin settings:

| Option | Type | Default | Description | | ----------------- | ------- | -------------- | -------------------------------------------------------------------------------- | | maxPages | integer | 2 | Max DuckDuckGo result pages to scrape per query (1-10) | | maxResults | integer | 5 | Max results to return per query (1-20) | | region | string | "us-en" | DuckDuckGo region code (e.g. us-en, uk-en, de-de) | | cacheTtlMinutes | integer | 15 | Cache TTL in minutes. Set to 0 to disable caching | | toolName | string | "web_search" | Tool name: "web_search" (replaces built-in) or "ddg_search" (runs alongside) |

Alternative: Run Alongside the Built-in

If you want both DuckDuckGo and the built-in search available, set toolName to "ddg_search" in the plugin config. No need to disable the built-in in this case.

How It Works

1. The plugin registers a tool (default name: web_search) with OpenClaw's gateway
2. When an agent calls the tool, the plugin searches DuckDuckGo via HTML scraping (no API key needed)
3. Results are formatted as numbered entries with title, URL, and snippet
4. Results are cached in-memory for the configured TTL to avoid redundant requests

Tool Parameters

The registered tool accepts these parameters (passed by the LLM agent):

• query (string, required) — the search query
• count (integer, optional, default 5) — number of results (1-10)
• time (string, optional) — freshness filter: d (day), w (week), m (month), y (year)

Requirements

• Node.js 22+ (required by ddg-search)
• OpenClaw with plugin support

Troubleshooting

Tool not being called by agents

Make sure you've disabled the built-in web_search tool (see above). If both are registered with the same name, the built-in wins and the plugin is silently skipped.

Bot detection / empty results

DuckDuckGo may occasionally block scraping requests. The plugin will return an error message to the agent. Try again after a brief wait, or reduce maxPages to minimize request volume.

Node.js version error

The ddg-search library requires Node.js 22+. Check your version with node --version.

License

MIT