npm package: @sage-pai/openclaw-ddg-search
Description: DuckDuckGo web search plugin for OpenClaw — free, no API key, no rate limits
Author: Sage
Latest version: 2026.2.15

# @sage-pai/openclaw-ddg-search

DuckDuckGo web search plugin for [OpenClaw](https://github.com/openclaw/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`](https://github.com/sage-pai/ddg-search) library.

## Install

```bash
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`):

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

Then restart the gateway:

```bash
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