How to Add Web Search to OpenClaw (Free, No API Key)
How to Add Web Search to OpenClaw (Free, No API Key) OpenClaw is an open-source AI assistant that runs on your own computer and answers you in the chat apps you already use. Its web_search tool needs a search provider,
How to Add Web Search to OpenClaw (Free, No API Key)
OpenClaw is an open-source AI assistant that runs on your own computer and answers you in the chat apps you already use. Its web_search tool needs a search provider, and most of the built-in choices want an API key before the first query.
This guide adds web search to OpenClaw with the AgentSearch provider plugin, @agentsearchhq/openclaw-web-search. It works right away with no API key, no signup and no wallet: up to 25 searches a day per IP. If you need more, give it a small wallet and each search costs $0.003 in USDC on Base over x402, with no daily cap.
You'll do four things:
- Install the plugin from npm.
- Select AgentSearch as your
web_searchprovider (OpenClaw makes you do this once). - Check it with
openclaw infer web. - Optionally add a wallet for paid search, with spend caps.
Every command below was run against OpenClaw 2026.11.5 and plugin 0.1.0 in a clean, isolated home directory: install, provider selection, plugin config and the provider check. We didn't run a live free search for this post; the free path is covered by the plugin's test suite.
What you get (and what it costs)
The plugin registers one provider, id agentsearch, for OpenClaw's web_search tool. Each search returns up to 5 ranked results with a title, URL, snippet, publish date and site name.
| Setup | Cost | Limits |
|---|---|---|
| No wallet | Free | Up to 25 searches a day per IP, no key |
Wallet set (default auto mode) |
$0.003 per search, USDC on Base | No daily cap; $1.00 per gateway process by default |
Wallet set + AGENTSEARCH_MODE=free
|
Free | Same as no wallet |
There's no account at any tier. Paid search uses x402: the API answers with a 402 price, the plugin signs a small USDC payment on Base, and the payment settles only when a usable answer comes back. Errors and empty result sets aren't charged. You don't need ETH for gas.
Step 1: Install the plugin
The plugin isn't on ClawHub yet, so install it from npm with the npm: prefix:
openclaw plugins install npm:@agentsearchhq/openclaw-web-search
OpenClaw warns that npm packages are outside ClawHub review and asks you to confirm, then asks you to accept the plugin's capabilities (it declares one: web-search: agentsearch). In a script or any shell without a prompt, pass both answers as flags:
openclaw plugins install npm:@agentsearchhq/openclaw-web-search --force --accept-capabilities
You should see Installed plugin: agentsearch and Saved for the next Gateway start. OpenClaw may also print a note that the plugin id agentsearch differs from the npm package name. That's expected: agentsearch is the id you use in config.
To see what was installed:
openclaw plugins inspect agentsearch
It lists Status: enabled, Version: 0.1.0 and Capabilities: web-search: agentsearch.
Step 2: Select AgentSearch as the search provider
OpenClaw does not auto-select key-free providers, and a plugin can't make itself the default. You pick it once, either from the setup wizard:
openclaw configure --section web
and choose AgentSearch, or with one command:
openclaw config set tools.web.search.provider agentsearch
The plugin never changes your search provider by itself, so if you switch back to another provider later, it stays switched.
Because the plugin was installed, restart the gateway so it loads:
openclaw gateway restart
Step 3: Check that it works
List the search providers:
openclaw infer web providers --json
The agentsearch entry should show "selected": true:
{ "available": true, "configured": true, "selected": true, "id": "agentsearch", "envVars": [] }
Then run one search from the command line, without involving a model:
openclaw infer web search --query "latest OpenClaw release" --json
With no wallet, that uses one of your free daily searches. From here, your assistant's web_search tool goes through AgentSearch in any chat.
When the gateway starts, it logs which mode search is in, for example "Search mode: free: AgentSearch free tier, up to 25 searches/day per IP (no wallet configured)". The tool description and every error message state the mode too, so you can always tell whether a search is free or paid.
Going past the free tier: pay per search with x402
Free search covers a lot of personal use. If your assistant needs more than 25 searches a day, or the extra filters, add a wallet. There's still no account: the plugin pays each search from a small wallet you control.
- Make a new, dedicated wallet and put a little USDC on Base in it, for example $1. Never use your main wallet. The wallet setup guide walks through it.
- Point the plugin at it in one of three ways:
-
Env var: set
AGENTSEARCH_WALLET_PRIVATE_KEY(the 64-hex key) in the gateway's environment. OpenClaw reads a global env file at~/.openclaw/.env, which is the usual place for keys like this. -
Existing wallet file: set
AGENTSEARCH_WALLET_FILE=/path/to/file. It can be a raw 64-hex key file or JSON with aprivateKeyfield.AGENTSEARCH_WALLET_FILE=agentcashreuses an AgentCash wallet at~/.agentcash/wallet.json. - Plugin config:
openclaw config set plugins.entries.agentsearch.config.webSearch.walletFile ~/.agentcash/wallet.json
Restart the gateway after changing env vars. With a wallet set, the default auto mode pays $0.003 per search and the startup log says "Search mode: paid". Paid mode also accepts the freshness, date-range, country, language and include/exclude-domain filters.
The plugin reads the key only to sign payments. The key never appears in logs, tool output or errors.
Spending limits
-
Per search: the plugin signs only USDC on Base, only to AgentSearch's published payee, and never more than $0.020 for one search.
webSearch.maxPerCallAtomic(orAGENTSEARCH_MAX_PER_CALL_ATOMIC) can lower that ceiling but not raise it. -
Per gateway process: total spend is capped at $1.00 by default. Change it with
webSearch.maxTotalAtomic(orAGENTSEARCH_MAX_TOTAL_ATOMIC), in USDC atomic units, where 1000000 is $1.00. The count starts over when the gateway restarts.
Because the cap resets on restart, the wallet balance is your real budget: a looping assistant can't spend more than you put in.
Keeping search free with a wallet set
If the same wallet is there for other tools and you want search to stay free, set the mode:
openclaw config set plugins.entries.agentsearch.config.webSearch.mode free
AGENTSEARCH_MODE=free in the gateway environment does the same, and env vars take precedence over plugin config. The modes are auto (the default: paid with a wallet, free without), free and paid.
Plugin settings reference
All plugin settings live under plugins.entries.agentsearch.config.webSearch:
| Key | Env var | Meaning |
|---|---|---|
mode |
AGENTSEARCH_MODE |
auto, free or paid
|
walletFile |
AGENTSEARCH_WALLET_FILE |
Existing wallet file, or agentcash
|
maxTotalAtomic |
AGENTSEARCH_MAX_TOTAL_ATOMIC |
Spend cap per gateway process (default 1000000 = $1.00) |
maxPerCallAtomic |
AGENTSEARCH_MAX_PER_CALL_ATOMIC |
Lower per-search ceiling |
The wallet key itself is env-only: AGENTSEARCH_WALLET_PRIVATE_KEY.
Reading pages, not just search results
The plugin covers web_search. If you also want your assistant to read full pages as clean markdown, or render JavaScript-heavy sites, add the AgentSearch MCP server through OpenClaw's MCP config:
openclaw mcp set agentsearch '{"command":"npx","args":["-y","@agentsearchhq/agentsearch-mcp"]}'
openclaw mcp probe
The probe should report agentsearch: 8 tools. Extract has a free trial of 5 pages a day per IP and render 3 a day per IP; after that they're pay per call over x402 with a wallet.
Direct x402 prices, all in USDC on Base:
| Tool | Price per call |
|---|---|
| Search | $0.003 |
| News search | $0.003 |
| Extract | $0.002 |
| Search + Read | $0.005 |
| Render | $0.005 |
| Screenshot | $0.004 |
Failed calls aren't charged. Full details are on the pricing page.
Troubleshooting
Install cancelled; rerun with --force after reviewing the source. You ran the install without a prompt (in a script, for example). Add --force --accept-capabilities, as in Step 1.
infer web providers doesn't show agentsearch as selected. Run openclaw config set tools.web.search.provider agentsearch again, then check openclaw plugins inspect agentsearch shows Status: enabled.
"AgentSearch free search limit reached". You've used the free searches for your IP today. Wait for the daily reset, or add a wallet as shown above.
You set a wallet but search is still free. Check the gateway log for the mode line. A mode of free in plugin config or AGENTSEARCH_MODE=free in the environment keeps search free. If you set the key in the environment, restart the gateway so it picks it up.
Filters seem to be ignored. Freshness, dates, country, language and domain filters apply in paid mode only.
FAQ
Do I need an AgentSearch account or API key?
No. Free search needs nothing at all. Paid search is signed from your own wallet over x402, so there's still no account or key.
Is the plugin on ClawHub?
Not yet. Install it from npm with openclaw plugins install npm:@agentsearchhq/openclaw-web-search. The source is on GitHub at agentsearchhq-coder/openclaw-agentsearch.
Why doesn't OpenClaw switch to AgentSearch automatically?
OpenClaw doesn't auto-select key-free search providers, and the plugin never edits your config by itself. Select it once with openclaw configure --section web or openclaw config set tools.web.search.provider agentsearch.
How much does paid search cost?
$0.003 per search in USDC on Base, with no daily cap. The plugin never signs more than $0.020 for one search and stops at $1.00 per gateway process by default. Errors and empty results aren't charged.
Can I keep search free if I have a wallet configured?
Yes. Set plugins.entries.agentsearch.config.webSearch.mode to free, or AGENTSEARCH_MODE=free in the gateway environment.
Get started
openclaw plugins install npm:@agentsearchhq/openclaw-web-search
openclaw config set tools.web.search.provider agentsearch
openclaw gateway restart
That's all it takes to give your OpenClaw assistant live web search, free to start. Read more about Search, Extract and Render, or see how the same tools work in Claude Code and a Mastra agent.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.