Tools
Agentsearch
AgentSearch web_search provider for OpenClaw: free tier with no key, x402 pay-per-search ($0.003, USDC on Base) when a wallet is set
Install
npm install
npm
README
# AgentSearch web search for OpenClaw
An OpenClaw plugin that adds **AgentSearch** as a `web_search` provider.
- **No wallet:** search uses the AgentSearch free tier. You need no key or account, and you get up to 25 searches per day per IP.
- **Wallet set:** search pays AgentSearch's own API over [x402](https://www.x402.org/). Each search costs **$0.003** in USDC on Base and has no daily cap. You need no ETH for gas.
- **Opt out:** `AGENTSEARCH_MODE=free` keeps search free even when a wallet is set.
Each search returns up to 5 ranked results, each with a title, URL, snippet, publish date and site name. In paid mode, search also takes the freshness, date-range, country, language and include/exclude-domain filters.
## Install
```bash
openclaw plugins install npm:@agentsearchhq/openclaw-web-search
openclaw config set tools.web.search.provider agentsearch
```
You can also run `openclaw configure --section web` and pick **AgentSearch**. Then restart the gateway.
OpenClaw does not auto-select key-free providers, so you have to select AgentSearch once, as shown above. The plugin never changes your search provider by itself.
To check it, run:
```bash
openclaw infer web providers --json # "agentsearch" shows selected: true
openclaw infer web search --query "latest OpenClaw release" --json
```
## Free vs paid
| Setup | Search goes to | Cost |
|---|---|---|
| No wallet | `relay.agentsearchhq.com` (free tier) | Free, up to 25 searches/day per IP |
| Wallet set (default `auto` mode) | `api.agentsearchhq.com/x402/v1/search` | $0.003 per search, USDC on Base |
| Wallet set + `AGENTSEARCH_MODE=free` | free tier | Free |
When the gateway starts, it logs the active mode, for example:
```
AgentSearch web_search provider registered (id "agentsearch"). Search mode: paid: x402 to AgentSearch's API, $0.003 per search (wallet configured; AGENTSEARCH_MODE=free keeps search free); wallet from AGENTSEARCH_WALLET_PRIVATE_KEY.
```
The tool description and every error message also state the mode. Each result payload carries an `agentsearch_mode` field. OpenClaw's normalized `web_search` output drops extra fields, but older hosts pass it through.
## Wallet
Use a **new** wallet that holds only a little USDC on Base (for example, $1). Set it in one of these three ways:
1. **Env var:** set `AGENTSEARCH_WALLET_PRIVATE_KEY=0x…` (64 hex characters) in the gateway's environment.
2. **Existing wallet file:** set `AGENTSEARCH_WALLET_FILE=/path/to/file`. The file can be either a raw 64-hex key file (such as a `wallet.key`) or JSON with a `privateKey` field. `AGENTSEARCH_WALLET_FILE=agentcash` reuses AgentCash's `~/.agentcash/wallet.json`.
3. **Plugin config:**
```bash
openclaw config set plugins.entries.agentsearch.config.webSearch.walletFile ~/.agentcash/wallet.json
```
The plugin reads the key only to sign the payment. The key never appears in logs, tool output or errors. Encrypted keystores and remote or CDP signers are not supported yet.
Wallet setup guide: <https://agentsearchhq.com/wallet-setup>
## Spending limits
- **Per search:** the plugin signs only USDC on Base, only to AgentSearch's published payee `0xC49B157887e51c21CB655f39CF65D6a4c2a4C337`, and never more than $0.020 per search (search costs $0.003). `AGENTSEARCH_MAX_PER_CALL_ATOMIC` or `webSearch.maxPerCallAtomic` can lower that ceiling.
- **Per gateway process:** spending is capped at $1.00 by default. Change it with `AGENTSEARCH_MAX_TOTAL_ATOMIC` or `webSearch.maxTotalAtomic`, in USDC atomic units (1000000 = $1.00).
- **Charges:** the API settles a payment only after a successful answer. Errors, 4xx/5xx responses and empty result sets are not charged.
## Configuration
Env vars take precedence over plugin config.
| Env var | Plugin config (`plugins.entries.agentsearch.config.webSearch.*`) | Meaning |
|---|---|---|
| `AGENTSEARCH_MODE` | `mode` | `auto` (default): paid with a wallet, free without one. `free`: always free. `paid`: pay (falls back to free if no wallet is set) |
| `AGENTSEARCH_WALLET_PRIVATE_KEY` | — | Wallet key (new wallet only) |
| `AGENTSEARCH_WALLET_FILE` | `walletFile` | Existing wallet file, or `agentcash` |
| `AGENTSEARCH_MAX_TOTAL_ATOMIC` | `maxTotalAtomic` | Spend cap per gateway process (default 1000000 = $1.00) |
| `AGENTSEARCH_MAX_PER_CALL_ATOMIC` | `maxPerCallAtomic` | Lower per-search ceiling |
| `AGENTSEARCH_PAYMENT_ROUTE=pocket` | — | Pay $0.005 per search through the Pocket Network Agentic Portal instead |
| `AGENTSEARCH_NO_CLIENT_TAG=1` | — | Don't send the anonymous `X-Agent-Client` package tag |
## Develop
```bash
npm install
npm test # builds, then runs the node:test suite (no network; HTTP is mocked)
```
## Links
- [AgentSearch docs](https://agentsearchhq.com/docs)
- [Pricing](https://agentsearchhq.com/pricing)
- [MCP server](https://www.npmjs.com/package/@agentsearchhq/agentsearch-mcp)
- [OpenClaw web search docs](https://docs.openclaw.ai/tools/web)
MIT licensed.
tools
Comments
Sign in to leave a comment