web-search-plus-plugin 2.0.0 → 2.0.4

package/.env.template

@@ -1,23 +1,28 @@
-# Serper (Google Search) — https://serper.dev
-SERPER_API_KEY=your-serper-key-here
+# web-search-plus-plugin — add at least one provider key
 
-# Tavily (Research Search) — https://tavily.com
-TAVILY_API_KEY=your-tavily-key-here
+# Serper (Google Search) — https://serper.dev
+SERPER_API_KEY=
 
-# Querit (Multilingual AI Search) — https://querit.ai
-QUERIT_API_KEY=your-querit-api-key-here
+# Tavily (Research Search) — https://tavily.com  
+TAVILY_API_KEY=
 
 # Exa (Neural/Deep Search) — https://exa.ai
-EXA_API_KEY=your-exa-key-here
+EXA_API_KEY=
 
-# Perplexity (Direct answers) — https://www.perplexity.ai/settings/api
-PERPLEXITY_API_KEY=your-perplexity-key-here
+# Querit (Multilingual AI Search) — https://querit.ai
+QUERIT_API_KEY=
 
-# Kilo Gateway (alternative Perplexity route) — https://api.kilo.ai
-KILOCODE_API_KEY=your-kilocode-key-here
+# Perplexity (Direct answers) — https://www.perplexity.ai/settings/api
+PERPLEXITY_API_KEY=
 
 # You.com — https://api.you.com
-YOU_API_KEY=your-you-api-key-here
+YOU_API_KEY=
 
 # SearXNG (self-hosted, no API key needed)
-SEARXNG_INSTANCE_URL=https://your-searxng-instance.example.com
+SEARXNG_INSTANCE_URL=
+
+# Set to 'true' to allow private IPs for SearXNG — disables SSRF protection!
+# SEARXNG_ALLOW_PRIVATE=true
+
+# Kilo.ai gateway (alternative Perplexity/other providers route) — https://api.kilo.ai  
+KILOCODE_API_KEY=

package/README.md

@@ -1,173 +1,85 @@
-# 🔍 web-search-plus-plugin
+# web-search-plus-plugin
 
-**Multi-provider web search as a native OpenClaw tool.**
+Multi-provider web search plugin for OpenClaw.
 
-An OpenClaw plugin that registers `web_search_plus` as a first-class tool with intelligent auto-routing. Install, configure an API key, go.
+## Install
 
-> **v2.0.0 is a complete rewrite.** The plugin now runs as a single pure TypeScript implementation with native `fetch()` and Node.js builtins only. No Python, no `child_process`, no setup wizard, no extra runtime dependencies.
-
-## ✨ Highlights
-
-- **Pure TypeScript** — single-file implementation, all logic in `index.ts`
-- **Zero dependencies** — Node.js builtins only, no Python, no `child_process`
-- **7 providers** — Serper, Tavily, Querit, Exa, Perplexity, You.com, SearXNG
-- **Intelligent auto-routing** — analyzes query intent, picks the best provider
-- **Automatic fallback** — if a provider fails, the next healthy one takes over
-- **Local result caching** — file-based, survives restarts, saves API credits
-- **Provider health tracking** — exponential cooldown on repeated failures
-- **SSRF protection** — SearXNG URLs validated via `dns/promises` + `net`
-
-## 🔎 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
+```bash
+openclaw plugins install clawhub:web-search-plus-plugin
+```
 
-The plugin analyzes your query and picks the best provider:
+It registers a `web_search_plus` tool that can query multiple providers and auto-route to the one that best fits the query.
 
-| 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 |
+## Why use this instead of OpenClaw's built-in `web_search`?
 
-You can always override with `provider: "tavily"` (or any other) to force a specific provider.
+OpenClaw's built-in `web_search` uses Brave Search.
 
-## 📦 Installation
+You might want this plugin when:
+- Brave returns thin or no results for a query, but Serper/Google or You.com still finds relevant pages.
+- You want research-oriented output; Tavily can return structured results that are easier to summarize.
+- You want semantic discovery; Exa can find related content that plain keyword search may miss.
 
-### Option 1: npm
+Supported providers:
+- Serper (Google)
+- Tavily
+- Exa
+- Querit
+- Perplexity
+- You.com
+- SearXNG
 
-```bash
-npm install web-search-plus-plugin
-```
+## What you need
 
-### Option 2: Clone
+You do not need every provider.
 
-```bash
-git clone https://github.com/robbyczgw-cla/web-search-plus-plugin.git
-```
+You need at least one configured provider:
+- an API key for any hosted provider, or
+- a SearXNG instance URL
 
-### Configure API Keys
+## Quick setup
 
 ```bash
 cp .env.template .env
-# Edit .env and add your API keys (at least one required)
+# add at least one API key or SearXNG URL
 ```
 
-### Add to OpenClaw Config
-
-```json
-{
-  "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](https://console.serper.dev) |
-| `TAVILY_API_KEY` | Tavily | [tavily.com](https://tavily.com) |
-| `QUERIT_API_KEY` | Querit | [querit.ai](https://querit.ai) |
-| `EXA_API_KEY` | Exa | [exa.ai](https://exa.ai) |
-| `PERPLEXITY_API_KEY` | Perplexity | [perplexity.ai](https://docs.perplexity.ai) |
-| `KILOCODE_API_KEY` | Perplexity via Kilo | [kilocode.ai](https://kilocode.ai) |
-| `YOU_API_KEY` | You.com | [you.com/api](https://you.com/api) |
-| `SEARXNG_INSTANCE_URL` | SearXNG (self-hosted) | [docs.searxng.org](https://docs.searxng.org) |
-
-You can also configure these values through OpenClaw plugin config. Local `.env` values remain convenient for development.
-
-## 🤖 Enable for an Agent
-
-Allow the tool in your agent config:
-
-```json
-{
-  "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, max: 10) |
-| `depth` | string | ❌ | Exa depth: `normal`, `deep`, or `deep-reasoning` |
-| `time_range` | string | ❌ | Recency filter where supported: `day`, `week`, `month`, `year` |
-| `include_domains` | string[] | ❌ | Restrict results to these domains where supported (Tavily, Exa, Querit) |
-| `exclude_domains` | string[] | ❌ | Exclude these domains where supported (Tavily, Exa, Querit) |
-
-## ❓ 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. The plugin is the recommended approach.
-
-### How does auto-routing work?
-The router scores each configured provider based on query signals. Shopping keywords boost Serper, explanation queries boost Tavily, multilingual/real-time queries favor Querit, semantic/discovery queries boost Exa, and direct questions boost Perplexity. Highest score wins, with automatic fallback on failure.
+Then load the plugin in OpenClaw and restart the gateway.
 
-### 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.
+## Provider overview
 
-### 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`.
+| Provider | Best for | Free tier | Rate limit (free) |
+| --- | --- | --- | --- |
+| Serper | Google-style general web, news, shopping, local results | Yes | 2,500/mo |
+| Tavily | Research-style results and summaries | Yes | 1,000/mo |
+| Exa | Semantic / neural discovery | Yes | 1,000/mo |
+| Querit | Multilingual and regional search | Yes | Varies |
+| Perplexity | Answer-style web results with citations | Limited / depends on plan | API credits required |
+| You.com | General web + answer-oriented results | Limited | 60 req/hr |
+| SearXNG | Self-hosted metasearch | Yes, self-hosted | Self-hosted, unlimited |
 
-### 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 instance URLs before querying and includes SSRF protection using Node.js DNS/IP checks for security.
+## Auto-routing logic
 
-### 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.
+The plugin scores each query against the providers you have configured and picks the best match for that query type. If the first choice is unavailable or fails, it falls back to another configured provider instead of failing immediately.
 
-## 📋 Requirements
+## Notes
 
-- **OpenClaw gateway** (any recent version)
-- At least **one API key** from a supported provider, or a **SearXNG instance URL**
+- Auto-routing chooses among configured providers only.
+- If a provider is missing credentials, it is skipped.
+- SearXNG includes SSRF protection by default.
+- `SEARXNG_ALLOW_PRIVATE=true` disables that protection and should only be used on trusted private networks.
 
-## 📄 License
+## Environment variables
 
-MIT
+- `SERPER_API_KEY`
+- `TAVILY_API_KEY`
+- `EXA_API_KEY`
+- `QUERIT_API_KEY`
+- `PERPLEXITY_API_KEY`
+- `KILOCODE_API_KEY`
+- `YOU_API_KEY`
+- `SEARXNG_INSTANCE_URL`
+- `SEARXNG_ALLOW_PRIVATE`
 
-## 👤 Maintainer
+## Repository
 
-**robbyczgw-cla** — [GitHub](https://github.com/robbyczgw-cla)
+GitHub: <https://github.com/robbyczgw-cla/web-search-plus-plugin>

package/index.ts

@@ -286,7 +286,7 @@ function loadEnvFile(envPath: string): Record<string, string> {
 }
 
 function getRuntimeEnv(pluginConfig: Record<string, string>): Record<string, string> {
-  const envFiles = [path.join(PLUGIN_DIR, ".env"), path.join(PLUGIN_DIR, "..", "web-search-plus", ".env")];
+  const envFiles = [path.join(PLUGIN_DIR, ".env")];
   const fileEnv = Object.assign({}, ...envFiles.map(loadEnvFile));
   const mapped: Record<string, string> = {};
   const configKeyMap: Record<string, string> = {
@@ -314,8 +314,8 @@ function getApiKey(provider: ProviderName, env: Record<string, string>): string
     querit: env.QUERIT_API_KEY,
     exa: env.EXA_API_KEY,
     perplexity: env.KILOCODE_API_KEY || env.PERPLEXITY_API_KEY,
-    you: env.YOU_API_KEY,
-    searxng: env.SEARXNG_INSTANCE_URL,
+    you: env.YOU_API_KEY || env.YOUCOM_API_KEY,
+    searxng: env.SEARXNG_INSTANCE_URL || env.SEARXNG_URL,
   };
   return keyMap[provider];
 }
@@ -387,7 +387,9 @@ async function validateSearxngUrl(input: string, env: Record<string, string>): P
   const blockedHosts = new Set(["169.254.169.254", "metadata.google.internal", "metadata.internal"]);
   if (blockedHosts.has(u.hostname)) throw new ProviderConfigError("SearXNG URL blocked: metadata endpoint");
 
-  const allowPrivate = String(env.SEARXNG_ALLOW_PRIVATE || "").trim() === "1";
+  // WARNING: Setting SEARXNG_ALLOW_PRIVATE=true disables SSRF protection for SearXNG.
+  // Only enable on fully trusted private networks.
+  const allowPrivate = ["1", "true", "yes"].includes(String(env.SEARXNG_ALLOW_PRIVATE || "").trim().toLowerCase());
   if (!allowPrivate) {
     const records = await dns.lookup(u.hostname, { all: true, verbatim: true }).catch(() => [] as dns.LookupAddress[]);
     if (!records.length && net.isIP(u.hostname)) records.push({ address: u.hostname, family: net.isIP(u.hostname) as 4 | 6 });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "web-search-plus-plugin",
   "name": "Web Search Plus",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Multi-provider web search (Serper/Google, Tavily, Querit/Multilingual AI Search, Exa/Neural+Deep, Perplexity, You.com, SearXNG) with intelligent auto-routing",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,11 +1,27 @@
 {
   "name": "web-search-plus-plugin",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "OpenClaw plugin: multi-provider web search (Serper/Google, Tavily, Querit/Multilingual AI Search, Exa/Neural+Deep, Perplexity, You.com, SearXNG) with intelligent auto-routing",
   "type": "module",
   "main": "index.ts",
   "openclaw": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.22"
+    },
+    "env": {
+      "SERPER_API_KEY": "optional \u2014 Serper/Google search API key",
+      "TAVILY_API_KEY": "optional \u2014 Tavily research search API key",
+      "EXA_API_KEY": "optional \u2014 Exa neural search API key",
+      "QUERIT_API_KEY": "optional \u2014 Querit multilingual search API key",
+      "PERPLEXITY_API_KEY": "optional \u2014 Perplexity AI search API key",
+      "KILOCODE_API_KEY": "optional \u2014 Kilo.ai gateway API key",
+      "YOU_API_KEY": "optional \u2014 You.com search API key",
+      "SEARXNG_INSTANCE_URL": "optional \u2014 SearXNG self-hosted instance URL",
+      "SEARXNG_ALLOW_PRIVATE": "optional \u2014 set true to allow private IPs for SearXNG (disables SSRF protection)"
+    }
   },
   "files": [
     "index.ts",
@@ -14,7 +30,21 @@
     "README.md",
     "LICENSE"
   ],
-  "keywords": ["openclaw", "plugin", "search", "serper", "tavily", "querit", "exa", "exa-deep", "perplexity", "you", "searxng", "web-search", "auto-routing"],
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "search",
+    "serper",
+    "tavily",
+    "querit",
+    "exa",
+    "exa-deep",
+    "perplexity",
+    "you",
+    "searxng",
+    "web-search",
+    "auto-routing"
+  ],
   "peerDependencies": {
     "openclaw": ">=2026.3.22"
   },