跳到正文
DEV Community· AgentSearch·· 2 小時前AI 評分59

如何透過 AgentSearch 為 OpenClaw 加入免費網頁搜尋(無需 API key)

How to Add Web Search to OpenClaw (Free, No API Key)

AI 導讀

AgentSearch 插件可為 OpenClaw 的 web_search 工具加入免 API key 的網頁搜尋,無需帳戶,免費模式每個 IP 每日最多 25 次。插件需從 npm 安裝,並由用戶手動選為搜尋供應商;設置錢包後,每次搜尋收費 $0.003 USDC(Base),預設每個 gateway process 支出上限為 $1.00。

正文

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:

  1. Install the plugin from npm.
  2. Select AgentSearch as your web_search provider (OpenClaw makes you do this once).
  3. Check it with openclaw infer web.
  4. 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.

  1. 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.
  2. 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 a privateKey field. AGENTSEARCH_WALLET_FILE=agentcash reuses 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 (or AGENTSEARCH_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 (or AGENTSEARCH_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.

來源:DEV Community · dev.to