Web Search Plus

Multi-provider web search with Intelligent Auto-Routing: Serper (Google), Tavily (Research), Exa (Neural).

NEW in v2.3.0: Interactive setup wizard! Run python3 scripts/setup.py for guided configuration.

NEW in v2.2.5: Automatic error fallback — if one provider fails (rate limit, timeout, etc.), automatically tries the next provider in priority order!

🚀 First Run (Setup Wizard)

New to web-search-plus? The interactive setup wizard guides you through configuration:

python3 scripts/setup.py

The wizard will:

1. Explain each provider — What they're best for, free tier limits, signup links
2. Ask which providers to enable — You can use 1, 2, or all 3
3. Collect API keys — Keys are stored locally in config.json (gitignored)
4. Configure defaults — Default provider, auto-routing, result count

What Each Provider Is Best For

Reconfigure Anytime

python3 scripts/setup.py --reset

🔑 API Keys Setup (Manual)

NEW in v2.2.0: The script auto-loads API keys from .env in the skill directory!

Quick Setup

Option A: .env file (recommended)

# /path/to/skills/web-search-plus/.env
export SERPER_API_KEY="your-key"   # https://serper.dev
export TAVILY_API_KEY="your-key"   # https://tavily.com  
export EXA_API_KEY="your-key"      # https://exa.ai

Option B: config.json (NEW in v2.2.1)

# Copy the example config
cp config.example.json config.json

Then add your keys:

{
  "serper": { "api_key": "your-serper-key" },
  "tavily": { "api_key": "your-tavily-key" },
  "exa": { "api_key": "your-exa-key" }
}

⚠️ config.json is gitignored — your keys stay safe!

Just run — keys load automatically:

python3 scripts/search.py -q "your query"
# No need for 'source .env' anymore! ✨

Priority: config.json > .env > environment variable

Get Free API Keys

⚠️ Don't Modify Core OpenClaw Config

Tavily, Serper, and Exa are NOT core OpenClaw providers.

❌ DON'T add to ~/.openclaw/openclaw.json:

"tools": { "web": { "search": { "provider": "tavily" }}}  // WRONG!

✅ DO use this skill's scripts — keys auto-load from .env

Core OpenClaw only supports brave as the built-in web search provider. This skill adds Serper, Tavily, and Exa as additional options via its own scripts.

🧠 Intelligent Auto-Routing

No need to choose a provider — just search! The skill uses multi-signal analysis to understand your query intent:

# These queries are intelligently routed with confidence scoring:
python3 scripts/search.py -q "how much does iPhone 16 cost"     # → Serper (68% MEDIUM)
python3 scripts/search.py -q "how does quantum entanglement work"  # → Tavily (86% HIGH)
python3 scripts/search.py -q "startups similar to Notion"       # → Exa (76% HIGH)
python3 scripts/search.py -q "MacBook Pro M3 specs review"      # → Serper (70% HIGH)
python3 scripts/search.py -q "explain pros and cons of React"   # → Tavily (85% HIGH)
python3 scripts/search.py -q "companies like stripe.com"        # → Exa (100% HIGH)

How It Works

The routing engine analyzes multiple signals:

🛒 Shopping Intent → Serper

📚 Research Intent → Tavily

🔍 Discovery Intent → Exa

Confidence Scoring

Every routing decision includes a confidence level:

Debug Routing Decisions

See the full analysis:

python3 scripts/search.py --explain-routing -q "how much does iPhone 16 Pro cost"

Output:

{
  "query": "how much does iPhone 16 Pro cost",
  "routing_decision": {
    "provider": "serper",
    "confidence": 0.68,
    "confidence_level": "medium",
    "reason": "moderate_confidence_match"
  },
  "scores": {"serper": 7.0, "tavily": 0.0, "exa": 0.0},
  "top_signals": [
    {"matched": "how much", "weight": 4.0},
    {"matched": "brand + product detected", "weight": 3.0}
  ],
  "query_analysis": {
    "word_count": 7,
    "is_complex": false,
    "has_url": null,
    "recency_focused": false
  }
}

🔍 When to Use This Skill vs Built-in Brave Search

Use Built-in Brave Search when:

• ✅ General web searches (news, info, questions)
• ✅ Privacy is important
• ✅ Quick lookups without specific requirements

Use web-search-plus when:

→ Serper (Google results):

• 🛍️ Product specs, prices, shopping - "Compare iPhone 16 vs Samsung S24"
• 📍 Local businesses, places - "Best pizza in Berlin"
• 🎯 "Google it" - Explicitly wants Google results
• 📰 Shopping/images/news - --type shopping/images/news
• 🏆 Knowledge Graph - Structured info (prices, ratings, etc.)

→ Tavily (AI-optimized research):

• 📚 Research questions - "How does quantum computing work?"
• 🔬 Deep dives - Complex multi-part questions
• 📄 Full page content - Not just snippets (--raw-content)
• 🎓 Academic research - Synthesized answers
• 🔒 Domain filtering - --include-domains for trusted sources

→ Exa (Neural semantic search):

• 🔗 Similar pages - "Sites like OpenAI.com" (--similar-url)
• 🏢 Company discovery - "AI companies like Anthropic"
• 📝 Research papers - --category "research paper"
• 💻 GitHub projects - --category github
• 📅 Date-specific - --start-date / --end-date

Provider Comparison

Usage Examples

Auto-Routed (Recommended)

python3 scripts/search.py -q "iPhone 16 Pro Max price"          # → Serper
python3 scripts/search.py -q "how does HTTPS encryption work"   # → Tavily
python3 scripts/search.py -q "startups similar to Notion"       # → Exa

Explicit Provider

python3 scripts/search.py -p serper -q "weather Berlin" --type weather
python3 scripts/search.py -p tavily -q "quantum computing" --depth advanced
python3 scripts/search.py -p exa --similar-url "https://stripe.com" --category company

Configuration

config.json

{
  "auto_routing": {
    "enabled": true,
    "fallback_provider": "serper",
    "confidence_threshold": 0.3,
    "disabled_providers": []
  },
  "serper": {"country": "us", "language": "en"},
  "tavily": {"depth": "advanced"},
  "exa": {"type": "neural"}
}

Output Format

{
  "provider": "serper",
  "query": "iPhone 16 price",
  "results": [{"title": "...", "url": "...", "snippet": "...", "score": 0.95}],
  "answer": "Synthesized answer...",
  "routing": {
    "auto_routed": true,
    "provider": "serper",
    "confidence": 0.78,
    "confidence_level": "high",
    "reason": "high_confidence_match",
    "top_signals": [{"matched": "price", "weight": 3.0}]
  }
}

FAQ

General

Q: How does auto-routing decide which provider to use?

Multi-signal analysis scores each provider based on: price patterns, explanation phrases, similarity keywords, URLs, product+brand combos, and query complexity. Highest score wins. Use --explain-routing to see the decision breakdown.

Q: What if it picks the wrong provider?

Override with -p serper/tavily/exa. Check --explain-routing to understand why it chose differently.

Q: What does "low confidence" mean?

Query is ambiguous (e.g., "Tesla" could be cars, stock, or company). Falls back to Serper. Results may vary.

Q: Can I disable a provider?

Yes! In config.json: "disabled_providers": ["exa"]

API Keys

Q: Which API keys do I need?

At minimum ONE key. You can use just Serper, just Tavily, or all three. Missing keys = that provider is skipped.

Q: Where do I get API keys?

• Serper: https://serper.dev (2,500 free queries, no credit card)
• Tavily: https://tavily.com (1,000 free searches/month)
• Exa: https://exa.ai (1,000 free searches/month)

Q: How do I set API keys?

Two options (both auto-load):

Option A: .env file

export SERPER_API_KEY="your-key"

Copy

Option B: config.json (v2.2.1+)

{ "serper": { "api_key": "your-key" } }

Copy

Routing Details

Q: How do I know which provider handled my search?

Check routing.provider in JSON output, or [🔍 Searched with: Provider] in chat responses.

Q: Why does it sometimes choose Serper for research questions?

If the query has brand/product signals (e.g., "how does Tesla FSD work"), shopping intent may outweigh research intent. Override with -p tavily.

Q: What's the confidence threshold?

Default: 0.3 (30%). Below this = low confidence, uses fallback. Adjustable in config.json.

Troubleshooting

Q: "No API key found" error?

1. Check .env exists in skill folder with export VAR=value format
2. Keys auto-load from skill's .env since v2.2.0
3. Or set in system environment: export SERPER_API_KEY="..."

Q: Getting empty results?

1. Check API key is valid
2. Try a different provider with -p
3. Some queries have no results (very niche topics)

Q: Rate limited?

NEW in v2.2.5: Automatic fallback! If one provider hits rate limits, the script automatically tries the next provider in priority order (serper → tavily → exa). You'll see fallback info in stderr and the response will include routing.fallback_used: true.

Provider limits: Serper 2,500 free total, Tavily 1,000/month free, Exa 1,000/month free.

For OpenClaw Users

Q: How do I use this in chat?

Just ask! OpenClaw auto-detects search intent. Or explicitly: "search with web-search-plus for..."

Q: Does it replace built-in Brave Search?

No, it's complementary. Use Brave for quick lookups, web-search-plus for research/shopping/discovery.

Q: Can I see which provider was used?

Yes! SOUL.md can include attribution: [🔍 Searched with: Serper/Tavily/Exa]