🔍 web-search-plus-plugin

Multi-provider web search as a native OpenClaw tool.

A standalone OpenClaw plugin that registers web_search_plus as a first-class tool with intelligent auto-routing. No skill dependency needed — install, configure, and go.

✨ Features

• Intelligent auto-routing — analyzes query intent and picks the best provider automatically
• 7 search providers — use one or all, graceful fallback if any is down
• Local result caching — saves API costs on repeated queries
• Interactive setup wizard — guided configuration via python3 scripts/setup.py
• Native OpenClaw tool — registers as web_search_plus, not a skill

🔎 Supported Providers

| Provider | Best for | Free tier | |----------|----------|-----------| | Serper (Google) | Facts, news, shopping, local businesses | 2,500 queries/month | | Tavily | Deep research, analysis, explanations | 1,000 queries/month | | Querit | Multi-lingual AI search with rich metadata and real-time info | 1,000 queries/month | | Exa (Neural) | Semantic discovery, finding similar content | 1,000 queries/month | | Perplexity | AI-synthesized answers with citations | Via API key | | You.com | Real-time RAG, LLM-ready snippets | Limited free tier | | SearXNG | Privacy-first, self-hosted, $0 cost | Free (self-hosted) |

🧠 Auto-Routing Examples

The plugin analyzes your query and picks the best provider:

| Query | Routed to | Why | |-------|-----------|-----| | "iPhone 16 Pro price" | Serper | Shopping intent detected | | "how does TCP/IP work" | Tavily | Research/explanation intent | | "latest multilingual EV market updates" | Querit | Real-time AI search with metadata-rich results | | "companies like Stripe" | Exa | Discovery/semantic intent | | "what is quantum computing" | Perplexity | Direct answer intent | | "latest news AI regulation" | Serper | News intent |

You can always override with provider: "tavily" (or any other) to force a specific provider.

📦 Installation

Option 1: npm

npm install web-search-plus-plugin

Option 2: Clone

git clone https://github.com/robbyczgw-cla/web-search-plus-plugin.git

Configure API Keys

cp .env.template .env
# Edit .env and add your API keys (at least one required)

Add to OpenClaw Config

{
  "plugins": {
    "load": {
      "paths": [
        "./node_modules/web-search-plus-plugin"
      ]
    },
    "entries": {
      "web-search-plus-plugin": {
        "enabled": true
      }
    }
  }
}

Restart your gateway after adding the plugin.

🔑 Environment Variables

Copy .env.template to .env and add at least one API key:

| Variable | Provider | Sign up | |----------|----------|---------| | SERPER_API_KEY | Serper (Google) | console.serper.dev | | TAVILY_API_KEY | Tavily | tavily.com | | QUERIT_API_KEY | Querit | querit.ai | | EXA_API_KEY | Exa | exa.ai | | PERPLEXITY_API_KEY | Perplexity | perplexity.ai | | KILOCODE_API_KEY | Perplexity via Kilo | kilocode.ai | | YOU_API_KEY | You.com | you.com/api | | SEARXNG_URL | SearXNG (self-hosted) | docs.searxng.org |

🤖 Enable for an Agent

Allow the tool in your agent config:

{
  "agents": {
    "list": [
      {
        "name": "my-agent",
        "tools": {
          "allow": ["web_search_plus"]
        }
      }
    ]
  }
}

🛠️ Tool Parameters

The registered web_search_plus tool accepts:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | ✅ | Search query | | provider | string | ❌ | Force a provider: serper, tavily, querit, exa, perplexity, you, searxng, or auto (default) | | count | number | ❌ | Number of results (default: 5) |

🧪 Test Directly

You can test the search script standalone:

# Auto-route
python3 scripts/search.py -q "your query here"

# Force a specific provider
python3 scripts/search.py -q "your query" -p tavily

# More results
python3 scripts/search.py -q "your query" --max-results 10

❓ FAQ

Do I need all 7 providers?

No. The plugin works with just one API key. Configure whichever providers you have — the auto-router will use what's available and skip what's not.

What's the difference between this plugin and the web-search-plus skill?

The plugin registers a native tool that any agent can use directly. The skill provides a SKILL.md with instructions for the agent. Both use the same search backend. Use the plugin for cleaner integration — it's the recommended approach.

Do I need Python?

Yes, Python 3 is required. The search logic runs as a Python script. Most Linux servers and macOS have Python 3 pre-installed.

How does auto-routing work?

The router scores each provider based on query signals — keywords like "price" or "buy" boost Serper, deep explanation queries boost Tavily, multilingual or metadata-rich real-time search can favor Querit, semantic/discovery queries boost Exa, and direct questions boost Perplexity. The highest-scoring provider wins.

Does it cache results?

Yes. Results are cached locally in a .cache/ directory inside the plugin folder. Identical queries return cached results instantly and don't consume API credits. Cache is file-based and survives restarts.

Can I use Perplexity through Kilo Gateway?

Yes. Set KILOCODE_API_KEY in your .env — the plugin routes Perplexity requests through the Kilo Gateway automatically. You can also use a direct PERPLEXITY_API_KEY.

What about SearXNG?

SearXNG is a self-hosted meta search engine that aggregates 70+ sources. It's free but requires your own instance. The plugin validates the instance URL on setup and includes SSRF protection for security.

Does it work in sandboxed agents?

Yes, as long as the tool is allowed in the agent's tool config. The plugin runs on the host alongside the gateway.

📋 Requirements

• OpenClaw gateway (any recent version)
• Python 3 (3.8+)
• At least one API key from a supported provider

📄 License

MIT

👤 Maintainer

robbyczgw-cla — GitHub