{"id":"0d20863c-19ab-4318-9ad2-302034484535","entityType":"agent","slug":"clawhub-robbyczgw-cla-web-search-plus","name":"Web Search Plus","canonicalUrl":"https://www.xpersona.co/agent/clawhub-robbyczgw-cla-web-search-plus","canonicalPath":"/agent/clawhub-robbyczgw-cla-web-search-plus","generatedAt":"2026-10-09T19:00:18.442Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neura...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 10.3K downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn73gpe8xz2630jrknkb3ya96h7zb84h:web-search-plus","sourceUrl":"https://clawhub.ai/robbyczgw-cla/web-search-plus","homepage":"https://clawhub.ai/robbyczgw-cla/web-search-plus","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/robbyczgw-cla/web-search-plus","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":74,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Web Search Plus technical dossier on Xpersona with source links, trust signals, and execution metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No protocol or capability metadata is available."},"protocols":[],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":0,"capabilityMatrix":{"rows":[],"flattenedTokens":""}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":10261,"packageName":null,"latestVersion":"2.8.5","tractionLabel":"10.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-02-28T17:01:02.800Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-28T17:01:02.800Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-01T17:01:02.800Z","lastVerifiedAt":null,"highlights":[{"version":"2.8.5","createdAt":"2026-02-20T15:58:22.076Z","changelog":"web-search-plus 2.8.5 - Updated package version to 2.8.5. - Minor updates in CHANGELOG.md and scripts/search.py. - No changes to SKILL.md; user-facing documentation is unchanged.","fileCount":11,"zipByteSize":58666},{"version":"2.8.4","createdAt":"2026-02-20T13:56:48.196Z","changelog":"Security: SSRF protection added to setup.py SearXNG connection test","fileCount":11,"zipByteSize":58352},{"version":"2.8.3","createdAt":"2026-02-20T13:52:13.265Z","changelog":"Fix: Perplexity provider returned 0 results โ€” answer now mapped as primary result","fileCount":null,"zipByteSize":null},{"version":"2.8.2","createdAt":"2026-02-20T13:28:17.364Z","changelog":"Fix SKILL.md metadata inconsistencies: add KILOCODE_API_KEY to env declarations, update all provider references to include Perplexity","fileCount":null,"zipByteSize":null},{"version":"2.8.1","createdAt":"2026-02-20T13:25:21.665Z","changelog":"Detailed changelog + docs for Perplexity provider and routing rebalance","fileCount":null,"zipByteSize":null},{"version":"2.8.0","createdAt":"2026-02-20T13:23:07.723Z","changelog":"Add Perplexity provider via Kilo Gateway + rebalance routing (Tavily for research, Exa for discovery, Perplexity for direct answers)","fileCount":null,"zipByteSize":null},{"version":"2.7.2","createdAt":"2026-02-15T07:32:28.504Z","changelog":"Security: Implement actual SSRF protection - resolve hostnames and block private/internal IPs (loopback, RFC1918, link-local, cloud metadata). Add SEARXNG_ALLOW_PRIVATE=1 escape hatch for intentional self-hosted setups.","fileCount":null,"zipByteSize":null},{"version":"2.7.1","createdAt":"2026-02-15T07:24:08.041Z","changelog":"Security fix: Add SSRF protection for SearXNG instance URL validation. Enforce http/https scheme, prevent prompt injection from redirecting to internal endpoints.","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn73gpe8xz2630jrknkb3ya96h7zb84h:web-search-plus","setupComplexity":"low","setupSteps":["Install using `clawhub skill install kn73gpe8xz2630jrknkb3ya96h7zb84h:web-search-plus` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/robbyczgw-cla/web-search-plus before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":[]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T19:00:18.438Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-web-search-plus/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: Web Search Plus\n\nOwner: robbyczgw-cla\n\nSummary: Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neura...\n\nTags: latest:2.8.5\n\nVersion history:\n\nv2.8.5 | 2026-02-20T15:58:22.076Z | auto\n\nweb-search-plus 2.8.5\n\n- Updated package version to 2.8.5.\n- Minor updates in CHANGELOG.md and scripts/search.py.\n- No changes to SKILL.md; user-facing documentation is unchanged.\n\nv2.8.4 | 2026-02-20T13:56:48.196Z | user\n\nSecurity: SSRF protection added to setup.py SearXNG connection test\n\nv2.8.3 | 2026-02-20T13:52:13.265Z | user\n\nFix: Perplexity provider returned 0 results โ€” answer now mapped as primary result\n\nv2.8.2 | 2026-02-20T13:28:17.364Z | user\n\nFix SKILL.md metadata inconsistencies: add KILOCODE_API_KEY to env declarations, update all provider references to include Perplexity\n\nv2.8.1 | 2026-02-20T13:25:21.665Z | user\n\nDetailed changelog + docs for Perplexity provider and routing rebalance\n\nv2.8.0 | 2026-02-20T13:23:07.723Z | user\n\nAdd Perplexity provider via Kilo Gateway + rebalance routing (Tavily for research, Exa for discovery, Perplexity for direct answers)\n\nv2.7.2 | 2026-02-15T07:32:28.504Z | user\n\nSecurity: Implement actual SSRF protection - resolve hostnames and block private/internal IPs (loopback, RFC1918, link-local, cloud metadata). Add SEARXNG_ALLOW_PRIVATE=1 escape hatch for intentional self-hosted setups.\n\nv2.7.1 | 2026-02-15T07:24:08.041Z | user\n\nSecurity fix: Add SSRF protection for SearXNG instance URL validation. Enforce http/https scheme, prevent prompt injection from redirecting to internal endpoints.\n\nv2.7.0 | 2026-02-14T14:52:12.877Z | auto\n\n**Version 2.7.0 (web-search-plus):**\n\n- Documentation fully updated across README, FAQ, SKILL, and TROUBLESHOOTING for clarity and completeness.\n- Improved instructions and API key setup guides.\n- Enhanced configuration examples and usage explanations.\n- No changes to provider support or algorithm logic.\n- Version updated in metadata and docs.\n\nv2.6.5 | 2026-02-11T09:02:15.723Z | user\n\nFix: SKILL.md metadata env vars now correctly marked optional (was array format interpreted as required by registry)\n\nv2.6.4 | 2026-02-11T08:46:01.334Z | user\n\ncache fix\n\nv2.6.3 | 2026-02-11T08:36:14.538Z | user\n\nAdded file-based result caching (1h TTL), --no-cache, --clear-cache, --cache-stats flags.\n\nv2.6.2 | 2026-02-05T09:30:14.248Z | user\n\nImprove SKILL.md user-friendliness for ClawHub (add FAQ section, clearer intro)\n\nv2.6.1 | 2026-02-04T23:03:31.408Z | auto\n\n- Bumped version to 2.6.1.\n- Updated documentation files for accuracy and clarification.\n- No major code or feature changes in this release.\n\nv2.6.0 | 2026-02-04T12:19:43.253Z | auto\n\n- Added FAQ.md and TROUBLESHOOTING.md for improved user support and documentation.\n- SKILL.md fully rewritten for clarity, concise setup, and easier navigation.\n- Expanded and reorganized usage instructions, configuration details, and provider comparison tables.\n- Now highlights additional documentation and troubleshooting resources for new and existing users.\n\nv2.5.2 | 2026-02-03T17:17:49.757Z | user\n\nAdd ClawHub runtime requirements metadata (SKILL.md frontmatter)\n\nv2.5.1 | 2026-02-03T16:58:10.723Z | user\n\nAdd runtime requirements metadata for ClawHub discovery\n\nv2.5.0 | 2026-02-03T15:32:22.706Z | user\n\nNEW: SearXNG provider - Privacy-first meta-search! ๐Ÿ”’ 70+ upstream engines, $0 API cost, self-hosted. Perfect for privacy-conscious users and multi-source aggregation. Now with 5 intelligent providers: Serper (Google), Tavily (Research), Exa (Neural), You.com (RAG), SearXNG (Privacy). Comprehensive FAQ added with 15 questions. Auto-routing for privacy/multi-source queries. Tested all provider combinations (0-5). Designed for self-hosters - bring your own instance!\n\nv2.4.4 | 2026-02-03T15:11:26.320Z | user\n\nDocumentation fix: Corrected provider count from 'all 3' to 'all 4' in setup wizard description (we have 4 providers: Serper, Tavily, Exa, You.com).\n\nv2.4.3 | 2026-02-03T14:44:05.657Z | user\n\nDocumentation update: Added 'NEW in v2.4.2' badge for You.com in SKILL.md to properly highlight the new provider on ClawHub.\n\nv2.4.2 | 2026-02-03T14:40:35.558Z | user\n\nCritical fix: Corrected You.com API hostname (ydc-index.io) and header name (X-API-KEY uppercase). You.com provider now works correctly - fully tested and verified with perfect results!\n\nv2.4.1 | 2026-02-03T14:36:58.532Z | user\n\nBugfix: Fixed URL encoding for You.com queries - spaces and special characters now work correctly. Queries like 'OpenClaw AI framework' no longer cause 403 errors.\n\nv2.4.0 | 2026-02-03T14:32:29.725Z | user\n\nAdd You.com as 4th search provider. Features: Auto-routing for RAG/real-time queries, LLM-ready snippets, unified web/news results, live crawl option for full page content. Perfect for AI-assisted research and real-time information needs.\n\nv2.3.0 | 2026-01-31T23:02:52.885Z | auto\n\n**Highlights:** Adds interactive setup wizard for first-time users.\n\n- Introduced an interactive setup script (`scripts/setup.py`) for guided provider and API key configuration.\n- Updated documentation to highlight the setup wizard and improved onboarding experience.\n- Existing manual configuration via `.env` or `config.json` still supported.\n- Minor metadata and documentation improvements.\n\nv2.2.6 | 2026-01-31T22:55:13.239Z | auto\n\n- Updated example city in usage and intent sections from \"Vienna\" to \"Berlin\" for consistency.\n- No code changes or feature updates; documentation adjustments only.\n\nv2.2.5 | 2026-01-31T08:55:23.621Z | user\n\nAuto error fallback between providers\n\nv2.2.4 | 2026-01-31T08:54:05.168Z | user\n\nAutomatic error fallback - when one provider fails (rate limit, timeout), automatically tries next provider in priority order (serper โ†’ tavily โ†’ exa)\n\nv2.1.9 | 2026-01-29T18:40:00.157Z | user\n\nMigrate from Clawdbot to Moltbot\n\nv2.2.2 | 2026-01-28T20:51:59.487Z | user\n\nGitignore config.json to prevent API key leaks. Added config.example.json as safe template.\n\nv2.2.1 | 2026-01-28T20:50:55.570Z | user\n\nSupport API keys in config.json - Priority: config.json > .env > environment\n\nv2.2.0 | 2026-01-28T20:46:15.447Z | user\n\nAuto-load .env file - no more 'source .env' needed! Keys load automatically from skill directory.\n\nv2.1.8 | 2026-01-28T13:47:37.649Z | user\n\nfix: correct free tier limits (Serper 2,500, Tavily 1,000), update version badges\n\nv2.1.7 | 2026-01-28T13:46:11.702Z | user\n\nfix: remove incorrect perplexity reference\n\nv2.1.6 | 2026-01-28T12:12:55.279Z | user\n\nfix: add missing confidence_level, User-Agent header, English defaults\n\nv2.1.5 | 2026-01-27T07:58:42.652Z | user\n\ndocs: Add warning about NOT using Tavily/Serper/Exa in core clawdbot.json\n\nv2.1.3 | 2026-01-25T11:17:51.767Z | user\n\nv2.1.3: Expanded FAQ (API keys, troubleshooting, Clawdbot), more tags\n\nv2.1.2 | 2026-01-25T06:24:49.025Z | user\n\nSECURITY: Removed hardcoded API keys from test script\n\nv2.1.1 | 2026-01-25T06:22:16.903Z | user\n\nFix: .env requires export prefix for Python to read environment variables\n\nv2.0.0 | 2026-01-23T20:54:07.068Z | auto\n\nWeb Search Plus 2.0.0 โ€“ Smart Auto-Routing (major upgrade!)\n\n- Added automatic query analysis to select the best search provider (Serper, Tavily, or Exa) with no user intervention required.\n- Included explainable routing: use `--explain-routing` to see why a provider was chosen.\n- Updated usage guides and documentation to reflect auto-routing as the new default and recommended workflow.\n- Introduced tests for auto-routing logic (see `test-auto-routing.sh`).\n- Minor config and script updates for improved clarity and maintainability.\n\nv1.0.8 | 2026-01-20T22:35:48.740Z | user\n\nUpdate author email to robbyczgw@gmail.com\n\nv1.0.7 | 2026-01-20T22:35:05.769Z | user\n\nUpdate author email\n\nv1.0.6 | 2026-01-20T22:25:57.841Z | user\n\nAdd SKILL.md frontmatter for ClawdHub summary display\n\nv1.0.5 | 2026-01-20T22:22:45.872Z | user\n\nAdd decision guide to README.md, update badges to v1.0.4 and add GitHub badge\n\nv1.0.4 | 2026-01-20T22:19:24.367Z | user\n\nAdd clear decision guide: when to use built-in Brave search vs web-search-plus providers (Serper/Tavily/Exa)\n\nv1.0.3 | 2026-01-20T22:14:12.343Z | user\n\nFix config.json example defaults to en/us for consistency\n\nv1.0.2 | 2026-01-20T22:11:51.811Z | user\n\nAdd package.json with full description for ClawdHub display\n\nv1.0.1 | 2026-01-20T22:11:12.153Z | user\n\nFix defaults to English (en/us) for international use, add package.json for proper ClawdHub metadata\n\nv1.1.0 | 2026-01-20T22:10:17.360Z | auto\n\nWeb Search Plus v1.1.0\n\n- Major documentation overhaul: SKILL.md rewritten to include agent-focused decision trees, detailed feature matrix, usage patterns, cost optimization, and advanced workflows.\n- Added `config.json` for new configuration capabilities.\n- Updated README.md and scripts/search.py for improved clarity and usability.\n- Enhanced provider comparison and multi-provider workflow instructions.\n\nv1.0.0 | 2026-01-20T22:05:37.164Z | auto\n\n- Initial release of Web Search Plus: a multi-provider web search utility supporting Serper (Google Search API), Tavily (Research Search), and Exa (Neural/Semantic Search).\n- Added guidance on choosing the best provider for various query types.\n- Unified JSON output format across all providers for streamlined results handling.\n- Default settings for provider options (such as language, result count, and type) included.\n- Environment variable setup documented for easy API integration.\n\nArchive index:\n\nArchive v2.8.5: 11 files, 58666 bytes\n\nFiles: CHANGELOG.md (18449b), config.example.json (4972b), FAQ.md (9360b), package.json (1801b), README.md (23073b), scripts/search.py (89216b), scripts/setup.py (18486b), SKILL.md (9693b), test-auto-routing.sh (555b), TROUBLESHOOTING.md (6664b), _meta.json (134b)\n\nFile v2.8.5:SKILL.md\n\n---\nname: web-search-plus\nversion: 2.8.1\ndescription: Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neural), Perplexity (AI Answers), You.com (RAG/Real-time), and SearXNG (Privacy/Self-hosted) with confidence scoring.\ntags: [search, web-search, serper, tavily, exa, perplexity, you, searxng, google, research, semantic-search, auto-routing, multi-provider, shopping, rag, free-tier, privacy, self-hosted, kilo]\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"bash\"],\"env\":{\"SERPER_API_KEY\":\"optional\",\"TAVILY_API_KEY\":\"optional\",\"EXA_API_KEY\":\"optional\",\"YOU_API_KEY\":\"optional\",\"SEARXNG_INSTANCE_URL\":\"optional\",\"KILOCODE_API_KEY\":\"optional โ€” required for Perplexity provider (via Kilo Gateway)\"},\"note\":\"Only ONE provider key needed. All are optional.\"}}}\n---\n\n# Web Search Plus\n\n**Stop choosing search providers. Let the skill do it for you.**\n\nThis skill connects you to 6 search providers (Serper, Tavily, Exa, Perplexity, You.com, SearXNG) and automatically picks the best one for each query. Shopping question? โ†’ Google results. Research question? โ†’ Deep research engine. Need a direct answer? โ†’ AI-synthesized with citations. Want privacy? โ†’ Self-hosted option.\n\n---\n\n## โœจ What Makes This Different?\n\n- **Just search** โ€” No need to think about which provider to use\n- **Smart routing** โ€” Analyzes your query and picks the best provider automatically\n- **6 providers, 1 interface** โ€” Google results, research engines, neural search, AI answers with citations, RAG-optimized, and privacy-first all in one\n- **Works with just 1 key** โ€” Start with any single provider, add more later\n- **Free options available** โ€” SearXNG is completely free (self-hosted)\n\n---\n\n## ๐Ÿš€ Quick Start\n\n```bash\n# Interactive setup (recommended for first run)\npython3 scripts/setup.py\n\n# Or manual: copy config and add your keys\ncp config.example.json config.json\n```\n\nThe wizard explains each provider, collects API keys, and configures defaults.\n\n---\n\n## ๐Ÿ”‘ API Keys\n\nYou only need **ONE** key to get started. Add more providers later for better coverage.\n\n| Provider | Free Tier | Best For | Sign Up |\n|----------|-----------|----------|---------|\n| **Serper** | 2,500/mo | Shopping, prices, local, news | [serper.dev](https://serper.dev) |\n| **Tavily** | 1,000/mo | Research, explanations, academic | [tavily.com](https://tavily.com) |\n| **Exa** | 1,000/mo | \"Similar to X\", startups, papers | [exa.ai](https://exa.ai) |\n| **Perplexity** | Via Kilo | Direct answers with citations | [kilo.ai](https://kilo.ai) |\n| **You.com** | Limited | Real-time info, AI/RAG context | [api.you.com](https://api.you.com) |\n| **SearXNG** | **FREE** โœ… | Privacy, multi-source, $0 cost | Self-hosted |\n\n**Setting your keys:**\n\n```bash\n# Option A: .env file (recommended)\nexport SERPER_API_KEY=\"your-key\"\nexport TAVILY_API_KEY=\"your-key\"\n\n# Option B: config.json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## ๐ŸŽฏ When to Use Which Provider\n\n| I want to... | Provider | Example Query |\n|--------------|----------|---------------|\n| Find product prices | **Serper** | \"iPhone 16 Pro Max price\" |\n| Find restaurants/stores nearby | **Serper** | \"best pizza near me\" |\n| Understand how something works | **Tavily** | \"how does HTTPS encryption work\" |\n| Do deep research | **Tavily** | \"climate change research 2024\" |\n| Find companies like X | **Exa** | \"startups similar to Notion\" |\n| Find research papers | **Exa** | \"transformer architecture papers\" |\n| Get a direct answer with sources | **Perplexity** | \"events in Berlin this weekend\" |\n| Know the current status of something | **Perplexity** | \"what is the status of Ethereum upgrades\" |\n| Get real-time info | **You.com** | \"latest AI regulation news\" |\n| Search without being tracked | **SearXNG** | anything, privately |\n\n**Pro tip:** Just search normally! Auto-routing handles most queries correctly. Override with `-p provider` when needed.\n\n---\n\n## ๐Ÿง  How Auto-Routing Works\n\nThe skill looks at your query and picks the best provider:\n\n```bash\n\"iPhone 16 price\" โ†’ Serper (shopping keywords)\n\"how does quantum computing work\" โ†’ Tavily (research question)\n\"companies like stripe.com\" โ†’ Exa (URL detected, similarity)\n\"events in Graz this weekend\" โ†’ Perplexity (local + direct answer)\n\"latest news on AI\" โ†’ You.com (real-time intent)\n\"search privately\" โ†’ SearXNG (privacy keywords)\n```\n\n**What if it picks wrong?** Override it: `python3 scripts/search.py -p tavily -q \"your query\"`\n\n**Debug routing:** `python3 scripts/search.py --explain-routing -q \"your query\"`\n\n---\n\n## ๐Ÿ“– Usage Examples\n\n### Let Auto-Routing Choose (Recommended)\n\n```bash\npython3 scripts/search.py -q \"Tesla Model 3 price\"\npython3 scripts/search.py -q \"explain machine learning\"\npython3 scripts/search.py -q \"startups like Figma\"\n```\n\n### Force a Specific Provider\n\n```bash\npython3 scripts/search.py -p serper -q \"weather Berlin\"\npython3 scripts/search.py -p tavily -q \"quantum computing\" --depth advanced\npython3 scripts/search.py -p exa --similar-url \"https://stripe.com\" --category company\npython3 scripts/search.py -p you -q \"breaking tech news\" --include-news\npython3 scripts/search.py -p searxng -q \"linux distros\" --engines \"google,bing\"\n```\n\n---\n\n## โš™ Configuration\n\n```json\n{\n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"confidence_threshold\": 0.3,\n \"disabled_providers\": []\n },\n \"serper\": {\"country\": \"us\", \"language\": \"en\"},\n \"tavily\": {\"depth\": \"advanced\"},\n \"exa\": {\"type\": \"neural\"},\n \"you\": {\"country\": \"US\", \"include_news\": true},\n \"searxng\": {\"instance_url\": \"https://your-instance.example.com\"}\n}\n```\n\n---\n\n## ๐Ÿ“Š Provider Comparison\n\n| Feature | Serper | Tavily | Exa | Perplexity | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:----------:|:-------:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšก | โšกโšกโšก | โšกโšก |\n| Direct Answers | โœ— | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— |\n| Citations | โœ— | โœ— | โœ— | โœ“ | โœ— | โœ— |\n| Factual Accuracy | โญโญโญ | โญโญโญ | โญโญ | โญโญโญ | โญโญโญ | โญโญโญ |\n| Semantic Understanding | โญ | โญโญ | โญโญโญ | โญโญโญ | โญโญ | โญ |\n| Full Page Content | โœ— | โœ“ | โœ“ | โœ“ | โœ“ | โœ— |\n| Shopping/Local | โœ“ | โœ— | โœ— | โœ— | โœ— | โœ“ |\n| Find Similar Pages | โœ— | โœ— | โœ“ | โœ— | โœ— | โœ— |\n| RAG-Optimized | โœ— | โœ“ | โœ— | โœ— | โœ“โœ“ | โœ— |\n| Privacy-First | โœ— | โœ— | โœ— | โœ— | โœ— | โœ“โœ“ |\n| API Cost | $$ | $$ | $$ | Via Kilo | $ | **FREE** |\n\n---\n\n## โ“ Common Questions\n\n### Do I need API keys for all providers?\n**No.** You only need keys for providers you want to use. Start with one (Serper recommended), add more later.\n\n### Which provider should I start with?\n**Serper** โ€” fastest, cheapest, largest free tier (2,500 queries/month), and handles most queries well.\n\n### What if I run out of free queries?\nThe skill automatically falls back to your other configured providers. Or switch to SearXNG (unlimited, self-hosted).\n\n### How much does this cost?\n- **Free tiers:** 2,500 (Serper) + 1,000 (Tavily) + 1,000 (Exa) = 4,500+ free searches/month\n- **SearXNG:** Completely free (just ~$5/mo if you self-host on a VPS)\n- **Paid plans:** Start around $10-50/month depending on provider\n\n### Is SearXNG really private?\n**Yes, if self-hosted.** You control the server, no tracking, no profiling. Public instances depend on the operator's policy.\n\n### How do I set up SearXNG?\n```bash\n# Docker (5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n```\nThen enable JSON API in `settings.yml`. See [docs.searxng.org](https://docs.searxng.org/admin/installation.html).\n\n### Why did it route my query to the \"wrong\" provider?\nSometimes queries are ambiguous. Use `--explain-routing` to see why, then override with `-p provider` if needed.\n\n---\n\n## ๐Ÿ”„ Automatic Fallback\n\nIf one provider fails (rate limit, timeout, error), the skill automatically tries the next provider. You'll see `routing.fallback_used: true` in the response when this happens.\n\n---\n\n## ๐Ÿ“ค Output Format\n\n```json\n{\n \"provider\": \"serper\",\n \"query\": \"iPhone 16 price\",\n \"results\": [{\"title\": \"...\", \"url\": \"...\", \"snippet\": \"...\", \"score\": 0.95}],\n \"routing\": {\n \"auto_routed\": true,\n \"provider\": \"serper\",\n \"confidence\": 0.78,\n \"confidence_level\": \"high\"\n }\n}\n```\n\n---\n\n## โš  Important Note\n\n**Tavily, Serper, and Exa are NOT core OpenClaw providers.**\n\nโŒ Don't modify `~/.openclaw/openclaw.json` for these \nโœ… Use this skill's scripts โ€” keys auto-load from `.env`\n\n---\n\n## ๐Ÿ”’ Security\n\n**SearXNG SSRF Protection:** The SearXNG instance URL is validated with defense-in-depth:\n- Enforces `http`/`https` schemes only\n- Blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal)\n- Resolves hostnames and blocks private/internal IPs (loopback, RFC1918, link-local, reserved)\n- Operators who intentionally self-host on private networks can set `SEARXNG_ALLOW_PRIVATE=1`\n\n## ๐Ÿ“š More Documentation\n\n- **[FAQ.md](FAQ.md)** โ€” Detailed answers to more questions\n- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** โ€” Fix common errors\n- **[README.md](README.md)** โ€” Full technical reference\n\n---\n\n## ๐Ÿ”— Quick Links\n\n- [Serper](https://serper.dev) โ€” Google Search API\n- [Tavily](https://tavily.com) โ€” AI Research Search\n- [Exa](https://exa.ai) โ€” Neural Search\n- [Perplexity](https://www.perplexity.ai) โ€” AI-Synthesized Answers (via [Kilo Gateway](https://kilo.ai))\n- [You.com](https://api.you.com) โ€” RAG/Real-time Search\n- [SearXNG](https://docs.searxng.org) โ€” Privacy-First Meta-Search\n\nFile v2.8.5:README.md\n\n# Web Search Plus\n\n> Unified multi-provider web search with **Intelligent Auto-Routing** โ€” uses multi-signal analysis to automatically select between **Serper**, **Tavily**, **Exa**, **You.com**, and **SearXNG** with confidence scoring.\n\n[![ClawHub](https://img.shields.io/badge/ClawHub-web--search--plus-blue)](https://clawhub.ai)\n[![Version](https://img.shields.io/badge/version-2.7.0-green)](https://clawhub.ai)\n[![GitHub](https://img.shields.io/badge/GitHub-web--search--plus-blue)](https://github.com/robbyczgw-cla/web-search-plus)\n\n---\n\n## ๐Ÿง  Features (v2.7.0)\n\n**Intelligent Multi-Signal Routing** โ€” The skill uses sophisticated query analysis:\n\n- **Intent Classification**: Shopping vs Research vs Discovery vs RAG/Real-time vs Privacy\n- **Linguistic Patterns**: \"how much\" (price) vs \"how does\" (research) vs \"privately\" (privacy)\n- **Entity Detection**: Product+brand combos, URLs, domains\n- **Complexity Analysis**: Long queries favor research providers\n- **Confidence Scoring**: Know how reliable the routing decision is\n\n```bash\npython3 scripts/search.py -q \"how much does iPhone 16 cost\" # โ†’ Serper (68% confidence)\npython3 scripts/search.py -q \"how does quantum entanglement work\" # โ†’ Tavily (86% HIGH)\npython3 scripts/search.py -q \"startups similar to Notion\" # โ†’ Exa (76% HIGH)\npython3 scripts/search.py -q \"companies like stripe.com\" # โ†’ Exa (100% HIGH - URL detected)\npython3 scripts/search.py -q \"summarize key points on AI\" # โ†’ You.com (68% MEDIUM - RAG intent)\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG (74% HIGH - privacy intent)\n```\n\n---\n\n## ๐Ÿ” When to Use Which Provider\n\n### Built-in Brave Search (OpenClaw default)\n- โœ… General web searches\n- โœ… Privacy-focused\n- โœ… Quick lookups\n- โœ… Default fallback\n\n### Serper (Google Results)\n- ๐Ÿ› **Product specs, prices, shopping**\n- ๐Ÿ“ **Local businesses, places**\n- ๐ŸŽฏ **\"Google it\" - explicit Google results**\n- ๐Ÿ“ฐ **Shopping/images needed**\n- ๐Ÿ† **Knowledge Graph data**\n\n### Tavily (AI-Optimized Research)\n- ๐Ÿ“š **Research questions, deep dives**\n- ๐Ÿ”ฌ **Complex multi-part queries**\n- ๐Ÿ“„ **Need full page content** (not just snippets)\n- ๐ŸŽ“ **Academic/technical research**\n- ๐Ÿ”’ **Domain filtering** (trusted sources)\n\n### Exa (Neural Semantic Search)\n- ๐Ÿ”— **Find similar pages**\n- ๐Ÿข **Company/startup discovery**\n- ๐Ÿ“ **Research papers**\n- ๐Ÿ’ป **GitHub projects**\n- ๐Ÿ“… **Date-specific content**\n\n### You.com (RAG/Real-time)\n- ๐Ÿค– **RAG applications** (LLM-ready snippets)\n- ๐Ÿ“ฐ **Combined web + news** (single API call)\n- โšก **Real-time information** (current events)\n- ๐Ÿ“‹ **Summarization context** (\"What's the latest...\")\n- ๐Ÿ”„ **Live crawling** (full page content on demand)\n\n### SearXNG (Privacy-First/Self-Hosted)\n- ๐Ÿ”’ **Privacy-preserving search** (no tracking)\n- ๐ŸŒ **Multi-source aggregation** (70+ engines)\n- ๐Ÿ’ฐ **$0 API cost** (self-hosted)\n- ๐ŸŽฏ **Diverse perspectives** (results from multiple engines)\n- ๐Ÿ  **Self-hosted environments** (full control)\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Smart Auto-Routing](#smart-auto-routing)\n- [Configuration Guide](#configuration-guide)\n- [Provider Deep Dives](#provider-deep-dives)\n- [Usage Examples](#usage-examples)\n- [Workflow Examples](#workflow-examples)\n- [Optimization Tips](#optimization-tips)\n- [FAQ & Troubleshooting](#faq--troubleshooting)\n- [API Reference](#api-reference)\n\n---\n\n## Quick Start\n\n### Option A: Interactive Setup (Recommended)\n\n```bash\n# Run the setup wizard - it guides you through everything\npython3 scripts/setup.py\n```\n\nThe wizard explains each provider, collects your API keys, and creates `config.json` automatically.\n\n### Option B: Manual Setup\n\n```bash\n# 1. Set up at least one API key (or SearXNG instance)\nexport SERPER_API_KEY=\"your-key\" # https://serper.dev\nexport TAVILY_API_KEY=\"your-key\" # https://tavily.com\nexport EXA_API_KEY=\"your-key\" # https://exa.ai\nexport YOU_API_KEY=\"your-key\" # https://api.you.com\nexport SEARXNG_INSTANCE_URL=\"https://your-instance.example.com\" # Self-hosted\n\n# 2. Run a search (auto-routed!)\npython3 scripts/search.py -q \"best laptop 2024\"\n```\n\n### Run a Search\n\n```bash\n# Auto-routed to best provider\npython3 scripts/search.py -q \"best laptop 2024\"\n\n# Or specify a provider explicitly\npython3 scripts/search.py -p serper -q \"iPhone 16 specs\"\npython3 scripts/search.py -p tavily -q \"quantum computing explained\" --depth advanced\npython3 scripts/search.py -p exa -q \"AI startups 2024\" --category company\n```\n\n---\n\n## Smart Auto-Routing\n\n### How It Works\n\nWhen you don't specify a provider, the skill analyzes your query and routes it to the best provider:\n\n| Query Contains | Routes To | Example |\n|---------------|-----------|---------|\n| \"price\", \"buy\", \"shop\", \"cost\" | **Serper** | \"iPhone 16 price\" |\n| \"near me\", \"restaurant\", \"hotel\" | **Serper** | \"pizza near me\" |\n| \"weather\", \"news\", \"latest\" | **Serper** | \"weather Berlin\" |\n| \"how does\", \"explain\", \"what is\" | **Tavily** | \"how does TCP work\" |\n| \"research\", \"study\", \"analyze\" | **Tavily** | \"climate research\" |\n| \"tutorial\", \"guide\", \"learn\" | **Tavily** | \"python tutorial\" |\n| \"similar to\", \"companies like\" | **Exa** | \"companies like Stripe\" |\n| \"startup\", \"Series A\" | **Exa** | \"AI startups Series A\" |\n| \"github\", \"research paper\" | **Exa** | \"LLM papers arxiv\" |\n| \"private\", \"anonymous\", \"no tracking\" | **SearXNG** | \"search privately\" |\n| \"multiple sources\", \"aggregate\" | **SearXNG** | \"results from all engines\" |\n\n### Examples\n\n```bash\n# These are all auto-routed to the optimal provider:\npython3 scripts/search.py -q \"MacBook Pro M3 price\" # โ†’ Serper\npython3 scripts/search.py -q \"how does HTTPS work\" # โ†’ Tavily\npython3 scripts/search.py -q \"startups like Notion\" # โ†’ Exa\npython3 scripts/search.py -q \"best sushi restaurant near me\" # โ†’ Serper\npython3 scripts/search.py -q \"explain attention mechanism\" # โ†’ Tavily\npython3 scripts/search.py -q \"alternatives to Figma\" # โ†’ Exa\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG\n```\n\n### Result Caching (NEW in v2.7.0!)\n\nSearch results are **automatically cached** for 1 hour to save API costs:\n\n```bash\n# First request: fetches from API ($)\npython3 scripts/search.py -q \"AI startups 2024\"\n\n# Second request: uses cache (FREE!)\npython3 scripts/search.py -q \"AI startups 2024\"\n# Output includes: \"cached\": true\n\n# Bypass cache (force fresh results)\npython3 scripts/search.py -q \"AI startups 2024\" --no-cache\n\n# View cache stats\npython3 scripts/search.py --cache-stats\n\n# Clear all cached results\npython3 scripts/search.py --clear-cache\n\n# Custom TTL (in seconds, default: 3600 = 1 hour)\npython3 scripts/search.py -q \"query\" --cache-ttl 7200\n```\n\n**Cache location:** `.cache/` in skill directory (override with `WSP_CACHE_DIR` environment variable)\n\n### Debug Auto-Routing\n\nSee exactly why a provider was selected:\n\n```bash\npython3 scripts/search.py --explain-routing -q \"best laptop to buy\"\n```\n\nOutput:\n```json\n{\n \"query\": \"best laptop to buy\",\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=2)\",\n \"matched_keywords\": [\"buy\", \"best\"],\n \"available_providers\": [\"serper\", \"tavily\", \"exa\"]\n}\n```\n\n### Routing Info in Results\n\nEvery search result includes routing information:\n\n```json\n{\n \"provider\": \"serper\",\n \"query\": \"iPhone 16 price\",\n \"results\": [...],\n \"routing\": {\n \"auto_routed\": true,\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=1)\",\n \"matched_keywords\": [\"price\"]\n }\n}\n```\n\n---\n\n## Configuration Guide\n\n### Environment Variables\n\nCreate a `.env` file or set these in your shell:\n\n```bash\n# Required: Set at least one\nexport SERPER_API_KEY=\"your-serper-key\"\nexport TAVILY_API_KEY=\"your-tavily-key\"\nexport EXA_API_KEY=\"your-exa-key\"\n```\n\n### Config File (config.json)\n\nThe `config.json` file lets you customize auto-routing and provider defaults:\n\n```json\n{\n \"defaults\": {\n \"provider\": \"serper\",\n \"max_results\": 5\n },\n \n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"provider_priority\": [\"serper\", \"tavily\", \"exa\"],\n \"disabled_providers\": [],\n \"keyword_mappings\": {\n \"serper\": [\"price\", \"buy\", \"shop\", \"cost\", \"deal\", \"near me\", \"weather\"],\n \"tavily\": [\"how does\", \"explain\", \"research\", \"what is\", \"tutorial\"],\n \"exa\": [\"similar to\", \"companies like\", \"alternatives\", \"startup\", \"github\"]\n }\n },\n \n \"serper\": {\n \"country\": \"us\",\n \"language\": \"en\"\n },\n \n \"tavily\": {\n \"depth\": \"basic\",\n \"topic\": \"general\"\n },\n \n \"exa\": {\n \"type\": \"neural\"\n }\n}\n```\n\n### Configuration Examples\n\n#### Example 1: Disable Exa (Only Use Serper + Tavily)\n\n```json\n{\n \"auto_routing\": {\n \"disabled_providers\": [\"exa\"]\n }\n}\n```\n\n#### Example 2: Make Tavily the Default\n\n```json\n{\n \"auto_routing\": {\n \"fallback_provider\": \"tavily\"\n }\n}\n```\n\n#### Example 3: Add Custom Keywords\n\n```json\n{\n \"auto_routing\": {\n \"keyword_mappings\": {\n \"serper\": [\n \"price\", \"buy\", \"shop\", \"amazon\", \"ebay\", \"walmart\",\n \"deal\", \"discount\", \"coupon\", \"sale\", \"cheap\"\n ],\n \"tavily\": [\n \"how does\", \"explain\", \"research\", \"what is\",\n \"coursera\", \"udemy\", \"learn\", \"course\", \"certification\"\n ],\n \"exa\": [\n \"similar to\", \"companies like\", \"competitors\",\n \"YC company\", \"funded startup\", \"Series A\", \"Series B\"\n ]\n }\n }\n}\n```\n\n#### Example 4: German Locale for Serper\n\n```json\n{\n \"serper\": {\n \"country\": \"de\",\n \"language\": \"de\"\n }\n}\n```\n\n#### Example 5: Disable Auto-Routing\n\n```json\n{\n \"auto_routing\": {\n \"enabled\": false\n },\n \"defaults\": {\n \"provider\": \"serper\"\n }\n}\n```\n\n#### Example 6: Research-Heavy Config\n\n```json\n{\n \"auto_routing\": {\n \"fallback_provider\": \"tavily\",\n \"provider_priority\": [\"tavily\", \"serper\", \"exa\"]\n },\n \"tavily\": {\n \"depth\": \"advanced\",\n \"include_raw_content\": true\n }\n}\n```\n\n---\n\n## Provider Deep Dives\n\n### Serper (Google Search API)\n\n**What it is:** Direct access to Google Search results via API โ€” the same results you'd see on google.com.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐ŸŽฏ **Accuracy** | Google's search quality, knowledge graph, featured snippets |\n| ๐Ÿ›’ **Shopping** | Product prices, reviews, shopping results |\n| ๐Ÿ“ **Local** | Business listings, maps, places |\n| ๐Ÿ“ฐ **News** | Real-time news with Google News integration |\n| ๐Ÿ–ผ **Images** | Google Images search |\n| โšก **Speed** | Fastest response times (~200-400ms) |\n\n#### Best Use Cases\n- โœ… Product specifications and comparisons\n- โœ… Shopping and price lookups\n- โœ… Local business searches (\"restaurants near me\")\n- โœ… Quick factual queries (weather, conversions, definitions)\n- โœ… News headlines and current events\n- โœ… Image searches\n- โœ… When you need \"what Google shows\"\n\n#### Getting Your API Key\n1. Go to [serper.dev](https://serper.dev)\n2. Sign up with email or Google\n3. Copy your API key from the dashboard\n4. Set `SERPER_API_KEY` environment variable\n\n---\n\n### Tavily (Research Search)\n\n**What it is:** AI-optimized search engine built for research and RAG applications โ€” returns synthesized answers plus full content.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿ“š **Research Quality** | Optimized for comprehensive, accurate research |\n| ๐Ÿ’ฌ **AI Answers** | Returns synthesized answers, not just links |\n| ๐Ÿ“„ **Full Content** | Can return complete page content (raw_content) |\n| ๐ŸŽฏ **Domain Filtering** | Include/exclude specific domains |\n| ๐Ÿ”ฌ **Deep Mode** | Advanced search for thorough research |\n| ๐Ÿ“ฐ **Topic Modes** | Specialized for general vs news content |\n\n#### Best Use Cases\n- โœ… Research questions requiring synthesized answers\n- โœ… Academic or technical deep dives\n- โœ… When you need actual page content (not just snippets)\n- โœ… Multi-source information comparison\n- โœ… Domain-specific research (filter to authoritative sources)\n- โœ… News research with context\n- โœ… RAG/LLM applications\n\n#### Getting Your API Key\n1. Go to [tavily.com](https://tavily.com)\n2. Sign up and verify email\n3. Navigate to API Keys section\n4. Generate and copy your key\n5. Set `TAVILY_API_KEY` environment variable\n\n---\n\n### Exa (Neural Search)\n\n**What it is:** Neural/semantic search engine that understands meaning, not just keywords โ€” finds conceptually similar content.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿง  **Semantic Understanding** | Finds results by meaning, not keywords |\n| ๐Ÿ”— **Similar Pages** | Find pages similar to a reference URL |\n| ๐Ÿข **Company Discovery** | Excellent for finding startups, companies |\n| ๐Ÿ“‘ **Category Filters** | Filter by type (company, paper, tweet, etc.) |\n| ๐Ÿ“… **Date Filtering** | Precise date range searches |\n| ๐ŸŽ“ **Academic** | Great for research papers and technical content |\n\n#### Best Use Cases\n- โœ… Conceptual queries (\"companies building X\")\n- โœ… Finding similar companies or pages\n- โœ… Startup and company discovery\n- โœ… Research paper discovery\n- โœ… Finding GitHub projects\n- โœ… Date-filtered searches for recent content\n- โœ… When keyword matching fails\n\n#### Getting Your API Key\n1. Go to [exa.ai](https://exa.ai)\n2. Sign up with email or Google\n3. Navigate to API section in dashboard\n4. Copy your API key\n5. Set `EXA_API_KEY` environment variable\n\n---\n\n### SearXNG (Privacy-First Meta-Search)\n\n**What it is:** Open-source, self-hosted meta-search engine that aggregates results from 70+ search engines without tracking.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿ”’ **Privacy-First** | No tracking, no profiling, no data collection |\n| ๐ŸŒ **Multi-Engine** | Aggregates Google, Bing, DuckDuckGo, and 70+ more |\n| ๐Ÿ’ฐ **Free** | $0 API cost (self-hosted, unlimited queries) |\n| ๐ŸŽฏ **Diverse Results** | Get perspectives from multiple search engines |\n| โš™ **Customizable** | Choose which engines to use, SafeSearch, language |\n| ๐Ÿ  **Self-Hosted** | Full control over your search infrastructure |\n\n#### Best Use Cases\n- โœ… Privacy-sensitive searches (no tracking)\n- โœ… When you want diverse results from multiple engines\n- โœ… Budget-conscious (no API fees)\n- โœ… Self-hosted/air-gapped environments\n- โœ… Fallback when paid APIs are rate-limited\n- โœ… When \"aggregate everything\" is the goal\n\n#### Setting Up Your Instance\n```bash\n# Docker (recommended, 5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n\n# Enable JSON API in settings.yml:\n# search:\n# formats: [html, json]\n```\n\n1. See [docs.searxng.org](https://docs.searxng.org/admin/installation.html)\n2. Deploy via Docker, pip, or your preferred method\n3. Enable JSON format in `settings.yml`\n4. Set `SEARXNG_INSTANCE_URL` environment variable\n\n---\n\n## Usage Examples\n\n### Auto-Routed Searches (Recommended)\n\n```bash\n# Just search โ€” the skill picks the best provider\npython3 scripts/search.py -q \"Tesla Model 3 price\"\npython3 scripts/search.py -q \"how do neural networks learn\"\npython3 scripts/search.py -q \"YC startups like Stripe\"\npython3 scripts/search.py -q \"search privately without tracking\"\n```\n\n### Serper Options\n\n```bash\n# Different search types\npython3 scripts/search.py -p serper -q \"gaming monitor\" --type shopping\npython3 scripts/search.py -p serper -q \"coffee shop\" --type places\npython3 scripts/search.py -p serper -q \"AI news\" --type news\n\n# With time filter\npython3 scripts/search.py -p serper -q \"OpenAI news\" --time-range day\n\n# Include images\npython3 scripts/search.py -p serper -q \"iPhone 16 Pro\" --images\n\n# Different locale\npython3 scripts/search.py -p serper -q \"Wetter Wien\" --country at --language de\n```\n\n### Tavily Options\n\n```bash\n# Deep research mode\npython3 scripts/search.py -p tavily -q \"quantum computing applications\" --depth advanced\n\n# With full page content\npython3 scripts/search.py -p tavily -q \"transformer architecture\" --raw-content\n\n# Domain filtering\npython3 scripts/search.py -p tavily -q \"AI research\" --include-domains arxiv.org nature.com\n```\n\n### Exa Options\n\n```bash\n# Category filtering\npython3 scripts/search.py -p exa -q \"AI startups Series A\" --category company\npython3 scripts/search.py -p exa -q \"attention mechanism\" --category \"research paper\"\n\n# Date filtering\npython3 scripts/search.py -p exa -q \"YC companies\" --start-date 2024-01-01\n\n# Find similar pages\npython3 scripts/search.py -p exa --similar-url \"https://stripe.com\" --category company\n```\n\n### SearXNG Options\n\n```bash\n# Basic search\npython3 scripts/search.py -p searxng -q \"linux distros\"\n\n# Specific engines only\npython3 scripts/search.py -p searxng -q \"AI news\" --engines \"google,bing,duckduckgo\"\n\n# SafeSearch (0=off, 1=moderate, 2=strict)\npython3 scripts/search.py -p searxng -q \"privacy tools\" --searxng-safesearch 2\n\n# With time filter\npython3 scripts/search.py -p searxng -q \"open source projects\" --time-range week\n\n# Custom instance URL\npython3 scripts/search.py -p searxng -q \"test\" --searxng-url \"http://localhost:8080\"\n```\n\n---\n\n## Workflow Examples\n\n### ๐Ÿ›’ Product Research Workflow\n\n```bash\n# Step 1: Get product specs (auto-routed to Serper)\npython3 scripts/search.py -q \"MacBook Pro M3 Max specs\"\n\n# Step 2: Check prices (auto-routed to Serper)\npython3 scripts/search.py -q \"MacBook Pro M3 Max price comparison\"\n\n# Step 3: In-depth reviews (auto-routed to Tavily)\npython3 scripts/search.py -q \"detailed MacBook Pro M3 Max review\"\n```\n\n### ๐Ÿ“š Academic Research Workflow\n\n```bash\n# Step 1: Understand the topic (auto-routed to Tavily)\npython3 scripts/search.py -q \"explain transformer architecture in deep learning\"\n\n# Step 2: Find recent papers (Exa)\npython3 scripts/search.py -p exa -q \"transformer improvements\" --category \"research paper\" --start-date 2024-01-01\n\n# Step 3: Find implementations (Exa)\npython3 scripts/search.py -p exa -q \"transformer implementation\" --category github\n```\n\n### ๐Ÿข Competitive Analysis Workflow\n\n```bash\n# Step 1: Find competitors (auto-routed to Exa)\npython3 scripts/search.py -q \"companies like Notion\"\n\n# Step 2: Find similar products (Exa)\npython3 scripts/search.py -p exa --similar-url \"https://notion.so\" --category company\n\n# Step 3: Deep dive comparison (Tavily)\npython3 scripts/search.py -p tavily -q \"Notion vs Coda comparison\" --depth advanced\n```\n\n---\n\n## Optimization Tips\n\n### Cost Optimization\n\n| Tip | Savings |\n|-----|---------|\n| Use SearXNG for routine queries | **$0 API cost** |\n| Use auto-routing (defaults to Serper, cheapest paid) | Best value |\n| Use Tavily `basic` before `advanced` | ~50% cost reduction |\n| Set appropriate `max_results` | Linear cost savings |\n| Use Exa only for semantic queries | Avoid waste |\n\n### Performance Optimization\n\n| Tip | Impact |\n|-----|--------|\n| Serper is fastest (~200ms) | Use for time-sensitive queries |\n| Tavily `basic` faster than `advanced` | ~2x faster |\n| Lower `max_results` = faster response | Linear improvement |\n\n---\n\n## FAQ & Troubleshooting\n\n### General Questions\n\n**Q: Do I need API keys for all three providers?**\n> No. You only need keys for providers you want to use. Auto-routing skips providers without keys.\n\n**Q: Which provider should I start with?**\n> Serper โ€” it's the fastest, cheapest, and has the largest free tier (2,500 queries).\n\n**Q: Can I use multiple providers in one workflow?**\n> Yes! That's the recommended approach. See [Workflow Examples](#workflow-examples).\n\n**Q: How do I reduce API costs?**\n> Use auto-routing (defaults to cheapest), start with lower `max_results`, use Tavily `basic` before `advanced`.\n\n### Auto-Routing Questions\n\n**Q: Why did my query go to the wrong provider?**\n> Use `--explain-routing` to debug. Add custom keywords to config.json if needed.\n\n**Q: Can I add my own keywords?**\n> Yes! Edit `config.json` โ†’ `auto_routing.keyword_mappings`.\n\n**Q: How does keyword scoring work?**\n> Multi-word phrases get higher weights. \"companies like\" (2 words) scores higher than \"like\" (1 word).\n\n**Q: What if no keywords match?**\n> Uses the fallback provider (default: Serper).\n\n**Q: Can I force a specific provider?**\n> Yes, use `-p serper`, `-p tavily`, or `-p exa`.\n\n### Troubleshooting\n\n**Error: \"Missing API key\"**\n```bash\n# Check if key is set\necho $SERPER_API_KEY\n\n# Set it\nexport SERPER_API_KEY=\"your-key\"\n```\n\n**Error: \"API Error (401)\"**\n> Your API key is invalid or expired. Generate a new one.\n\n**Error: \"API Error (429)\"**\n> Rate limited. Wait and retry, or upgrade your plan.\n\n**Empty results?**\n> Try a different provider, broaden your query, or remove restrictive filters.\n\n**Slow responses?**\n> Reduce `max_results`, use Tavily `basic`, or use Serper (fastest).\n\n---\n\n## API Reference\n\n### Output Format\n\nAll providers return unified JSON:\n\n```json\n{\n \"provider\": \"serper|tavily|exa\",\n \"query\": \"original search query\",\n \"results\": [\n {\n \"title\": \"Page Title\",\n \"url\": \"https://example.com/page\",\n \"snippet\": \"Content excerpt...\",\n \"score\": 0.95,\n \"date\": \"2024-01-15\",\n \"raw_content\": \"Full page content (Tavily only)\"\n }\n ],\n \"images\": [\"url1\", \"url2\"],\n \"answer\": \"Synthesized answer\",\n \"knowledge_graph\": { },\n \"routing\": {\n \"auto_routed\": true,\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=1)\",\n \"matched_keywords\": [\"price\"]\n }\n}\n```\n\n### CLI Options Reference\n\n| Option | Providers | Description |\n|--------|-----------|-------------|\n| `-q, --query` | All | Search query |\n| `-p, --provider` | All | Provider: auto, serper, tavily, exa, you, searxng |\n| `-n, --max-results` | All | Max results (default: 5) |\n| `--auto` | All | Force auto-routing |\n| `--explain-routing` | All | Debug auto-routing |\n| `--images` | Serper, Tavily | Include images |\n| `--country` | Serper, You | Country code (default: us) |\n| `--language` | Serper, SearXNG | Language code (default: en) |\n| `--type` | Serper | search/news/images/videos/places/shopping |\n| `--time-range` | Serper, SearXNG | hour/day/week/month/year |\n| `--depth` | Tavily | basic/advanced |\n| `--topic` | Tavily | general/news |\n| `--raw-content` | Tavily | Include full page content |\n| `--exa-type` | Exa | neural/keyword |\n| `--category` | Exa | company/research paper/news/pdf/github/tweet |\n| `--start-date` | Exa | Start date (YYYY-MM-DD) |\n| `--end-date` | Exa | End date (YYYY-MM-DD) |\n| `--similar-url` | Exa | Find similar pages |\n| `--searxng-url` | SearXNG | Instance URL |\n| `--searxng-safesearch` | SearXNG | 0=off, 1=moderate, 2=strict |\n| `--engines` | SearXNG | Specific engines (google,bing,duckduckgo) |\n| `--categories` | SearXNG | Search categories (general,images,news) |\n| `--include-domains` | Tavily, Exa | Only these domains |\n| `--exclude-domains` | Tavily, Exa | Exclude these domains |\n| `--compact` | All | Compact JSON output |\n\n---\n\n## License\n\nMIT\n\n---\n\n## Links\n\n- [Serper](https://serper.dev) โ€” Google Search API\n- [Tavily](https://tavily.com) โ€” AI Research Search\n- [Exa](https://exa.ai) โ€” Neural Search\n- [ClawHub](https://clawhub.ai) โ€” OpenClaw Skills\n\nFile v2.8.5:_meta.json\n\n{\n \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n \"slug\": \"web-search-plus\",\n \"version\": \"2.8.5\",\n \"publishedAt\": 1771603102076\n}\n\nFile v2.8.5:CHANGELOG.md\n\n# Changelog - Web Search Plus\n\n## [2.8.5] - 2026-02-20\n\n### โœจ Feature: Perplexity freshness filter\n\n- Added `freshness` parameter to Perplexity provider (`day`, `week`, `month`, `year`)\n- Maps to Perplexity's native `search_recency_filter` parameter\n- Example: `python3 scripts/search.py -p perplexity -q \"latest AI news\" --freshness day`\n- Consistent with freshness support in Serper and Brave providers\n\n## [2.8.4] - 2026-02-20\n\n### ๐Ÿ”’ Security Fix: SSRF protection in setup wizard\n\n- **Fixed:** `setup.py` SearXNG connection test had no SSRF protection (unlike `search.py`)\n- **Before:** Operator could be tricked into probing internal networks during setup\n- **After:** Same IP validation as `search.py` โ€” blocks private IPs, cloud metadata, loopback\n- **Credit:** ClawHub security scanner\n\n## [2.8.3] - 2026-02-20\n\n### ๐Ÿ› Critical Fix: Perplexity results empty\n\n- **Fixed:** Perplexity provider returned 0 results because the AI-synthesized answer wasn't mapped into the results array\n- **Before:** Only extracted URLs from the answer text were returned as results (often 0)\n- **After:** The full answer is now the primary result (title, snippet with cleaned text), extracted source URLs follow as additional results\n- **Impact:** Perplexity queries now always return at least 1 result with the synthesized answer\n\n## [2.8.0] - 2026-02-20\n\n### ๐Ÿ†• New Provider: Perplexity (AI-Synthesized Answers)\n\nAdded Perplexity as the 6th search provider via Kilo Gateway โ€” the first provider that returns **direct answers with citations** instead of just links:\n\n#### Features\n- **AI-Synthesized Answers**: Get a complete answer, not a list of links\n- **Inline Citations**: Every claim backed by `[1][2][3]` source references\n- **Real-Time Web Search**: Perplexity searches the web live, reads pages, and summarizes\n- **Zero Extra Config**: Works through Kilo Gateway with your existing `KILOCODE_API_KEY`\n- **Model**: `perplexity/sonar-pro` (best quality, supports complex queries)\n\n#### Auto-Routing Signals\nNew direct-answer intent detection routes to Perplexity for:\n- Status queries: \"status of\", \"current state of\", \"what is the status\"\n- Local info: \"events in [city]\", \"things to do in\", \"what's happening in\"\n- Direct questions: \"what is\", \"who is\", \"when did\", \"how many\"\n- Current affairs: \"this week\", \"this weekend\", \"right now\", \"today\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"events in Graz Austria this weekend\" # โ†’ Perplexity\npython3 scripts/search.py -q \"what is the current status of Ethereum\" # โ†’ Perplexity\n\n# Explicit\npython3 scripts/search.py -p perplexity -q \"latest AI regulation news\"\n```\n\n#### Configuration\nRequires `KILOCODE_API_KEY` environment variable (Kilo Gateway account).\nNo additional API key needed โ€” Perplexity is accessed through Kilo's unified API.\n\n```bash\nexport KILOCODE_API_KEY=\"your-kilo-key\"\n```\n\n### ๐Ÿ”ง Routing Rebalance\n\nMajor overhaul of the auto-routing confidence scoring to fix Serper dominance:\n\n#### Problem\nSerper (Google) was winning ~90% of queries due to:\n- High recency multiplier boosting Serper on any query with dates/years\n- Default provider priority placing Serper first in ties\n- Research and discovery signals not strong enough to override\n\n#### Changes\n- **Lowered Serper recency multiplier** โ€” date mentions no longer auto-route to Google\n- **Strengthened research signals** for Tavily:\n - Added: \"status of\", \"what happened with\", \"how does X compare\"\n - Boosted weights for comparison patterns (4.0 โ†’ 5.0)\n- **Strengthened discovery signals** for Exa:\n - Added: \"events in\", \"things to do in\", \"startups similar to\"\n - Boosted weights for local discovery patterns\n- **Updated provider priority order**: `tavily โ†’ exa โ†’ perplexity โ†’ serper โ†’ you โ†’ searxng`\n - Serper moved from 1st to 4th in tie-breaking\n - Research/discovery providers now win on ambiguous queries\n\n#### Routing Test Results\n\n| Query | Before | After | โœ“ |\n|-------|--------|-------|---|\n| \"latest OpenClaw version Feb 2026\" | Serper | Serper | โœ… |\n| \"Ethereum Pectra upgrade status\" | Serper | **Tavily** | โœ… |\n| \"events in Graz this weekend\" | Serper | **Perplexity** | โœ… |\n| \"compare SearXNG vs Brave for AI agents\" | Serper | **Tavily** | โœ… |\n| \"Sam Altman OpenAI news this week\" | Serper | Serper | โœ… |\n| \"find startups similar to Kilo Code\" | Serper | **Exa** | โœ… |\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | Perplexity | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:----------:|:-------:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšก | โšกโšกโšก | โšก |\n| Direct Answers | โœ— | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— |\n| Citations | โœ— | โœ— | โœ— | โœ“ | โœ— | โœ— |\n| Local Events | โœ“ | โœ— | โœ“ | โœ“โœ“ | โœ— | โœ“ |\n| Research | โœ— | โœ“โœ“ | โœ“ | โœ“ | โœ“ | โœ— |\n| Discovery | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— | โœ— |\n| Self-Hosted | โœ— | โœ— | โœ— | โœ— | โœ— | โœ“ |\n\n## [2.7.0] - 2026-02-14\n\n### โœจ Added\n- Provider cooldown tracking in `.cache/provider_health.json`\n- Exponential cooldown on provider failures: **1m โ†’ 5m โ†’ 25m โ†’ 1h (cap)**\n- Retry strategy for transient failures (timeout, 429, 503): up to 2 retries with backoff **1s โ†’ 3s โ†’ 9s**\n- Smarter cache keys hashed from full request context (query/provider/max_results + locale, freshness, time_range, topic, search_engines, include_news, and related params)\n- Cross-provider result deduplication by normalized URL during fallback merge\n\n### ๐Ÿ”ง Changed\n- Cooldown providers are skipped in routing while their cooldown is active\n- Provider health is reset automatically after successful requests\n- Fallback output now includes dedup metadata:\n - `deduplicated: true|false`\n - `metadata.dedup_count`\n\n\n## [2.6.5] - 2026-02-11\n\n### ๐Ÿ†• File-Based Result Caching\n\nAdded local caching to save API costs on repeated searches:\n\n#### Features\n- **Automatic Caching**: Search results cached locally by default\n- **1-Hour TTL**: Results expire after 3600 seconds (configurable)\n- **Cache Indicators**: Response includes `cached: true/false` and `cache_age_seconds`\n- **Zero-Cost Repeats**: Cached requests don't hit APIs\n\n#### New CLI Options\n- `--cache-ttl SECONDS` โ€” Custom cache TTL (default: 3600)\n- `--no-cache` โ€” Bypass cache, always fetch fresh\n- `--clear-cache` โ€” Delete all cached results\n- `--cache-stats` โ€” Show cache statistics (entries, size, age)\n\n#### Configuration\n- **Cache directory**: `.cache/` in skill directory\n- **Environment variable**: `WSP_CACHE_DIR` to override location\n- **Cache key**: Based on query + provider + max_results (SHA256)\n\n#### Usage Examples\n```bash\n# First request costs API credits\npython3 scripts/search.py -q \"AI startups\"\n\n# Second request is FREE (uses cache)\npython3 scripts/search.py -q \"AI startups\"\n\n# Force fresh results\npython3 scripts/search.py -q \"AI startups\" --no-cache\n\n# View stats\npython3 scripts/search.py --cache-stats\n\n# Clear everything\npython3 scripts/search.py --clear-cache\n```\n\n#### Technical Details\n- Cache files: JSON with metadata (_cache_timestamp, _cache_key, etc.)\n- Automatic cleanup of expired entries on access\n- Graceful handling of corrupted cache files\n\n## [2.6.1] - 2026-02-04\n\n- Privacy cleanup: removed hardcoded paths and personal info from docs\n\n## [2.5.0] - 2026-02-03\n\n### ๐Ÿ†• New Provider: SearXNG (Privacy-First Meta-Search)\n\nAdded SearXNG as the 5th search provider, focused on privacy and self-hosted search:\n\n#### Features\n- **Privacy-Preserving**: No tracking, no profiling โ€” your searches stay private\n- **Multi-Source Aggregation**: Queries 70+ upstream engines (Google, Bing, DuckDuckGo, etc.)\n- **$0 API Cost**: Self-hosted = unlimited queries with no API fees\n- **Diverse Results**: Get perspectives from multiple search engines in one query\n- **Customizable**: Choose which engines to use, set SafeSearch levels, language preferences\n\n#### Auto-Routing Signals\nNew privacy/multi-source intent detection routes to SearXNG for:\n- Privacy queries: \"private\", \"anonymous\", \"without tracking\", \"no tracking\"\n- Multi-source: \"aggregate results\", \"multiple sources\", \"diverse perspectives\"\n- Budget/free: \"free search\", \"no api cost\", \"self-hosted search\"\n- German: \"privat\", \"anonym\", \"ohne tracking\", \"verschiedene quellen\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG\n\n# Explicit\npython3 scripts/search.py -p searxng -q \"linux distros\"\npython3 scripts/search.py -p searxng -q \"AI news\" --engines \"google,bing,duckduckgo\"\npython3 scripts/search.py -p searxng -q \"privacy tools\" --searxng-safesearch 2\n```\n\n#### Configuration\n```json\n{\n \"searxng\": {\n \"instance_url\": \"https://your-instance.example.com\",\n \"safesearch\": 0,\n \"engines\": null,\n \"language\": \"en\"\n }\n}\n```\n\n#### Setup\nSearXNG requires a self-hosted instance with JSON format enabled:\n```bash\n# Docker setup (5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n\n# Enable JSON in settings.yml:\n# search:\n# formats: [html, json]\n\n# Set instance URL\nexport SEARXNG_INSTANCE_URL=\"http://localhost:8080\"\n```\n\nSee: https://docs.searxng.org/admin/installation.html\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:-------:|:-------:|\n| Privacy-First | โœ— | โœ— | โœ— | โœ— | โœ“โœ“ |\n| Self-Hosted | โœ— | โœ— | โœ— | โœ— | โœ“ |\n| API Cost | $$ | $$ | $$ | $ | **FREE** |\n| Multi-Engine | โœ— | โœ— | โœ— | โœ— | โœ“ (70+) |\n\n### ๐Ÿ”ง Technical Changes\n\n- Added `search_searxng()` function with full error handling\n- Added `PRIVACY_SIGNALS` to QueryAnalyzer for auto-routing\n- Updated setup wizard with SearXNG option (instance URL validation)\n- Updated config.example.json with searxng section\n- New CLI args: `--searxng-url`, `--searxng-safesearch`, `--engines`, `--categories`\n\n---\n\n## [2.4.4] - 2026-02-03\n\n### ๐Ÿ“ Documentation: Provider Count Fix\n\n- **Fixed:** \"You can use 1, 2, or all 3\" โ†’ \"1, 2, 3, or all 4\" (we have 4 providers now!)\n- **Impact:** Accurate documentation for setup wizard\n\n## [2.4.3] - 2026-02-03\n\n### ๐Ÿ“ Documentation: Updated README\n\n- **Added:** \"NEW in v2.4.2\" badge for You.com in SKILL.md\n- **Impact:** ClawHub README now properly highlights You.com as new feature\n\n## [2.4.2] - 2026-02-03\n\n### ๐Ÿ› Critical Fix: You.com API Configuration\n\n- **Fixed:** Incorrect hostname (`api.ydc-index.io` โ†’ `ydc-index.io`)\n- **Fixed:** Incorrect header name (`X-API-Key` โ†’ `X-API-KEY` uppercase)\n- **Impact:** You.com now works correctly - was giving 403 Forbidden before\n- **Status:** โœ… Fully tested and working\n\n## [2.4.1] - 2026-02-03\n\n### ๐Ÿ› Bugfix: You.com URL Encoding\n\n- **Fixed:** URL encoding for You.com queries - spaces and special characters now properly encoded\n- **Impact:** Queries with spaces (e.g., \"OpenClaw AI framework\") work correctly now\n- **Technical:** Added `urllib.parse.quote` for parameter encoding\n\n## [2.4.0] - 2026-02-03\n\n### ๐Ÿ†• New Provider: You.com\n\nAdded You.com as the 4th search provider, optimized for RAG applications and real-time information:\n\n#### Features\n- **LLM-Ready Snippets**: Pre-extracted, query-aware text excerpts perfect for feeding into AI models\n- **Unified Web + News**: Get both web pages and news articles in a single API call\n- **Live Crawling**: Fetch full page content on-demand in Markdown format (`--livecrawl`)\n- **Automatic News Classification**: Intelligently includes news results based on query intent\n- **Freshness Controls**: Filter by recency (day, week, month, year, or date range)\n- **SafeSearch Support**: Content filtering (off, moderate, strict)\n\n#### Auto-Routing Signals\nNew RAG/Real-time intent detection routes to You.com for:\n- RAG context queries: \"summarize\", \"key points\", \"tldr\", \"context for\"\n- Real-time info: \"latest news\", \"current status\", \"right now\", \"what's happening\"\n- Information synthesis: \"updates on\", \"situation\", \"main takeaways\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"summarize key points about AI regulation\" # โ†’ You.com\n\n# Explicit\npython3 scripts/search.py -p you -q \"climate change\" --livecrawl all\npython3 scripts/search.py -p you -q \"tech news\" --freshness week\n```\n\n#### Configuration\n```json\n{\n \"you\": {\n \"country\": \"US\",\n \"language\": \"en\",\n \"safesearch\": \"moderate\",\n \"include_news\": true\n }\n}\n```\n\n#### API Key Setup\n```bash\nexport YOU_API_KEY=\"your-key\" # Get from https://api.you.com\n```\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | You.com |\n|---------|:------:|:------:|:---:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšกโšก |\n| News Integration | โœ“ | โœ— | โœ— | โœ“ |\n| RAG-Optimized | โœ— | โœ“ | โœ— | โœ“โœ“ |\n| Full Page Content | โœ— | โœ“ | โœ“ | โœ“ |\n\n---\n\n## [2.1.5] - 2026-01-27\n\n### ๐Ÿ“ Documentation\n\n- Added warning about NOT using Tavily/Serper/Exa in core OpenClaw config\n- Core OpenClaw only supports `brave` as the built-in provider\n- This skill's providers must be used via environment variables and scripts, not `openclaw.json`\n\n## [2.1.0] - 2026-01-23\n\n### ๐Ÿง  Intelligent Multi-Signal Routing\n\nCompletely overhauled auto-routing with sophisticated query analysis:\n\n#### Intent Classification\n- **Shopping Intent**: Detects price patterns (\"how much\", \"cost of\"), purchase signals (\"buy\", \"order\"), deal keywords, and product+brand combinations\n- **Research Intent**: Identifies explanation patterns (\"how does\", \"why does\"), analysis signals (\"pros and cons\", \"compare\"), learning keywords, and complex multi-clause queries\n- **Discovery Intent**: Recognizes similarity patterns (\"similar to\", \"alternatives\"), company discovery signals, URL/domain detection, and academic patterns\n\n#### Linguistic Pattern Detection\n- \"How much\" / \"price of\" โ†’ Shopping (Serper)\n- \"How does\" / \"Why does\" / \"Explain\" โ†’ Research (Tavily)\n- \"Companies like\" / \"Similar to\" / \"Alternatives\" โ†’ Discovery (Exa)\n- Product + Brand name combos โ†’ Shopping (Serper)\n- URLs and domains in query โ†’ Similar search (Exa)\n\n#### Query Analysis Features\n- **Complexity scoring**: Long, multi-clause queries get routed to research providers\n- **URL detection**: Automatic detection of URLs/domains triggers Exa similar search\n- **Brand recognition**: Tech brands (Apple, Samsung, Sony, etc.) with product terms โ†’ shopping\n- **Recency signals**: \"latest\", \"2026\", \"breaking\" boost news mode\n\n#### Confidence Scoring\n- **HIGH (70-100%)**: Strong signal match, very reliable routing\n- **MEDIUM (40-69%)**: Good match, should work well\n- **LOW (0-39%)**: Ambiguous query, using fallback provider\n- Confidence based on absolute signal strength + relative margin over alternatives\n\n#### Enhanced Debug Mode\n```bash\npython3 scripts/search.py --explain-routing -q \"your query\"\n```\n\nNow shows:\n- Routing decision with confidence level\n- All provider scores\n- Top matched signals with weights\n- Query analysis (complexity, URL detection, recency focus)\n- All matched patterns per provider\n\n### ๐Ÿ”ง Technical Changes\n\n#### QueryAnalyzer Class\nNew `QueryAnalyzer` class with:\n- `SHOPPING_SIGNALS`: 25+ weighted patterns for shopping intent\n- `RESEARCH_SIGNALS`: 30+ weighted patterns for research intent\n- `DISCOVERY_SIGNALS`: 20+ weighted patterns for discovery intent\n- `LOCAL_NEWS_SIGNALS`: 25+ patterns for local/news queries\n- `BRAND_PATTERNS`: Tech brand detection regex\n\n#### Signal Weighting\n- Multi-word phrases get higher weights (e.g., \"how much\" = 4.0 vs \"price\" = 3.0)\n- Strong signals: price patterns (4.0), similarity patterns (5.0), URLs (5.0)\n- Medium signals: product terms (2.5), learning keywords (2.5)\n- Bonus scoring: Product+brand combo (+3.0), complex query (+2.5)\n\n#### Improved Output Format\n```json\n{\n \"routing\": {\n \"auto_routed\": true,\n \"provider\": \"serper\",\n \"confidence\": 0.78,\n \"confidence_level\": \"high\",\n \"reason\": \"high_confidence_match\",\n \"top_signals\": [{\"matched\": \"price\", \"weight\": 3.0}],\n \"scores\": {\"serper\": 7.0, \"tavily\": 0.0, \"exa\": 0.0}\n }\n}\n```\n\n### ๐Ÿ“š Documentation Updates\n\n- **SKILL.md**: Complete rewrite with signal tables and confidence scoring guide\n- **README.md**: Updated with intelligent routing examples and confidence levels\n- **FAQ**: Updated to explain multi-signal analysis\n\n### ๐Ÿงช Test Results\n\n| Query | Provider | Confidence | Signals |\n|-------|----------|------------|---------|\n| \"how much does iPhone 16 cost\" | Serper | 68% | \"how much\", brand+product |\n| \"how does quantum entanglement work\" | Tavily | 86% HIGH | \"how does\", \"what are\", \"implications\" |\n| \"startups similar to Notion\" | Exa | 76% HIGH | \"similar to\", \"Series A\" |\n| \"companies like stripe.com\" | Exa | 100% HIGH | URL detected, \"companies like\" |\n| \"MacBook Pro M3 specs review\" | Serper | 70% HIGH | brand+product, \"specs\", \"review\" |\n| \"Tesla\" | Serper | 0% LOW | No signals (fallback) |\n| \"arxiv papers on transformers\" | Exa | 58% | \"arxiv\" |\n| \"latest AI news 2026\" | Serper | 77% HIGH | \"latest\", \"news\", \"2026\" |\n\n---\n\n## [2.0.0] - 2026-01-23\n\n### ๐ŸŽ‰ Major Features\n\n#### Smart Auto-Routing\n- **Automatic provider selection** based on query analysis\n- No need to manually choose provider - just search!\n- Intelligent keyword matching for routing decisions\n- Pattern detection for query types (shopping, research, discovery)\n- Scoring system for provider selection\n\n#### User Configuration\n- **config.json**: Full control over auto-routing behavior\n- **Configurable keyword mappings**: Add your own routing keywords\n- **Provider priority**: Set tie-breaker order\n- **Disable providers**: Turn off providers you don't have API keys for\n- **Enable/disable auto-routing**: Opt-in or opt-out as needed\n\n#### Debugging Tools\n- **--explain-routing** flag: See exactly why a provider was selected\n- Detailed routing metadata in JSON responses\n- Shows matched keywords and routing scores\n\n### ๐Ÿ“š Documentation\n\n- **README.md**: Complete auto-routing guide with examples\n- **SKILL.md**: Detailed routing logic and configuration reference\n- **FAQ section**: Common questions about auto-routing\n- **Configuration examples**: Pre-built configs for common use cases\n\n---\n\n## [1.0.x] - Initial Release\n\n- Multi-provider search: Serper, Tavily, Exa\n- Manual provider selection with `-p` flag\n- Unified JSON output format\n- Provider-specific options (--depth, --category, --similar-url, etc.)\n- Domain filtering for Tavily/Exa\n- Date filtering for Exa\n\nFile v2.8.5:FAQ.md\n\n# Frequently Asked Questions\n\n## Caching (NEW in v2.7.0!)\n\n### How does caching work?\nSearch results are automatically cached locally for 1 hour (3600 seconds). When you make the same query again, you get instant results at $0 API cost. The cache key is based on: query text + provider + max_results.\n\n### Where are cached results stored?\nIn `.cache/` directory inside the skill folder by default. Override with `WSP_CACHE_DIR` environment variable:\n```bash\nexport WSP_CACHE_DIR=\"/path/to/custom/cache\"\n```\n\n### How do I see cache stats?\n```bash\npython3 scripts/search.py --cache-stats\n```\nThis shows total entries, size, oldest/newest entries, and breakdown by provider.\n\n### How do I clear the cache?\n```bash\npython3 scripts/search.py --clear-cache\n```\n\n### Can I change the cache TTL?\nYes! Default is 3600 seconds (1 hour). Set a custom TTL per request:\n```bash\npython3 scripts/search.py -q \"query\" --cache-ttl 7200 # 2 hours\n```\n\n### How do I skip the cache?\nUse `--no-cache` to always fetch fresh results:\n```bash\npython3 scripts/search.py -q \"query\" --no-cache\n```\n\n### How do I know if a result was cached?\nThe response includes:\n- `\"cached\": true/false` โ€” whether result came from cache\n- `\"cache_age_seconds\": 1234` โ€” how old the cached result is (when cached)\n\n---\n\n## General\n\n### How does auto-routing decide which provider to use?\nMulti-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.\n\n### What if it picks the wrong provider?\nOverride with `-p serper/tavily/exa`. Check `--explain-routing` to understand why it chose differently.\n\n### What does \"low confidence\" mean?\nQuery is ambiguous (e.g., \"Tesla\" could be cars, stock, or company). Falls back to Serper. Results may vary.\n\n### Can I disable a provider?\nYes! In config.json: `\"disabled_providers\": [\"exa\"]`\n\n---\n\n## API Keys\n\n### Which API keys do I need?\nAt minimum ONE key (or SearXNG instance). You can use just Serper, just Tavily, just Exa, just You.com, or just SearXNG. Missing keys = that provider is skipped.\n\n### Where do I get API keys?\n- Serper: https://serper.dev (2,500 free queries, no credit card)\n- Tavily: https://tavily.com (1,000 free searches/month)\n- Exa: https://exa.ai (1,000 free searches/month)\n- You.com: https://api.you.com (Limited free tier for testing)\n- SearXNG: Self-hosted, no key needed! https://docs.searxng.org/admin/installation.html\n\n### How do I set API keys?\nTwo options (both auto-load):\n\n**Option A: .env file**\n```bash\nexport SERPER_API_KEY=\"your-key\"\n```\n\n**Option B: config.json** (v2.2.1+)\n```json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## Routing Details\n\n### How do I know which provider handled my search?\nCheck `routing.provider` in JSON output, or `[๐Ÿ” Searched with: Provider]` in chat responses.\n\n### Why does it sometimes choose Serper for research questions?\nIf the query has brand/product signals (e.g., \"how does Tesla FSD work\"), shopping intent may outweigh research intent. Override with `-p tavily`.\n\n### What's the confidence threshold?\nDefault: 0.3 (30%). Below this = low confidence, uses fallback. Adjustable in config.json.\n\n---\n\n## You.com Specific\n\n### When should I use You.com over other providers?\nYou.com excels at:\n- **RAG applications**: Pre-extracted snippets ready for LLM consumption\n- **Real-time information**: Current events, breaking news, status updates\n- **Combined sources**: Web + news results in a single API call\n- **Summarization tasks**: \"What's the latest on...\", \"Key points about...\"\n\n### What's the livecrawl feature?\nYou.com can fetch full page content on-demand. Use `--livecrawl web` for web results, `--livecrawl news` for news articles, or `--livecrawl all` for both. Content is returned in Markdown format.\n\n### Does You.com include news automatically?\nYes! You.com's intelligent classification automatically includes relevant news results when your query has news intent. You can also use `--include-news` to explicitly enable it.\n\n---\n\n## SearXNG Specific\n\n### Do I need my own SearXNG instance?\nYes! SearXNG is self-hosted. Most public instances disable the JSON API to prevent bot abuse. You need to run your own instance with JSON format enabled. See: https://docs.searxng.org/admin/installation.html\n\n### How do I set up SearXNG?\nDocker is the easiest way:\n```bash\ndocker run -d -p 8080:8080 searxng/searxng\n```\nThen enable JSON in `settings.yml`:\n```yaml\nsearch:\n formats:\n - html\n - json\n```\n\n### Why am I getting \"403 Forbidden\"?\nThe JSON API is disabled on your instance. Enable it in `settings.yml` under `search.formats`.\n\n### What's the API cost for SearXNG?\n**$0!** SearXNG is free and open-source. You only pay for hosting (~$5/month VPS). Unlimited queries.\n\n### When should I use SearXNG?\n- **Privacy-sensitive queries**: No tracking, no profiling\n- **Budget-conscious**: $0 API cost\n- **Diverse results**: Aggregates 70+ search engines\n- **Self-hosted requirements**: Full control over your search infrastructure\n- **Fallback provider**: When paid APIs are rate-limited\n\n### Can I limit which search engines SearXNG uses?\nYes! Use `--engines google,bing,duckduckgo` to specify engines, or configure defaults in `config.json`.\n\n---\n\n## Provider Selection\n\n### Which provider should I use?\n\n| Query Type | Best Provider | Why |\n|------------|---------------|-----|\n| **Shopping** (\"buy laptop\", \"cheap shoes\") | **Serper** | Google Shopping, price comparisons, local stores |\n| **Research** (\"how does X work?\", \"explain Y\") | **Tavily** | Deep research, academic quality, full-page content |\n| **Startups/Papers** (\"companies like X\", \"arxiv papers\") | **Exa** | Semantic/neural search, startup discovery |\n| **RAG/Real-time** (\"summarize latest\", \"current events\") | **You.com** | LLM-ready snippets, combined web+news |\n| **Privacy** (\"search without tracking\") | **SearXNG** | No tracking, multi-source, self-hosted |\n\n**Tip:** Enable auto-routing and let the skill choose automatically! ๐ŸŽฏ\n\n### Do I need all 5 providers?\n**No!** All providers are optional. You can use:\n- **1 provider** (e.g., just Serper for everything)\n- **2-3 providers** (e.g., Serper + You.com for most needs)\n- **All 5** (maximum flexibility + fallback options)\n\n### How much do the APIs cost?\n\n| Provider | Free Tier | Paid Plan |\n|----------|-----------|-----------|\n| **Serper** | 2,500 queries/mo | $50/mo (5,000 queries) |\n| **Tavily** | 1,000 queries/mo | $150/mo (10,000 queries) |\n| **Exa** | 1,000 queries/mo | $1,000/mo (100,000 queries) |\n| **You.com** | Limited free | ~$10/mo (varies by usage) |\n| **SearXNG** | **FREE** โœ… | Only VPS cost (~$5/mo if self-hosting) |\n\n**Budget tip:** Use SearXNG as primary + others as fallback for specialized queries!\n\n### How private is SearXNG really?\n\n| Setup | Privacy Level |\n|-------|---------------|\n| **Self-hosted (your VPS)** | โญโญโญโญโญ You control everything |\n| **Self-hosted (Docker local)** | โญโญโญโญโญ Fully private |\n| **Public instance** | โญโญโญ Depends on operator's logging policy |\n\n**Best practice:** Self-host if privacy is critical.\n\n### Which provider has the best results?\n\n| Metric | Winner |\n|--------|--------|\n| **Most accurate for facts** | Serper (Google) |\n| **Best for research depth** | Tavily |\n| **Best for semantic queries** | Exa |\n| **Best for RAG/AI context** | You.com |\n| **Most diverse sources** | SearXNG (70+ engines) |\n| **Most private** | SearXNG (self-hosted) |\n\n**Recommendation:** Enable multiple providers + auto-routing for best overall experience.\n\n### How does auto-routing work?\nThe skill analyzes your query for keywords and patterns:\n\n```python\n\"buy cheap laptop\" โ†’ Serper (shopping signals)\n\"how does AI work?\" โ†’ Tavily (research/explanation)\n\"companies like X\" โ†’ Exa (semantic/similar)\n\"summarize latest news\" โ†’ You.com (RAG/real-time)\n\"search privately\" โ†’ SearXNG (privacy signals)\n```\n\n**Confidence threshold:** Only routes if confidence > 30%. Otherwise uses default provider.\n\n**Override:** Use `-p provider` to force a specific provider.\n\n---\n\n## Production Use\n\n### Can I use this in production?\n**Yes!** Web-search-plus is production-ready:\n- โœ… Error handling with automatic fallback\n- โœ… Rate limit protection\n- โœ… Timeout handling (30s per provider)\n- โœ… API key security (.env + config.json gitignored)\n- โœ… 5 providers for redundancy\n\n**Tip:** Monitor API usage to avoid exceeding free tiers!\n\n### What if I run out of API credits?\n1. **Fallback chain:** Other enabled providers automatically take over\n2. **Use SearXNG:** Switch to self-hosted (unlimited queries)\n3. **Upgrade plan:** Paid tiers have higher limits\n4. **Rate limit:** Use `disabled_providers` to skip exhausted APIs temporarily\n\n---\n\n## Updates\n\n### How do I update to the latest version?\n\n**Via ClawHub (recommended):**\n```bash\nclawhub update web-search-plus --registry \"https://www.clawhub.ai\" --no-input\n```\n\n**Manually:**\n```bash\ncd /path/to/workspace/skills/web-search-plus/\ngit pull origin main\npython3 scripts/setup.py # Re-run to configure new features\n```\n\n### Where can I report bugs or request features?\n- **GitHub Issues:** https://github.com/robbyczgw-cla/web-search-plus/issues\n- **ClawHub:** https://www.clawhub.ai/skills/web-search-plus\n\nFile v2.8.5:TROUBLESHOOTING.md\n\n# Troubleshooting Guide\n\n## Caching Issues (v2.7.0+)\n\n### Cache not working / always fetching fresh\n\n**Symptoms:**\n- Every request hits the API\n- `\"cached\": false` even for repeated queries\n\n**Solutions:**\n1. Check cache directory exists and is writable:\n ```bash\n ls -la .cache/ # Should exist in skill directory\n ```\n2. Verify `--no-cache` isn't being passed\n3. Check disk space isn't full\n4. Ensure query is EXACTLY the same (including provider and max_results)\n\n### Stale results from cache\n\n**Symptoms:**\n- Getting outdated information\n- Cache TTL seems too long\n\n**Solutions:**\n1. Use `--no-cache` to force fresh results\n2. Reduce TTL: `--cache-ttl 1800` (30 minutes)\n3. Clear cache: `python3 scripts/search.py --clear-cache`\n\n### Cache growing too large\n\n**Symptoms:**\n- Disk space filling up\n- Many .json files in `.cache/`\n\n**Solutions:**\n1. Clear cache periodically:\n ```bash\n python3 scripts/search.py --clear-cache\n ```\n2. Set up a cron job to clear weekly\n3. Use a smaller TTL so entries expire faster\n\n### \"Permission denied\" when caching\n\n**Symptoms:**\n- Cache write errors in stderr\n- Searches work but don't cache\n\n**Solutions:**\n1. Check directory permissions: `chmod 755 .cache/`\n2. Use custom cache dir: `export WSP_CACHE_DIR=\"/tmp/wsp-cache\"`\n\n---\n\n## Common Issues\n\n### \"No API key found\" error\n\n**Symptoms:**\n```\nError: No API key found for serper\n```\n\n**Solutions:**\n1. Check `.env` exists in skill folder with `export VAR=value` format\n2. Keys auto-load from skill's `.env` since v2.2.0\n3. Or set in system environment: `export SERPER_API_KEY=\"...\"`\n4. Verify key format in config.json:\n ```json\n { \"serper\": { \"api_key\": \"your-key\" } }\n ```\n\n**Priority order:** config.json > .env > environment variable\n\n---\n\n### Getting empty results\n\n**Symptoms:**\n- Search returns no results\n- `\"results\": []` in JSON output\n\n**Solutions:**\n1. Check API key is valid (try the provider's web dashboard)\n2. Try a different provider with `-p`\n3. Some queries have no results (very niche topics)\n4. Check if provider is rate-limited\n5. Verify internet connectivity\n\n**Debug:**\n```bash\npython3 scripts/search.py -q \"test query\" --verbose\n```\n\n---\n\n### Rate limited\n\n**Symptoms:**\n```\nError: 429 Too Many Requests\nError: Rate limit exceeded\n```\n\n**Good news:** Since v2.2.5, automatic fallback kicks in! If one provider hits rate limits, the script automatically tries the next provider.\n\n**Solutions:**\n1. Wait for rate limit to reset (usually 1 hour or end of day)\n2. Use a different provider: `-p tavily` instead of `-p serper`\n3. Check free tier limits:\n - Serper: 2,500 free total\n - Tavily: 1,000/month free\n - Exa: 1,000/month free\n4. Upgrade to paid tier for higher limits\n5. Use SearXNG (self-hosted, unlimited)\n\n**Fallback info:** Response will include `routing.fallback_used: true` when fallback was used.\n\n---\n\n### SearXNG: \"403 Forbidden\"\n\n**Symptoms:**\n```\nError: 403 Forbidden\nError: JSON format not allowed\n```\n\n**Cause:** Most public SearXNG instances disable JSON API to prevent bot abuse.\n\n**Solution:** Self-host your own instance:\n```bash\ndocker run -d -p 8080:8080 searxng/searxng\n```\n\nThen enable JSON in `settings.yml`:\n```yaml\nsearch:\n formats:\n - html\n - json # Add this!\n```\n\nRestart the container and update your config:\n```json\n{\n \"searxng\": {\n \"instance_url\": \"http://localhost:8080\"\n }\n}\n```\n\n---\n\n### SearXNG: Slow responses\n\n**Symptoms:**\n- SearXNG takes 2-5 seconds\n- Other providers are faster\n\n**Explanation:** This is expected behavior. SearXNG queries 70+ upstream engines in parallel, which takes longer than direct API calls.\n\n**Trade-off:** Slower but privacy-preserving + multi-source + $0 cost.\n\n**Solutions:**\n1. Accept the trade-off for privacy benefits\n2. Limit engines for faster results:\n ```bash\n python3 scripts/search.py -p searxng -q \"query\" --engines \"google,bing\"\n ```\n3. Use SearXNG as fallback (put last in priority list)\n\n---\n\n### Auto-routing picks wrong provider\n\n**Symptoms:**\n- Query about research goes to Serper\n- Query about shopping goes to Tavily\n\n**Debug:**\n```bash\npython3 scripts/search.py --explain-routing -q \"your query\"\n```\n\nThis shows the full analysis:\n```json\n{\n \"query\": \"how much does iPhone 16 Pro cost\",\n \"routing_decision\": {\n \"provider\": \"serper\",\n \"confidence\": 0.68,\n \"reason\": \"moderate_confidence_match\"\n },\n \"scores\": {\"serper\": 7.0, \"tavily\": 0.0, \"exa\": 0.0},\n \"top_signals\": [\n {\"matched\": \"how much\", \"weight\": 4.0},\n {\"matched\": \"brand + product detected\", \"weight\": 3.0}\n ]\n}\n```\n\n**Solutions:**\n1. Override with explicit provider: `-p tavily`\n2. Rephrase query to be more explicit about intent\n3. Adjust `confidence_threshold` in config.json (default: 0.3)\n\n---\n\n### Config not loading\n\n**Symptoms:**\n- Changes to config.json not applied\n- Using default values instead\n\n**Solutions:**\n1. Check JSON syntax (use a validator)\n2. Ensure file is in skill directory: `/path/to/skills/web-search-plus/config.json`\n3. Check file permissions\n4. Run setup wizard to regenerate:\n ```bash\n python3 scripts/setup.py --reset\n ```\n\n**Validate JSON:**\n```bash\npython3 -m json.tool config.json\n```\n\n---\n\n### Python dependencies missing\n\n**Symptoms:**\n```\nModuleNotFoundError: No module named 'requests'\n```\n\n**Solution:**\n```bash\npip3 install requests\n```\n\nOr install all dependencies:\n```bash\npip3 install -r requirements.txt\n```\n\n---\n\n### Timeout errors\n\n**Symptoms:**\n```\nError: Request timeout after 30s\n```\n\n**Causes:**\n- Slow network connection\n- Provider API issues\n- SearXNG instance overloaded\n\n**Solutions:**\n1. Try again (temporary issue)\n2. Switch provider: `-p serper`\n3. Check your internet connection\n4. If using SearXNG, check instance health\n\n---\n\n### Duplicate results\n\n**Symptoms:**\n- Same result appears multiple times\n- Results overlap between providers\n\n**Solution:** This is expected when using auto-fallback or multiple providers. The skill doesn't deduplicate across providers.\n\nFor single-provider results:\n```bash\npython3 scripts/search.py -p serper -q \"query\"\n```\n\n---\n\n## Debug Mode\n\nFor detailed debugging:\n\n```bash\n# Verbose output\npython3 scripts/search.py -q \"query\" --verbose\n\n# Show routing decision\npython3 scripts/search.py -q \"query\" --explain-routing\n\n# Dry run (no actual search)\npython3 scripts/search.py -q \"query\" --dry-run\n\n# Test specific provider\npython3 scripts/search.py -p tavily -q \"query\" --verbose\n```\n\n---\n\n## Getting Help\n\n**Still stuck?**\n\n1. Check the full documentation in `README.md`\n2. Run the setup wizard: `python3 scripts/setup.py`\n3. Review `FAQ.md` for common questions\n4. Open an issue: https://github.com/robbyczgw-cla/web-search-plus/issues\n\nFile v2.8.5:config.example.json\n\n{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"$comment\": \"Web Search Plus configuration โ€” intelligent routing and provider settings\",\n \"defaults\": {\n \"provider\": \"serper\",\n \"max_results\": 5\n },\n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"provider_priority\": [\n \"serper\",\n \"tavily\",\n \"exa\",\n \"you\",\n \"searxng\"\n ],\n \"disabled_providers\": [],\n \"confidence_threshold\": 0.3,\n \"keyword_mappings\": {\n \"serper\": [\n \"price\",\n \"buy\",\n \"shop\",\n \"shopping\",\n \"cost\",\n \"deal\",\n \"sale\",\n \"purchase\",\n \"cheap\",\n \"expensive\",\n \"store\",\n \"product\",\n \"review\",\n \"specs\",\n \"specification\",\n \"where to buy\",\n \"near me\",\n \"local\",\n \"restaurant\",\n \"hotel\",\n \"weather\",\n \"news\",\n \"latest\",\n \"breaking\",\n \"map\",\n \"directions\",\n \"phone number\",\n \"preis\",\n \"kaufen\",\n \"bestellen\",\n \"gรผnstig\",\n \"billig\",\n \"teuer\",\n \"kosten\",\n \"angebot\",\n \"rabatt\",\n \"shop\",\n \"hรคndler\",\n \"geschรคft\",\n \"laden\",\n \"test\",\n \"bewertung\",\n \"technische daten\",\n \"spezifikationen\",\n \"wo kaufen\",\n \"in der nรคhe\",\n \"wetter\",\n \"nachrichten\",\n \"aktuell\",\n \"neu\"\n ],\n \"tavily\": [\n \"how does\",\n \"how to\",\n \"explain\",\n \"research\",\n \"what is\",\n \"why does\",\n \"analyze\",\n \"compare\",\n \"study\",\n \"academic\",\n \"detailed\",\n \"comprehensive\",\n \"in-depth\",\n \"understand\",\n \"learn\",\n \"tutorial\",\n \"guide\",\n \"overview\",\n \"history of\",\n \"background\",\n \"context\",\n \"implications\",\n \"pros and cons\",\n \"wie funktioniert\",\n \"erklรคrung\",\n \"erklรคren\",\n \"was ist\",\n \"warum\",\n \"analyse\",\n \"vergleich\",\n \"vergleichen\",\n \"studie\",\n \"verstehen\",\n \"lernen\",\n \"anleitung\",\n \"tutorial\",\n \"รผberblick\",\n \"hintergrund\",\n \"vor- und nachteile\"\n ],\n \"exa\": [\n \"similar to\",\n \"companies like\",\n \"find sites like\",\n \"alternatives to\",\n \"competitors\",\n \"startup\",\n \"github\",\n \"paper\",\n \"research paper\",\n \"arxiv\",\n \"pdf\",\n \"academic paper\",\n \"similar pages\",\n \"related sites\",\n \"who else\",\n \"other companies\",\n \"comparable to\",\n \"รคhnlich wie\",\n \"firmen wie\",\n \"alternativen zu\",\n \"konkurrenten\",\n \"vergleichbar mit\",\n \"andere unternehmen\"\n ],\n \"you\": [\n \"rag\",\n \"context for\",\n \"summarize\",\n \"brief\",\n \"quick overview\",\n \"tldr\",\n \"key points\",\n \"key facts\",\n \"main points\",\n \"main takeaways\",\n \"latest news\",\n \"latest updates\",\n \"current events\",\n \"current situation\",\n \"current status\",\n \"right now\",\n \"as of today\",\n \"up to date\",\n \"real time\",\n \"what's happening\",\n \"what's the latest\",\n \"updates on\",\n \"status of\",\n \"zusammenfassung\",\n \"aktuelle nachrichten\",\n \"neueste updates\"\n ],\n \"searxng\": [\n \"private\",\n \"privately\",\n \"anonymous\",\n \"anonymously\",\n \"without tracking\",\n \"no tracking\",\n \"privacy\",\n \"privacy-focused\",\n \"privacy-first\",\n \"duckduckgo alternative\",\n \"private search\",\n \"aggregate results\",\n \"multiple sources\",\n \"diverse results\",\n \"diverse perspectives\",\n \"meta search\",\n \"all engines\",\n \"free search\",\n \"no api cost\",\n \"self-hosted search\",\n \"zero cost\",\n \"privat\",\n \"anonym\",\n \"ohne tracking\",\n \"datenschutz\",\n \"verschiedene quellen\",\n \"aus mehreren quellen\",\n \"alle suchmaschinen\",\n \"kostenlose suche\",\n \"keine api kosten\"\n ]\n }\n },\n \"serper\": {\n \"country\": \"us\",\n \"language\": \"en\",\n \"type\": \"search\",\n \"autocorrect\": true,\n \"include_images\": false\n },\n \"tavily\": {\n \"depth\": \"advanced\",\n \"topic\": \"general\",\n \"max_results\": 8\n },\n \"exa\": {\n \"type\": \"neural\",\n \"category\": null,\n \"include_domains\": [],\n \"exclude_domains\": []\n },\n \"you\": {\n \"country\": \"US\",\n \"language\": \"en\",\n \"safesearch\": \"moderate\",\n \"include_news\": true\n },\n \"searxng\": {\n \"$comment\": \"SearXNG requires a self-hosted instance. No API key needed, just your instance URL.\",\n \"instance_url\": null,\n \"safesearch\": 0,\n \"engines\": null,\n \"language\": \"en\"\n }\n}\n\nFile v2.8.5:package.json\n\n{\n \"name\": \"@openclaw/web-search-plus\",\n \"version\": \"2.8.5\",\n \"description\": \"Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis (intent classification, linguistic patterns, URL/brand detection) to automatically select between Serper (Google), Tavily (Research), Exa (Neural), and You.com (RAG/Real-time) with confidence scoring.\",\n \"keywords\": [\n \"openclaw\",\n \"skill\",\n \"search\",\n \"web-search\",\n \"serper\",\n \"tavily\",\n \"exa\",\n \"you\",\n \"you.com\",\n \"google-search\",\n \"research\",\n \"semantic-search\",\n \"ai-agent\",\n \"auto-routing\",\n \"smart-routing\",\n \"multi-provider\",\n \"shopping\",\n \"product-search\",\n \"similar-sites\",\n \"company-discovery\",\n \"rag\",\n \"real-time\",\n \"free-tier\",\n \"api-aggregator\"\n ],\n \"author\": \"robbyczgw-cla\",\n \"license\": \"MIT\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/robbyczgw-cla/web-search-plus.git\"\n },\n \"homepage\": \"https://clawhub.ai/robbyczgw-cla/web-search-plus\",\n \"bugs\": {\n \"url\": \"https://github.com/robbyczgw-cla/web-search-plus/issues\"\n },\n \"openclaw\": {\n \"skill\": true,\n \"triggers\": [\n \"search\",\n \"find\",\n \"look up\",\n \"research\"\n ],\n \"capabilities\": [\n \"web-search\",\n \"image-search\",\n \"semantic-search\",\n \"multi-provider\"\n ],\n \"providers\": [\n \"serper\",\n \"tavily\",\n \"exa\",\n \"you\"\n ],\n \"requirements\": {\n \"bins\": [\"python3\", \"bash\"],\n \"env\": {\n \"SERPER_API_KEY\": \"optional\",\n \"TAVILY_API_KEY\": \"optional\",\n \"EXA_API_KEY\": \"optional\",\n \"YOU_API_KEY\": \"optional\",\n \"SEARXNG_INSTANCE_URL\": \"optional\"\n }\n }\n },\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"scripts/\",\n \".env.example\"\n ]\n}\n\nArchive v2.8.4: 11 files, 58352 bytes\n\nFiles: CHANGELOG.md (18072b), config.example.json (4972b), FAQ.md (9360b), package.json (1801b), README.md (23073b), scripts/search.py (88415b), scripts/setup.py (18486b), SKILL.md (9693b), test-auto-routing.sh (555b), TROUBLESHOOTING.md (6664b), _meta.json (134b)\n\nFile v2.8.4:SKILL.md\n\n---\nname: web-search-plus\nversion: 2.8.1\ndescription: Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neural), Perplexity (AI Answers), You.com (RAG/Real-time), and SearXNG (Privacy/Self-hosted) with confidence scoring.\ntags: [search, web-search, serper, tavily, exa, perplexity, you, searxng, google, research, semantic-search, auto-routing, multi-provider, shopping, rag, free-tier, privacy, self-hosted, kilo]\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"bash\"],\"env\":{\"SERPER_API_KEY\":\"optional\",\"TAVILY_API_KEY\":\"optional\",\"EXA_API_KEY\":\"optional\",\"YOU_API_KEY\":\"optional\",\"SEARXNG_INSTANCE_URL\":\"optional\",\"KILOCODE_API_KEY\":\"optional โ€” required for Perplexity provider (via Kilo Gateway)\"},\"note\":\"Only ONE provider key needed. All are optional.\"}}}\n---\n\n# Web Search Plus\n\n**Stop choosing search providers. Let the skill do it for you.**\n\nThis skill connects you to 6 search providers (Serper, Tavily, Exa, Perplexity, You.com, SearXNG) and automatically picks the best one for each query. Shopping question? โ†’ Google results. Research question? โ†’ Deep research engine. Need a direct answer? โ†’ AI-synthesized with citations. Want privacy? โ†’ Self-hosted option.\n\n---\n\n## โœจ What Makes This Different?\n\n- **Just search** โ€” No need to think about which provider to use\n- **Smart routing** โ€” Analyzes your query and picks the best provider automatically\n- **6 providers, 1 interface** โ€” Google results, research engines, neural search, AI answers with citations, RAG-optimized, and privacy-first all in one\n- **Works with just 1 key** โ€” Start with any single provider, add more later\n- **Free options available** โ€” SearXNG is completely free (self-hosted)\n\n---\n\n## ๐Ÿš€ Quick Start\n\n```bash\n# Interactive setup (recommended for first run)\npython3 scripts/setup.py\n\n# Or manual: copy config and add your keys\ncp config.example.json config.json\n```\n\nThe wizard explains each provider, collects API keys, and configures defaults.\n\n---\n\n## ๐Ÿ”‘ API Keys\n\nYou only need **ONE** key to get started. Add more providers later for better coverage.\n\n| Provider | Free Tier | Best For | Sign Up |\n|----------|-----------|----------|---------|\n| **Serper** | 2,500/mo | Shopping, prices, local, news | [serper.dev](https://serper.dev) |\n| **Tavily** | 1,000/mo | Research, explanations, academic | [tavily.com](https://tavily.com) |\n| **Exa** | 1,000/mo | \"Similar to X\", startups, papers | [exa.ai](https://exa.ai) |\n| **Perplexity** | Via Kilo | Direct answers with citations | [kilo.ai](https://kilo.ai) |\n| **You.com** | Limited | Real-time info, AI/RAG context | [api.you.com](https://api.you.com) |\n| **SearXNG** | **FREE** โœ… | Privacy, multi-source, $0 cost | Self-hosted |\n\n**Setting your keys:**\n\n```bash\n# Option A: .env file (recommended)\nexport SERPER_API_KEY=\"your-key\"\nexport TAVILY_API_KEY=\"your-key\"\n\n# Option B: config.json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## ๐ŸŽฏ When to Use Which Provider\n\n| I want to... | Provider | Example Query |\n|--------------|----------|---------------|\n| Find product prices | **Serper** | \"iPhone 16 Pro Max price\" |\n| Find restaurants/stores nearby | **Serper** | \"best pizza near me\" |\n| Understand how something works | **Tavily** | \"how does HTTPS encryption work\" |\n| Do deep research | **Tavily** | \"climate change research 2024\" |\n| Find companies like X | **Exa** | \"startups similar to Notion\" |\n| Find research papers | **Exa** | \"transformer architecture papers\" |\n| Get a direct answer with sources | **Perplexity** | \"events in Berlin this weekend\" |\n| Know the current status of something | **Perplexity** | \"what is the status of Ethereum upgrades\" |\n| Get real-time info | **You.com** | \"latest AI regulation news\" |\n| Search without being tracked | **SearXNG** | anything, privately |\n\n**Pro tip:** Just search normally! Auto-routing handles most queries correctly. Override with `-p provider` when needed.\n\n---\n\n## ๐Ÿง  How Auto-Routing Works\n\nThe skill looks at your query and picks the best provider:\n\n```bash\n\"iPhone 16 price\" โ†’ Serper (shopping keywords)\n\"how does quantum computing work\" โ†’ Tavily (research question)\n\"companies like stripe.com\" โ†’ Exa (URL detected, similarity)\n\"events in Graz this weekend\" โ†’ Perplexity (local + direct answer)\n\"latest news on AI\" โ†’ You.com (real-time intent)\n\"search privately\" โ†’ SearXNG (privacy keywords)\n```\n\n**What if it picks wrong?** Override it: `python3 scripts/search.py -p tavily -q \"your query\"`\n\n**Debug routing:** `python3 scripts/search.py --explain-routing -q \"your query\"`\n\n---\n\n## ๐Ÿ“– Usage Examples\n\n### Let Auto-Routing Choose (Recommended)\n\n```bash\npython3 scripts/search.py -q \"Tesla Model 3 price\"\npython3 scripts/search.py -q \"explain machine learning\"\npython3 scripts/search.py -q \"startups like Figma\"\n```\n\n### Force a Specific Provider\n\n```bash\npython3 scripts/search.py -p serper -q \"weather Berlin\"\npython3 scripts/search.py -p tavily -q \"quantum computing\" --depth advanced\npython3 scripts/search.py -p exa --similar-url \"https://stripe.com\" --category company\npython3 scripts/search.py -p you -q \"breaking tech news\" --include-news\npython3 scripts/search.py -p searxng -q \"linux distros\" --engines \"google,bing\"\n```\n\n---\n\n## โš™ Configuration\n\n```json\n{\n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"confidence_threshold\": 0.3,\n \"disabled_providers\": []\n },\n \"serper\": {\"country\": \"us\", \"language\": \"en\"},\n \"tavily\": {\"depth\": \"advanced\"},\n \"exa\": {\"type\": \"neural\"},\n \"you\": {\"country\": \"US\", \"include_news\": true},\n \"searxng\": {\"instance_url\": \"https://your-instance.example.com\"}\n}\n```\n\n---\n\n## ๐Ÿ“Š Provider Comparison\n\n| Feature | Serper | Tavily | Exa | Perplexity | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:----------:|:-------:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšก | โšกโšกโšก | โšกโšก |\n| Direct Answers | โœ— | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— |\n| Citations | โœ— | โœ— | โœ— | โœ“ | โœ— | โœ— |\n| Factual Accuracy | โญโญโญ | โญโญโญ | โญโญ | โญโญโญ | โญโญโญ | โญโญโญ |\n| Semantic Understanding | โญ | โญโญ | โญโญโญ | โญโญโญ | โญโญ | โญ |\n| Full Page Content | โœ— | โœ“ | โœ“ | โœ“ | โœ“ | โœ— |\n| Shopping/Local | โœ“ | โœ— | โœ— | โœ— | โœ— | โœ“ |\n| Find Similar Pages | โœ— | โœ— | โœ“ | โœ— | โœ— | โœ— |\n| RAG-Optimized | โœ— | โœ“ | โœ— | โœ— | โœ“โœ“ | โœ— |\n| Privacy-First | โœ— | โœ— | โœ— | โœ— | โœ— | โœ“โœ“ |\n| API Cost | $$ | $$ | $$ | Via Kilo | $ | **FREE** |\n\n---\n\n## โ“ Common Questions\n\n### Do I need API keys for all providers?\n**No.** You only need keys for providers you want to use. Start with one (Serper recommended), add more later.\n\n### Which provider should I start with?\n**Serper** โ€” fastest, cheapest, largest free tier (2,500 queries/month), and handles most queries well.\n\n### What if I run out of free queries?\nThe skill automatically falls back to your other configured providers. Or switch to SearXNG (unlimited, self-hosted).\n\n### How much does this cost?\n- **Free tiers:** 2,500 (Serper) + 1,000 (Tavily) + 1,000 (Exa) = 4,500+ free searches/month\n- **SearXNG:** Completely free (just ~$5/mo if you self-host on a VPS)\n- **Paid plans:** Start around $10-50/month depending on provider\n\n### Is SearXNG really private?\n**Yes, if self-hosted.** You control the server, no tracking, no profiling. Public instances depend on the operator's policy.\n\n### How do I set up SearXNG?\n```bash\n# Docker (5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n```\nThen enable JSON API in `settings.yml`. See [docs.searxng.org](https://docs.searxng.org/admin/installation.html).\n\n### Why did it route my query to the \"wrong\" provider?\nSometimes queries are ambiguous. Use `--explain-routing` to see why, then override with `-p provider` if needed.\n\n---\n\n## ๐Ÿ”„ Automatic Fallback\n\nIf one provider fails (rate limit, timeout, error), the skill automatically tries the next provider. You'll see `routing.fallback_used: true` in the response when this happens.\n\n---\n\n## ๐Ÿ“ค Output Format\n\n```json\n{\n \"provider\": \"serper\",\n \"query\": \"iPhone 16 price\",\n \"results\": [{\"title\": \"...\", \"url\": \"...\", \"snippet\": \"...\", \"score\": 0.95}],\n \"routing\": {\n \"auto_routed\": true,\n \"provider\": \"serper\",\n \"confidence\": 0.78,\n \"confidence_level\": \"high\"\n }\n}\n```\n\n---\n\n## โš  Important Note\n\n**Tavily, Serper, and Exa are NOT core OpenClaw providers.**\n\nโŒ Don't modify `~/.openclaw/openclaw.json` for these \nโœ… Use this skill's scripts โ€” keys auto-load from `.env`\n\n---\n\n## ๐Ÿ”’ Security\n\n**SearXNG SSRF Protection:** The SearXNG instance URL is validated with defense-in-depth:\n- Enforces `http`/`https` schemes only\n- Blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal)\n- Resolves hostnames and blocks private/internal IPs (loopback, RFC1918, link-local, reserved)\n- Operators who intentionally self-host on private networks can set `SEARXNG_ALLOW_PRIVATE=1`\n\n## ๐Ÿ“š More Documentation\n\n- **[FAQ.md](FAQ.md)** โ€” Detailed answers to more questions\n- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** โ€” Fix common errors\n- **[README.md](README.md)** โ€” Full technical reference\n\n---\n\n## ๐Ÿ”— Quick Links\n\n- [Serper](https://serper.dev) โ€” Google Search API\n- [Tavily](https://tavily.com) โ€” AI Research Search\n- [Exa](https://exa.ai) โ€” Neural Search\n- [Perplexity](https://www.perplexity.ai) โ€” AI-Synthesized Answers (via [Kilo Gateway](https://kilo.ai))\n- [You.com](https://api.you.com) โ€” RAG/Real-time Search\n- [SearXNG](https://docs.searxng.org) โ€” Privacy-First Meta-Search\n\nFile v2.8.4:README.md\n\n# Web Search Plus\n\n> Unified multi-provider web search with **Intelligent Auto-Routing** โ€” uses multi-signal analysis to automatically select between **Serper**, **Tavily**, **Exa**, **You.com**, and **SearXNG** with confidence scoring.\n\n[![ClawHub](https://img.shields.io/badge/ClawHub-web--search--plus-blue)](https://clawhub.ai)\n[![Version](https://img.shields.io/badge/version-2.7.0-green)](https://clawhub.ai)\n[![GitHub](https://img.shields.io/badge/GitHub-web--search--plus-blue)](https://github.com/robbyczgw-cla/web-search-plus)\n\n---\n\n## ๐Ÿง  Features (v2.7.0)\n\n**Intelligent Multi-Signal Routing** โ€” The skill uses sophisticated query analysis:\n\n- **Intent Classification**: Shopping vs Research vs Discovery vs RAG/Real-time vs Privacy\n- **Linguistic Patterns**: \"how much\" (price) vs \"how does\" (research) vs \"privately\" (privacy)\n- **Entity Detection**: Product+brand combos, URLs, domains\n- **Complexity Analysis**: Long queries favor research providers\n- **Confidence Scoring**: Know how reliable the routing decision is\n\n```bash\npython3 scripts/search.py -q \"how much does iPhone 16 cost\" # โ†’ Serper (68% confidence)\npython3 scripts/search.py -q \"how does quantum entanglement work\" # โ†’ Tavily (86% HIGH)\npython3 scripts/search.py -q \"startups similar to Notion\" # โ†’ Exa (76% HIGH)\npython3 scripts/search.py -q \"companies like stripe.com\" # โ†’ Exa (100% HIGH - URL detected)\npython3 scripts/search.py -q \"summarize key points on AI\" # โ†’ You.com (68% MEDIUM - RAG intent)\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG (74% HIGH - privacy intent)\n```\n\n---\n\n## ๐Ÿ” When to Use Which Provider\n\n### Built-in Brave Search (OpenClaw default)\n- โœ… General web searches\n- โœ… Privacy-focused\n- โœ… Quick lookups\n- โœ… Default fallback\n\n### Serper (Google Results)\n- ๐Ÿ› **Product specs, prices, shopping**\n- ๐Ÿ“ **Local businesses, places**\n- ๐ŸŽฏ **\"Google it\" - explicit Google results**\n- ๐Ÿ“ฐ **Shopping/images needed**\n- ๐Ÿ† **Knowledge Graph data**\n\n### Tavily (AI-Optimized Research)\n- ๐Ÿ“š **Research questions, deep dives**\n- ๐Ÿ”ฌ **Complex multi-part queries**\n- ๐Ÿ“„ **Need full page content** (not just snippets)\n- ๐ŸŽ“ **Academic/technical research**\n- ๐Ÿ”’ **Domain filtering** (trusted sources)\n\n### Exa (Neural Semantic Search)\n- ๐Ÿ”— **Find similar pages**\n- ๐Ÿข **Company/startup discovery**\n- ๐Ÿ“ **Research papers**\n- ๐Ÿ’ป **GitHub projects**\n- ๐Ÿ“… **Date-specific content**\n\n### You.com (RAG/Real-time)\n- ๐Ÿค– **RAG applications** (LLM-ready snippets)\n- ๐Ÿ“ฐ **Combined web + news** (single API call)\n- โšก **Real-time information** (current events)\n- ๐Ÿ“‹ **Summarization context** (\"What's the latest...\")\n- ๐Ÿ”„ **Live crawling** (full page content on demand)\n\n### SearXNG (Privacy-First/Self-Hosted)\n- ๐Ÿ”’ **Privacy-preserving search** (no tracking)\n- ๐ŸŒ **Multi-source aggregation** (70+ engines)\n- ๐Ÿ’ฐ **$0 API cost** (self-hosted)\n- ๐ŸŽฏ **Diverse perspectives** (results from multiple engines)\n- ๐Ÿ  **Self-hosted environments** (full control)\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Smart Auto-Routing](#smart-auto-routing)\n- [Configuration Guide](#configuration-guide)\n- [Provider Deep Dives](#provider-deep-dives)\n- [Usage Examples](#usage-examples)\n- [Workflow Examples](#workflow-examples)\n- [Optimization Tips](#optimization-tips)\n- [FAQ & Troubleshooting](#faq--troubleshooting)\n- [API Reference](#api-reference)\n\n---\n\n## Quick Start\n\n### Option A: Interactive Setup (Recommended)\n\n```bash\n# Run the setup wizard - it guides you through everything\npython3 scripts/setup.py\n```\n\nThe wizard explains each provider, collects your API keys, and creates `config.json` automatically.\n\n### Option B: Manual Setup\n\n```bash\n# 1. Set up at least one API key (or SearXNG instance)\nexport SERPER_API_KEY=\"your-key\" # https://serper.dev\nexport TAVILY_API_KEY=\"your-key\" # https://tavily.com\nexport EXA_API_KEY=\"your-key\" # https://exa.ai\nexport YOU_API_KEY=\"your-key\" # https://api.you.com\nexport SEARXNG_INSTANCE_URL=\"https://your-instance.example.com\" # Self-hosted\n\n# 2. Run a search (auto-routed!)\npython3 scripts/search.py -q \"best laptop 2024\"\n```\n\n### Run a Search\n\n```bash\n# Auto-routed to best provider\npython3 scripts/search.py -q \"best laptop 2024\"\n\n# Or specify a provider explicitly\npython3 scripts/search.py -p serper -q \"iPhone 16 specs\"\npython3 scripts/search.py -p tavily -q \"quantum computing explained\" --depth advanced\npython3 scripts/search.py -p exa -q \"AI startups 2024\" --category company\n```\n\n---\n\n## Smart Auto-Routing\n\n### How It Works\n\nWhen you don't specify a provider, the skill analyzes your query and routes it to the best provider:\n\n| Query Contains | Routes To | Example |\n|---------------|-----------|---------|\n| \"price\", \"buy\", \"shop\", \"cost\" | **Serper** | \"iPhone 16 price\" |\n| \"near me\", \"restaurant\", \"hotel\" | **Serper** | \"pizza near me\" |\n| \"weather\", \"news\", \"latest\" | **Serper** | \"weather Berlin\" |\n| \"how does\", \"explain\", \"what is\" | **Tavily** | \"how does TCP work\" |\n| \"research\", \"study\", \"analyze\" | **Tavily** | \"climate research\" |\n| \"tutorial\", \"guide\", \"learn\" | **Tavily** | \"python tutorial\" |\n| \"similar to\", \"companies like\" | **Exa** | \"companies like Stripe\" |\n| \"startup\", \"Series A\" | **Exa** | \"AI startups Series A\" |\n| \"github\", \"research paper\" | **Exa** | \"LLM papers arxiv\" |\n| \"private\", \"anonymous\", \"no tracking\" | **SearXNG** | \"search privately\" |\n| \"multiple sources\", \"aggregate\" | **SearXNG** | \"results from all engines\" |\n\n### Examples\n\n```bash\n# These are all auto-routed to the optimal provider:\npython3 scripts/search.py -q \"MacBook Pro M3 price\" # โ†’ Serper\npython3 scripts/search.py -q \"how does HTTPS work\" # โ†’ Tavily\npython3 scripts/search.py -q \"startups like Notion\" # โ†’ Exa\npython3 scripts/search.py -q \"best sushi restaurant near me\" # โ†’ Serper\npython3 scripts/search.py -q \"explain attention mechanism\" # โ†’ Tavily\npython3 scripts/search.py -q \"alternatives to Figma\" # โ†’ Exa\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG\n```\n\n### Result Caching (NEW in v2.7.0!)\n\nSearch results are **automatically cached** for 1 hour to save API costs:\n\n```bash\n# First request: fetches from API ($)\npython3 scripts/search.py -q \"AI startups 2024\"\n\n# Second request: uses cache (FREE!)\npython3 scripts/search.py -q \"AI startups 2024\"\n# Output includes: \"cached\": true\n\n# Bypass cache (force fresh results)\npython3 scripts/search.py -q \"AI startups 2024\" --no-cache\n\n# View cache stats\npython3 scripts/search.py --cache-stats\n\n# Clear all cached results\npython3 scripts/search.py --clear-cache\n\n# Custom TTL (in seconds, default: 3600 = 1 hour)\npython3 scripts/search.py -q \"query\" --cache-ttl 7200\n```\n\n**Cache location:** `.cache/` in skill directory (override with `WSP_CACHE_DIR` environment variable)\n\n### Debug Auto-Routing\n\nSee exactly why a provider was selected:\n\n```bash\npython3 scripts/search.py --explain-routing -q \"best laptop to buy\"\n```\n\nOutput:\n```json\n{\n \"query\": \"best laptop to buy\",\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=2)\",\n \"matched_keywords\": [\"buy\", \"best\"],\n \"available_providers\": [\"serper\", \"tavily\", \"exa\"]\n}\n```\n\n### Routing Info in Results\n\nEvery search result includes routing information:\n\n```json\n{\n \"provider\": \"serper\",\n \"query\": \"iPhone 16 price\",\n \"results\": [...],\n \"routing\": {\n \"auto_routed\": true,\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=1)\",\n \"matched_keywords\": [\"price\"]\n }\n}\n```\n\n---\n\n## Configuration Guide\n\n### Environment Variables\n\nCreate a `.env` file or set these in your shell:\n\n```bash\n# Required: Set at least one\nexport SERPER_API_KEY=\"your-serper-key\"\nexport TAVILY_API_KEY=\"your-tavily-key\"\nexport EXA_API_KEY=\"your-exa-key\"\n```\n\n### Config File (config.json)\n\nThe `config.json` file lets you customize auto-routing and provider defaults:\n\n```json\n{\n \"defaults\": {\n \"provider\": \"serper\",\n \"max_results\": 5\n },\n \n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"provider_priority\": [\"serper\", \"tavily\", \"exa\"],\n \"disabled_providers\": [],\n \"keyword_mappings\": {\n \"serper\": [\"price\", \"buy\", \"shop\", \"cost\", \"deal\", \"near me\", \"weather\"],\n \"tavily\": [\"how does\", \"explain\", \"research\", \"what is\", \"tutorial\"],\n \"exa\": [\"similar to\", \"companies like\", \"alternatives\", \"startup\", \"github\"]\n }\n },\n \n \"serper\": {\n \"country\": \"us\",\n \"language\": \"en\"\n },\n \n \"tavily\": {\n \"depth\": \"basic\",\n \"topic\": \"general\"\n },\n \n \"exa\": {\n \"type\": \"neural\"\n }\n}\n```\n\n### Configuration Examples\n\n#### Example 1: Disable Exa (Only Use Serper + Tavily)\n\n```json\n{\n \"auto_routing\": {\n \"disabled_providers\": [\"exa\"]\n }\n}\n```\n\n#### Example 2: Make Tavily the Default\n\n```json\n{\n \"auto_routing\": {\n \"fallback_provider\": \"tavily\"\n }\n}\n```\n\n#### Example 3: Add Custom Keywords\n\n```json\n{\n \"auto_routing\": {\n \"keyword_mappings\": {\n \"serper\": [\n \"price\", \"buy\", \"shop\", \"amazon\", \"ebay\", \"walmart\",\n \"deal\", \"discount\", \"coupon\", \"sale\", \"cheap\"\n ],\n \"tavily\": [\n \"how does\", \"explain\", \"research\", \"what is\",\n \"coursera\", \"udemy\", \"learn\", \"course\", \"certification\"\n ],\n \"exa\": [\n \"similar to\", \"companies like\", \"competitors\",\n \"YC company\", \"funded startup\", \"Series A\", \"Series B\"\n ]\n }\n }\n}\n```\n\n#### Example 4: German Locale for Serper\n\n```json\n{\n \"serper\": {\n \"country\": \"de\",\n \"language\": \"de\"\n }\n}\n```\n\n#### Example 5: Disable Auto-Routing\n\n```json\n{\n \"auto_routing\": {\n \"enabled\": false\n },\n \"defaults\": {\n \"provider\": \"serper\"\n }\n}\n```\n\n#### Example 6: Research-Heavy Config\n\n```json\n{\n \"auto_routing\": {\n \"fallback_provider\": \"tavily\",\n \"provider_priority\": [\"tavily\", \"serper\", \"exa\"]\n },\n \"tavily\": {\n \"depth\": \"advanced\",\n \"include_raw_content\": true\n }\n}\n```\n\n---\n\n## Provider Deep Dives\n\n### Serper (Google Search API)\n\n**What it is:** Direct access to Google Search results via API โ€” the same results you'd see on google.com.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐ŸŽฏ **Accuracy** | Google's search quality, knowledge graph, featured snippets |\n| ๐Ÿ›’ **Shopping** | Product prices, reviews, shopping results |\n| ๐Ÿ“ **Local** | Business listings, maps, places |\n| ๐Ÿ“ฐ **News** | Real-time news with Google News integration |\n| ๐Ÿ–ผ **Images** | Google Images search |\n| โšก **Speed** | Fastest response times (~200-400ms) |\n\n#### Best Use Cases\n- โœ… Product specifications and comparisons\n- โœ… Shopping and price lookups\n- โœ… Local business searches (\"restaurants near me\")\n- โœ… Quick factual queries (weather, conversions, definitions)\n- โœ… News headlines and current events\n- โœ… Image searches\n- โœ… When you need \"what Google shows\"\n\n#### Getting Your API Key\n1. Go to [serper.dev](https://serper.dev)\n2. Sign up with email or Google\n3. Copy your API key from the dashboard\n4. Set `SERPER_API_KEY` environment variable\n\n---\n\n### Tavily (Research Search)\n\n**What it is:** AI-optimized search engine built for research and RAG applications โ€” returns synthesized answers plus full content.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿ“š **Research Quality** | Optimized for comprehensive, accurate research |\n| ๐Ÿ’ฌ **AI Answers** | Returns synthesized answers, not just links |\n| ๐Ÿ“„ **Full Content** | Can return complete page content (raw_content) |\n| ๐ŸŽฏ **Domain Filtering** | Include/exclude specific domains |\n| ๐Ÿ”ฌ **Deep Mode** | Advanced search for thorough research |\n| ๐Ÿ“ฐ **Topic Modes** | Specialized for general vs news content |\n\n#### Best Use Cases\n- โœ… Research questions requiring synthesized answers\n- โœ… Academic or technical deep dives\n- โœ… When you need actual page content (not just snippets)\n- โœ… Multi-source information comparison\n- โœ… Domain-specific research (filter to authoritative sources)\n- โœ… News research with context\n- โœ… RAG/LLM applications\n\n#### Getting Your API Key\n1. Go to [tavily.com](https://tavily.com)\n2. Sign up and verify email\n3. Navigate to API Keys section\n4. Generate and copy your key\n5. Set `TAVILY_API_KEY` environment variable\n\n---\n\n### Exa (Neural Search)\n\n**What it is:** Neural/semantic search engine that understands meaning, not just keywords โ€” finds conceptually similar content.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿง  **Semantic Understanding** | Finds results by meaning, not keywords |\n| ๐Ÿ”— **Similar Pages** | Find pages similar to a reference URL |\n| ๐Ÿข **Company Discovery** | Excellent for finding startups, companies |\n| ๐Ÿ“‘ **Category Filters** | Filter by type (company, paper, tweet, etc.) |\n| ๐Ÿ“… **Date Filtering** | Precise date range searches |\n| ๐ŸŽ“ **Academic** | Great for research papers and technical content |\n\n#### Best Use Cases\n- โœ… Conceptual queries (\"companies building X\")\n- โœ… Finding similar companies or pages\n- โœ… Startup and company discovery\n- โœ… Research paper discovery\n- โœ… Finding GitHub projects\n- โœ… Date-filtered searches for recent content\n- โœ… When keyword matching fails\n\n#### Getting Your API Key\n1. Go to [exa.ai](https://exa.ai)\n2. Sign up with email or Google\n3. Navigate to API section in dashboard\n4. Copy your API key\n5. Set `EXA_API_KEY` environment variable\n\n---\n\n### SearXNG (Privacy-First Meta-Search)\n\n**What it is:** Open-source, self-hosted meta-search engine that aggregates results from 70+ search engines without tracking.\n\n#### Strengths\n| Strength | Description |\n|----------|-------------|\n| ๐Ÿ”’ **Privacy-First** | No tracking, no profiling, no data collection |\n| ๐ŸŒ **Multi-Engine** | Aggregates Google, Bing, DuckDuckGo, and 70+ more |\n| ๐Ÿ’ฐ **Free** | $0 API cost (self-hosted, unlimited queries) |\n| ๐ŸŽฏ **Diverse Results** | Get perspectives from multiple search engines |\n| โš™ **Customizable** | Choose which engines to use, SafeSearch, language |\n| ๐Ÿ  **Self-Hosted** | Full control over your search infrastructure |\n\n#### Best Use Cases\n- โœ… Privacy-sensitive searches (no tracking)\n- โœ… When you want diverse results from multiple engines\n- โœ… Budget-conscious (no API fees)\n- โœ… Self-hosted/air-gapped environments\n- โœ… Fallback when paid APIs are rate-limited\n- โœ… When \"aggregate everything\" is the goal\n\n#### Setting Up Your Instance\n```bash\n# Docker (recommended, 5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n\n# Enable JSON API in settings.yml:\n# search:\n# formats: [html, json]\n```\n\n1. See [docs.searxng.org](https://docs.searxng.org/admin/installation.html)\n2. Deploy via Docker, pip, or your preferred method\n3. Enable JSON format in `settings.yml`\n4. Set `SEARXNG_INSTANCE_URL` environment variable\n\n---\n\n## Usage Examples\n\n### Auto-Routed Searches (Recommended)\n\n```bash\n# Just search โ€” the skill picks the best provider\npython3 scripts/search.py -q \"Tesla Model 3 price\"\npython3 scripts/search.py -q \"how do neural networks learn\"\npython3 scripts/search.py -q \"YC startups like Stripe\"\npython3 scripts/search.py -q \"search privately without tracking\"\n```\n\n### Serper Options\n\n```bash\n# Different search types\npython3 scripts/search.py -p serper -q \"gaming monitor\" --type shopping\npython3 scripts/search.py -p serper -q \"coffee shop\" --type places\npython3 scripts/search.py -p serper -q \"AI news\" --type news\n\n# With time filter\npython3 scripts/search.py -p serper -q \"OpenAI news\" --time-range day\n\n# Include images\npython3 scripts/search.py -p serper -q \"iPhone 16 Pro\" --images\n\n# Different locale\npython3 scripts/search.py -p serper -q \"Wetter Wien\" --country at --language de\n```\n\n### Tavily Options\n\n```bash\n# Deep research mode\npython3 scripts/search.py -p tavily -q \"quantum computing applications\" --depth advanced\n\n# With full page content\npython3 scripts/search.py -p tavily -q \"transformer architecture\" --raw-content\n\n# Domain filtering\npython3 scripts/search.py -p tavily -q \"AI research\" --include-domains arxiv.org nature.com\n```\n\n### Exa Options\n\n```bash\n# Category filtering\npython3 scripts/search.py -p exa -q \"AI startups Series A\" --category company\npython3 scripts/search.py -p exa -q \"attention mechanism\" --category \"research paper\"\n\n# Date filtering\npython3 scripts/search.py -p exa -q \"YC companies\" --start-date 2024-01-01\n\n# Find similar pages\npython3 scripts/search.py -p exa --similar-url \"https://stripe.com\" --category company\n```\n\n### SearXNG Options\n\n```bash\n# Basic search\npython3 scripts/search.py -p searxng -q \"linux distros\"\n\n# Specific engines only\npython3 scripts/search.py -p searxng -q \"AI news\" --engines \"google,bing,duckduckgo\"\n\n# SafeSearch (0=off, 1=moderate, 2=strict)\npython3 scripts/search.py -p searxng -q \"privacy tools\" --searxng-safesearch 2\n\n# With time filter\npython3 scripts/search.py -p searxng -q \"open source projects\" --time-range week\n\n# Custom instance URL\npython3 scripts/search.py -p searxng -q \"test\" --searxng-url \"http://localhost:8080\"\n```\n\n---\n\n## Workflow Examples\n\n### ๐Ÿ›’ Product Research Workflow\n\n```bash\n# Step 1: Get product specs (auto-routed to Serper)\npython3 scripts/search.py -q \"MacBook Pro M3 Max specs\"\n\n# Step 2: Check prices (auto-routed to Serper)\npython3 scripts/search.py -q \"MacBook Pro M3 Max price comparison\"\n\n# Step 3: In-depth reviews (auto-routed to Tavily)\npython3 scripts/search.py -q \"detailed MacBook Pro M3 Max review\"\n```\n\n### ๐Ÿ“š Academic Research Workflow\n\n```bash\n# Step 1: Understand the topic (auto-routed to Tavily)\npython3 scripts/search.py -q \"explain transformer architecture in deep learning\"\n\n# Step 2: Find recent papers (Exa)\npython3 scripts/search.py -p exa -q \"transformer improvements\" --category \"research paper\" --start-date 2024-01-01\n\n# Step 3: Find implementations (Exa)\npython3 scripts/search.py -p exa -q \"transformer implementation\" --category github\n```\n\n### ๐Ÿข Competitive Analysis Workflow\n\n```bash\n# Step 1: Find competitors (auto-routed to Exa)\npython3 scripts/search.py -q \"companies like Notion\"\n\n# Step 2: Find similar products (Exa)\npython3 scripts/search.py -p exa --similar-url \"https://notion.so\" --category company\n\n# Step 3: Deep dive comparison (Tavily)\npython3 scripts/search.py -p tavily -q \"Notion vs Coda comparison\" --depth advanced\n```\n\n---\n\n## Optimization Tips\n\n### Cost Optimization\n\n| Tip | Savings |\n|-----|---------|\n| Use SearXNG for routine queries | **$0 API cost** |\n| Use auto-routing (defaults to Serper, cheapest paid) | Best value |\n| Use Tavily `basic` before `advanced` | ~50% cost reduction |\n| Set appropriate `max_results` | Linear cost savings |\n| Use Exa only for semantic queries | Avoid waste |\n\n### Performance Optimization\n\n| Tip | Impact |\n|-----|--------|\n| Serper is fastest (~200ms) | Use for time-sensitive queries |\n| Tavily `basic` faster than `advanced` | ~2x faster |\n| Lower `max_results` = faster response | Linear improvement |\n\n---\n\n## FAQ & Troubleshooting\n\n### General Questions\n\n**Q: Do I need API keys for all three providers?**\n> No. You only need keys for providers you want to use. Auto-routing skips providers without keys.\n\n**Q: Which provider should I start with?**\n> Serper โ€” it's the fastest, cheapest, and has the largest free tier (2,500 queries).\n\n**Q: Can I use multiple providers in one workflow?**\n> Yes! That's the recommended approach. See [Workflow Examples](#workflow-examples).\n\n**Q: How do I reduce API costs?**\n> Use auto-routing (defaults to cheapest), start with lower `max_results`, use Tavily `basic` before `advanced`.\n\n### Auto-Routing Questions\n\n**Q: Why did my query go to the wrong provider?**\n> Use `--explain-routing` to debug. Add custom keywords to config.json if needed.\n\n**Q: Can I add my own keywords?**\n> Yes! Edit `config.json` โ†’ `auto_routing.keyword_mappings`.\n\n**Q: How does keyword scoring work?**\n> Multi-word phrases get higher weights. \"companies like\" (2 words) scores higher than \"like\" (1 word).\n\n**Q: What if no keywords match?**\n> Uses the fallback provider (default: Serper).\n\n**Q: Can I force a specific provider?**\n> Yes, use `-p serper`, `-p tavily`, or `-p exa`.\n\n### Troubleshooting\n\n**Error: \"Missing API key\"**\n```bash\n# Check if key is set\necho $SERPER_API_KEY\n\n# Set it\nexport SERPER_API_KEY=\"your-key\"\n```\n\n**Error: \"API Error (401)\"**\n> Your API key is invalid or expired. Generate a new one.\n\n**Error: \"API Error (429)\"**\n> Rate limited. Wait and retry, or upgrade your plan.\n\n**Empty results?**\n> Try a different provider, broaden your query, or remove restrictive filters.\n\n**Slow responses?**\n> Reduce `max_results`, use Tavily `basic`, or use Serper (fastest).\n\n---\n\n## API Reference\n\n### Output Format\n\nAll providers return unified JSON:\n\n```json\n{\n \"provider\": \"serper|tavily|exa\",\n \"query\": \"original search query\",\n \"results\": [\n {\n \"title\": \"Page Title\",\n \"url\": \"https://example.com/page\",\n \"snippet\": \"Content excerpt...\",\n \"score\": 0.95,\n \"date\": \"2024-01-15\",\n \"raw_content\": \"Full page content (Tavily only)\"\n }\n ],\n \"images\": [\"url1\", \"url2\"],\n \"answer\": \"Synthesized answer\",\n \"knowledge_graph\": { },\n \"routing\": {\n \"auto_routed\": true,\n \"selected_provider\": \"serper\",\n \"reason\": \"matched_keywords (score=1)\",\n \"matched_keywords\": [\"price\"]\n }\n}\n```\n\n### CLI Options Reference\n\n| Option | Providers | Description |\n|--------|-----------|-------------|\n| `-q, --query` | All | Search query |\n| `-p, --provider` | All | Provider: auto, serper, tavily, exa, you, searxng |\n| `-n, --max-results` | All | Max results (default: 5) |\n| `--auto` | All | Force auto-routing |\n| `--explain-routing` | All | Debug auto-routing |\n| `--images` | Serper, Tavily | Include images |\n| `--country` | Serper, You | Country code (default: us) |\n| `--language` | Serper, SearXNG | Language code (default: en) |\n| `--type` | Serper | search/news/images/videos/places/shopping |\n| `--time-range` | Serper, SearXNG | hour/day/week/month/year |\n| `--depth` | Tavily | basic/advanced |\n| `--topic` | Tavily | general/news |\n| `--raw-content` | Tavily | Include full page content |\n| `--exa-type` | Exa | neural/keyword |\n| `--category` | Exa | company/research paper/news/pdf/github/tweet |\n| `--start-date` | Exa | Start date (YYYY-MM-DD) |\n| `--end-date` | Exa | End date (YYYY-MM-DD) |\n| `--similar-url` | Exa | Find similar pages |\n| `--searxng-url` | SearXNG | Instance URL |\n| `--searxng-safesearch` | SearXNG | 0=off, 1=moderate, 2=strict |\n| `--engines` | SearXNG | Specific engines (google,bing,duckduckgo) |\n| `--categories` | SearXNG | Search categories (general,images,news) |\n| `--include-domains` | Tavily, Exa | Only these domains |\n| `--exclude-domains` | Tavily, Exa | Exclude these domains |\n| `--compact` | All | Compact JSON output |\n\n---\n\n## License\n\nMIT\n\n---\n\n## Links\n\n- [Serper](https://serper.dev) โ€” Google Search API\n- [Tavily](https://tavily.com) โ€” AI Research Search\n- [Exa](https://exa.ai) โ€” Neural Search\n- [ClawHub](https://clawhub.ai) โ€” OpenClaw Skills\n\nFile v2.8.4:_meta.json\n\n{\n \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n \"slug\": \"web-search-plus\",\n \"version\": \"2.8.4\",\n \"publishedAt\": 1771595808196\n}\n\nFile v2.8.4:CHANGELOG.md\n\n# Changelog - Web Search Plus\n\n## [2.8.4] - 2026-02-20\n\n### ๐Ÿ”’ Security Fix: SSRF protection in setup wizard\n\n- **Fixed:** `setup.py` SearXNG connection test had no SSRF protection (unlike `search.py`)\n- **Before:** Operator could be tricked into probing internal networks during setup\n- **After:** Same IP validation as `search.py` โ€” blocks private IPs, cloud metadata, loopback\n- **Credit:** ClawHub security scanner\n\n## [2.8.3] - 2026-02-20\n\n### ๐Ÿ› Critical Fix: Perplexity results empty\n\n- **Fixed:** Perplexity provider returned 0 results because the AI-synthesized answer wasn't mapped into the results array\n- **Before:** Only extracted URLs from the answer text were returned as results (often 0)\n- **After:** The full answer is now the primary result (title, snippet with cleaned text), extracted source URLs follow as additional results\n- **Impact:** Perplexity queries now always return at least 1 result with the synthesized answer\n\n## [2.8.0] - 2026-02-20\n\n### ๐Ÿ†• New Provider: Perplexity (AI-Synthesized Answers)\n\nAdded Perplexity as the 6th search provider via Kilo Gateway โ€” the first provider that returns **direct answers with citations** instead of just links:\n\n#### Features\n- **AI-Synthesized Answers**: Get a complete answer, not a list of links\n- **Inline Citations**: Every claim backed by `[1][2][3]` source references\n- **Real-Time Web Search**: Perplexity searches the web live, reads pages, and summarizes\n- **Zero Extra Config**: Works through Kilo Gateway with your existing `KILOCODE_API_KEY`\n- **Model**: `perplexity/sonar-pro` (best quality, supports complex queries)\n\n#### Auto-Routing Signals\nNew direct-answer intent detection routes to Perplexity for:\n- Status queries: \"status of\", \"current state of\", \"what is the status\"\n- Local info: \"events in [city]\", \"things to do in\", \"what's happening in\"\n- Direct questions: \"what is\", \"who is\", \"when did\", \"how many\"\n- Current affairs: \"this week\", \"this weekend\", \"right now\", \"today\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"events in Graz Austria this weekend\" # โ†’ Perplexity\npython3 scripts/search.py -q \"what is the current status of Ethereum\" # โ†’ Perplexity\n\n# Explicit\npython3 scripts/search.py -p perplexity -q \"latest AI regulation news\"\n```\n\n#### Configuration\nRequires `KILOCODE_API_KEY` environment variable (Kilo Gateway account).\nNo additional API key needed โ€” Perplexity is accessed through Kilo's unified API.\n\n```bash\nexport KILOCODE_API_KEY=\"your-kilo-key\"\n```\n\n### ๐Ÿ”ง Routing Rebalance\n\nMajor overhaul of the auto-routing confidence scoring to fix Serper dominance:\n\n#### Problem\nSerper (Google) was winning ~90% of queries due to:\n- High recency multiplier boosting Serper on any query with dates/years\n- Default provider priority placing Serper first in ties\n- Research and discovery signals not strong enough to override\n\n#### Changes\n- **Lowered Serper recency multiplier** โ€” date mentions no longer auto-route to Google\n- **Strengthened research signals** for Tavily:\n - Added: \"status of\", \"what happened with\", \"how does X compare\"\n - Boosted weights for comparison patterns (4.0 โ†’ 5.0)\n- **Strengthened discovery signals** for Exa:\n - Added: \"events in\", \"things to do in\", \"startups similar to\"\n - Boosted weights for local discovery patterns\n- **Updated provider priority order**: `tavily โ†’ exa โ†’ perplexity โ†’ serper โ†’ you โ†’ searxng`\n - Serper moved from 1st to 4th in tie-breaking\n - Research/discovery providers now win on ambiguous queries\n\n#### Routing Test Results\n\n| Query | Before | After | โœ“ |\n|-------|--------|-------|---|\n| \"latest OpenClaw version Feb 2026\" | Serper | Serper | โœ… |\n| \"Ethereum Pectra upgrade status\" | Serper | **Tavily** | โœ… |\n| \"events in Graz this weekend\" | Serper | **Perplexity** | โœ… |\n| \"compare SearXNG vs Brave for AI agents\" | Serper | **Tavily** | โœ… |\n| \"Sam Altman OpenAI news this week\" | Serper | Serper | โœ… |\n| \"find startups similar to Kilo Code\" | Serper | **Exa** | โœ… |\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | Perplexity | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:----------:|:-------:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšก | โšกโšกโšก | โšก |\n| Direct Answers | โœ— | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— |\n| Citations | โœ— | โœ— | โœ— | โœ“ | โœ— | โœ— |\n| Local Events | โœ“ | โœ— | โœ“ | โœ“โœ“ | โœ— | โœ“ |\n| Research | โœ— | โœ“โœ“ | โœ“ | โœ“ | โœ“ | โœ— |\n| Discovery | โœ— | โœ— | โœ“โœ“ | โœ— | โœ— | โœ— |\n| Self-Hosted | โœ— | โœ— | โœ— | โœ— | โœ— | โœ“ |\n\n## [2.7.0] - 2026-02-14\n\n### โœจ Added\n- Provider cooldown tracking in `.cache/provider_health.json`\n- Exponential cooldown on provider failures: **1m โ†’ 5m โ†’ 25m โ†’ 1h (cap)**\n- Retry strategy for transient failures (timeout, 429, 503): up to 2 retries with backoff **1s โ†’ 3s โ†’ 9s**\n- Smarter cache keys hashed from full request context (query/provider/max_results + locale, freshness, time_range, topic, search_engines, include_news, and related params)\n- Cross-provider result deduplication by normalized URL during fallback merge\n\n### ๐Ÿ”ง Changed\n- Cooldown providers are skipped in routing while their cooldown is active\n- Provider health is reset automatically after successful requests\n- Fallback output now includes dedup metadata:\n - `deduplicated: true|false`\n - `metadata.dedup_count`\n\n\n## [2.6.5] - 2026-02-11\n\n### ๐Ÿ†• File-Based Result Caching\n\nAdded local caching to save API costs on repeated searches:\n\n#### Features\n- **Automatic Caching**: Search results cached locally by default\n- **1-Hour TTL**: Results expire after 3600 seconds (configurable)\n- **Cache Indicators**: Response includes `cached: true/false` and `cache_age_seconds`\n- **Zero-Cost Repeats**: Cached requests don't hit APIs\n\n#### New CLI Options\n- `--cache-ttl SECONDS` โ€” Custom cache TTL (default: 3600)\n- `--no-cache` โ€” Bypass cache, always fetch fresh\n- `--clear-cache` โ€” Delete all cached results\n- `--cache-stats` โ€” Show cache statistics (entries, size, age)\n\n#### Configuration\n- **Cache directory**: `.cache/` in skill directory\n- **Environment variable**: `WSP_CACHE_DIR` to override location\n- **Cache key**: Based on query + provider + max_results (SHA256)\n\n#### Usage Examples\n```bash\n# First request costs API credits\npython3 scripts/search.py -q \"AI startups\"\n\n# Second request is FREE (uses cache)\npython3 scripts/search.py -q \"AI startups\"\n\n# Force fresh results\npython3 scripts/search.py -q \"AI startups\" --no-cache\n\n# View stats\npython3 scripts/search.py --cache-stats\n\n# Clear everything\npython3 scripts/search.py --clear-cache\n```\n\n#### Technical Details\n- Cache files: JSON with metadata (_cache_timestamp, _cache_key, etc.)\n- Automatic cleanup of expired entries on access\n- Graceful handling of corrupted cache files\n\n## [2.6.1] - 2026-02-04\n\n- Privacy cleanup: removed hardcoded paths and personal info from docs\n\n## [2.5.0] - 2026-02-03\n\n### ๐Ÿ†• New Provider: SearXNG (Privacy-First Meta-Search)\n\nAdded SearXNG as the 5th search provider, focused on privacy and self-hosted search:\n\n#### Features\n- **Privacy-Preserving**: No tracking, no profiling โ€” your searches stay private\n- **Multi-Source Aggregation**: Queries 70+ upstream engines (Google, Bing, DuckDuckGo, etc.)\n- **$0 API Cost**: Self-hosted = unlimited queries with no API fees\n- **Diverse Results**: Get perspectives from multiple search engines in one query\n- **Customizable**: Choose which engines to use, set SafeSearch levels, language preferences\n\n#### Auto-Routing Signals\nNew privacy/multi-source intent detection routes to SearXNG for:\n- Privacy queries: \"private\", \"anonymous\", \"without tracking\", \"no tracking\"\n- Multi-source: \"aggregate results\", \"multiple sources\", \"diverse perspectives\"\n- Budget/free: \"free search\", \"no api cost\", \"self-hosted search\"\n- German: \"privat\", \"anonym\", \"ohne tracking\", \"verschiedene quellen\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG\n\n# Explicit\npython3 scripts/search.py -p searxng -q \"linux distros\"\npython3 scripts/search.py -p searxng -q \"AI news\" --engines \"google,bing,duckduckgo\"\npython3 scripts/search.py -p searxng -q \"privacy tools\" --searxng-safesearch 2\n```\n\n#### Configuration\n```json\n{\n \"searxng\": {\n \"instance_url\": \"https://your-instance.example.com\",\n \"safesearch\": 0,\n \"engines\": null,\n \"language\": \"en\"\n }\n}\n```\n\n#### Setup\nSearXNG requires a self-hosted instance with JSON format enabled:\n```bash\n# Docker setup (5 minutes)\ndocker run -d -p 8080:8080 searxng/searxng\n\n# Enable JSON in settings.yml:\n# search:\n# formats: [html, json]\n\n# Set instance URL\nexport SEARXNG_INSTANCE_URL=\"http://localhost:8080\"\n```\n\nSee: https://docs.searxng.org/admin/installation.html\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | You.com | SearXNG |\n|---------|:------:|:------:|:---:|:-------:|:-------:|\n| Privacy-First | โœ— | โœ— | โœ— | โœ— | โœ“โœ“ |\n| Self-Hosted | โœ— | โœ— | โœ— | โœ— | โœ“ |\n| API Cost | $$ | $$ | $$ | $ | **FREE** |\n| Multi-Engine | โœ— | โœ— | โœ— | โœ— | โœ“ (70+) |\n\n### ๐Ÿ”ง Technical Changes\n\n- Added `search_searxng()` function with full error handling\n- Added `PRIVACY_SIGNALS` to QueryAnalyzer for auto-routing\n- Updated setup wizard with SearXNG option (instance URL validation)\n- Updated config.example.json with searxng section\n- New CLI args: `--searxng-url`, `--searxng-safesearch`, `--engines`, `--categories`\n\n---\n\n## [2.4.4] - 2026-02-03\n\n### ๐Ÿ“ Documentation: Provider Count Fix\n\n- **Fixed:** \"You can use 1, 2, or all 3\" โ†’ \"1, 2, 3, or all 4\" (we have 4 providers now!)\n- **Impact:** Accurate documentation for setup wizard\n\n## [2.4.3] - 2026-02-03\n\n### ๐Ÿ“ Documentation: Updated README\n\n- **Added:** \"NEW in v2.4.2\" badge for You.com in SKILL.md\n- **Impact:** ClawHub README now properly highlights You.com as new feature\n\n## [2.4.2] - 2026-02-03\n\n### ๐Ÿ› Critical Fix: You.com API Configuration\n\n- **Fixed:** Incorrect hostname (`api.ydc-index.io` โ†’ `ydc-index.io`)\n- **Fixed:** Incorrect header name (`X-API-Key` โ†’ `X-API-KEY` uppercase)\n- **Impact:** You.com now works correctly - was giving 403 Forbidden before\n- **Status:** โœ… Fully tested and working\n\n## [2.4.1] - 2026-02-03\n\n### ๐Ÿ› Bugfix: You.com URL Encoding\n\n- **Fixed:** URL encoding for You.com queries - spaces and special characters now properly encoded\n- **Impact:** Queries with spaces (e.g., \"OpenClaw AI framework\") work correctly now\n- **Technical:** Added `urllib.parse.quote` for parameter encoding\n\n## [2.4.0] - 2026-02-03\n\n### ๐Ÿ†• New Provider: You.com\n\nAdded You.com as the 4th search provider, optimized for RAG applications and real-time information:\n\n#### Features\n- **LLM-Ready Snippets**: Pre-extracted, query-aware text excerpts perfect for feeding into AI models\n- **Unified Web + News**: Get both web pages and news articles in a single API call\n- **Live Crawling**: Fetch full page content on-demand in Markdown format (`--livecrawl`)\n- **Automatic News Classification**: Intelligently includes news results based on query intent\n- **Freshness Controls**: Filter by recency (day, week, month, year, or date range)\n- **SafeSearch Support**: Content filtering (off, moderate, strict)\n\n#### Auto-Routing Signals\nNew RAG/Real-time intent detection routes to You.com for:\n- RAG context queries: \"summarize\", \"key points\", \"tldr\", \"context for\"\n- Real-time info: \"latest news\", \"current status\", \"right now\", \"what's happening\"\n- Information synthesis: \"updates on\", \"situation\", \"main takeaways\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"summarize key points about AI regulation\" # โ†’ You.com\n\n# Explicit\npython3 scripts/search.py -p you -q \"climate change\" --livecrawl all\npython3 scripts/search.py -p you -q \"tech news\" --freshness week\n```\n\n#### Configuration\n```json\n{\n \"you\": {\n \"country\": \"US\",\n \"language\": \"en\",\n \"safesearch\": \"moderate\",\n \"include_news\": true\n }\n}\n```\n\n#### API Key Setup\n```bash\nexport YOU_API_KEY=\"your-key\" # Get from https://api.you.com\n```\n\n### ๐Ÿ“Š Updated Provider Comparison\n\n| Feature | Serper | Tavily | Exa | You.com |\n|---------|:------:|:------:|:---:|:-------:|\n| Speed | โšกโšกโšก | โšกโšก | โšกโšก | โšกโšกโšก |\n| News Integration | โœ“ | โœ— | โœ— | โœ“ |\n| RAG-Optimized | โœ— | โœ“ | โœ— | โœ“โœ“ |\n| Full Page Content | โœ— | โœ“ | โœ“ | โœ“ |\n\n---\n\n## [2.1.5] - 2026-01-27\n\n### ๐Ÿ“ Documentation\n\n- Added warning about NOT using Tavily/Serper/Exa in core OpenClaw config\n- Core OpenClaw only supports `brave` as the built-in provider\n- This skill's providers must be used via environment variables and scripts, not `openclaw.json`\n\n## [2.1.0] - 2026-01-23\n\n### ๐Ÿง  Intelligent Multi-Signal Routing\n\nCompletely overhauled auto-routing with sophisticated query analysis:\n\n#### Intent Classification\n- **Shopping Intent**: Detects price patterns (\"how much\", \"cost of\"), purchase signals (\"buy\", \"order\"), deal keywords, and product+brand combinations\n- **Research Intent**: Identifies explanation patterns (\"how does\", \"why does\"), analysis signals (\"pros and cons\", \"compare\"), learning keywords, and complex multi-clause queries\n- **Discovery Intent**: Recognizes similarity patterns (\"similar to\", \"alternatives\"), company discovery signals, URL/domain detection, and academic patterns\n\n#### Linguistic Pattern Detection\n- \"How much\" / \"price of\" โ†’ Shopping (Serper)\n- \"How does\" / \"Why does\" / \"Explain\" โ†’ Research (Tavily)\n- \"Companies like\" / \"Similar to\" / \"Alternatives\" โ†’ Discovery (Exa)\n- Product + Brand name combos โ†’ Shopping (Serper)\n- URLs and domains in query โ†’ Similar search (Exa)\n\n#### Query Analysis Features\n- **Complexity scoring**: Long, multi-clause queries get routed to research providers\n- **URL detection**: Automatic detection of URLs/domains triggers Exa similar search\n- **Brand recognition**: Tech brands (Apple, Samsung, Sony, etc.) with product terms โ†’ shopping\n- **Recency signals**: \"latest\", \"2026\", \"breaking\" boost news mode\n\n#### Confidence Scoring\n- **HIGH (70-100%)**: Strong signal match, very reliable routing\n- **MEDIUM (40-69%)**: Good match, should work well\n- **LOW (0-39%)**: Ambiguous query, using fallback provider\n- Confidence based on absolute signal strength + relative margin over alternatives\n\n#### Enhanced Debug Mode\n```bash\npython3 scripts/search.py --explain-routing -q \"your query\"\n```\n\nNow shows:\n- Routing decision with confidence level\n- All provider scores\n- Top matched signals with weights\n- Query analysis (complexity, URL detection, recency focus)\n- All matched patterns per provider\n\n### ๐Ÿ”ง Technical Changes\n\n#### QueryAnalyzer Class\nNew `QueryAnalyzer` class with:\n- `SHOPPING_SIGNALS`: 25+ weighted patterns for shopping intent\n- `RESEARCH_SIGNALS`: 30+ weighted patterns for research intent\n- `DISCOVERY_SIGNALS`: 20+ weighted patterns for discovery intent\n- `LOCAL_NEWS_SIGNALS`: 25+ patterns for local/news queries\n- `BRAND_PATTERNS`: Tech brand detection regex\n\n#### Signal Weighting\n- Multi-word phrases get higher weights (e.g., \"how much\" = 4.0 vs \"price\" = 3.0)\n- Strong signals: price patterns (4.0), similarity patterns (5.0), URLs (5.0)\n- Medium signals: product terms (2.5), learning keywords (2.5)\n- Bonus scoring: Product+brand combo (+3.0), complex query (+2.5)\n\n#### Improved Output Format\n```json\n{\n \"routing\": {\n \"auto_routed\": true,\n \"provider\": \"serper\",\n \"confidence\": 0.78,\n \"confidence_level\": \"high\",\n \"reason\": \"high_confidence_match\",\n \"top_signals\": [{\"matched\": \"price\", \"weight\": 3.0}],\n \"scores\": {\"serper\": 7.0, \"tavily\": 0.0, \"exa\": 0.0}\n }\n}\n```\n\n### ๐Ÿ“š Documentation Updates\n\n- **SKILL.md**: Complete rewrite with signal tables and confidence scoring guide\n- **README.md**: Updated with intelligent routing examples and confidence levels\n- **FAQ**: Updated to explain multi-signal analysis\n\n### ๐Ÿงช Test Results\n\n| Query | Provider | Confidence | Signals |\n|-------|----------|------------|---------|\n| \"how much does iPhone 16 cost\" | Serper | 68% | \"how much\", brand+product |\n| \"how does quantum entanglement work\" | Tavily | 86% HIGH | \"how does\", \"what are\", \"implications\" |\n| \"startups similar to Notion\" | Exa | 76% HIGH | \"similar to\", \"Series A\" |\n| \"companies like stripe.com\" | Exa | 100% HIGH | URL detected, \"companies like\" |\n| \"MacBook Pro M3 specs review\" | Serper | 70% HIGH | brand+product, \"specs\", \"review\" |\n| \"Tesla\" | Serper | 0% LOW | No signals (fallback) |\n| \"arxiv papers on transformers\" | Exa | 58% | \"arxiv\" |\n| \"latest AI news 2026\" | Serper | 77% HIGH | \"latest\", \"news\", \"2026\" |\n\n---\n\n## [2.0.0] - 2026-01-23\n\n### ๐ŸŽ‰ Major Features\n\n#### Smart Auto-Routing\n- **Automatic provider selection** based on query analysis\n- No need to manually choose provider - just search!\n- Intelligent keyword matching for routing decisions\n- Pattern detection for query types (shopping, research, discovery)\n- Scoring system for provider selection\n\n#### User Configuration\n- **config.json**: Full control over auto-routing behavior\n- **Configurable keyword mappings**: Add your own routing keywords\n- **Provider priority**: Set tie-breaker order\n- **Disable providers**: Turn off providers you don't have API keys for\n- **Enable/disable auto-routing**: Opt-in or opt-out as needed\n\n#### Debugging Tools\n- **--explain-routing** flag: See exactly why a provider was selected\n- Detailed routing metadata in JSON responses\n- Shows matched keywords and routing scores\n\n### ๐Ÿ“š Documentation\n\n- **README.md**: Complete auto-routing guide with examples\n- **SKILL.md**: Detailed routing logic and configuration reference\n- **FAQ section**: Common questions about auto-routing\n- **Configuration examples**: Pre-built configs for common use cases\n\n---\n\n## [1.0.x] - Initial Release\n\n- Multi-provider search: Serper, Tavily, Exa\n- Manual provider selection with `-p` flag\n- Unified JSON output format\n- Provider-specific options (--depth, --category, --similar-url, etc.)\n- Domain filtering for Tavily/Exa\n- Date filtering for Exa\n\nFile v2.8.4:FAQ.md\n\n# Frequently Asked Questions\n\n## Caching (NEW in v2.7.0!)\n\n### How does caching work?\nSearch results are automatically cached locally for 1 hour (3600 seconds). When you make the same query again, you get instant results at $0 API cost. The cache key is based on: query text + provider + max_results.\n\n### Where are cached results stored?\nIn `.cache/` directory inside the skill folder by default. Override with `WSP_CACHE_DIR` environment variable:\n```bash\nexport WSP_CACHE_DIR=\"/path/to/custom/cache\"\n```\n\n### How do I see cache stats?\n```bash\npython3 scripts/search.py --cache-stats\n```\nThis shows total entries, size, oldest/newest entries, and breakdown by provider.\n\n### How do I clear the cache?\n```bash\npython3 scripts/search.py --clear-cache\n```\n\n### Can I change the cache TTL?\nYes! Default is 3600 seconds (1 hour). Set a custom TTL per request:\n```bash\npython3 scripts/search.py -q \"query\" --cache-ttl 7200 # 2 hours\n```\n\n### How do I skip the cache?\nUse `--no-cache` to always fetch fresh results:\n```bash\npython3 scripts/search.py -q \"query\" --no-cache\n```\n\n### How do I know if a result was cached?\nThe response includes:\n- `\"cached\": true/false` โ€” whether result came from cache\n- `\"cache_age_seconds\": 1234` โ€” how old the cached result is (when cached)\n\n---\n\n## General\n\n### How does auto-routing decide which provider to use?\nMulti-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.\n\n### What if it picks the wrong provider?\nOverride with `-p serper/tavily/exa`. Check `--explain-routing` to understand why it chose differently.\n\n### What does \"low confidence\" mean?\nQuery is ambiguous (e.g., \"Tesla\" could be cars, stock, or company). Falls back to Serper. Results may vary.\n\n### Can I disable a provider?\nYes! In config.json: `\"disabled_providers\": [\"exa\"]`\n\n---\n\n## API Keys\n\n### Which API keys do I need?\nAt minimum ONE key (or SearXNG instance). You can use just Serper, just Tavily, just Exa, just You.com, or just SearXNG. Missing keys = that provider is skipped.\n\n### Where do I get API keys?\n- Serper: https://serper.dev (2,500 free queries, no credit card)\n- Tavily: https://tavily.com (1,000 free searches/month)\n- Exa: https://exa.ai (1,000 free searches/month)\n- You.com: https://api.you.com (Limited free tier for testing)\n- SearXNG: Self-hosted, no key needed! https://docs.searxng.org/admin/installation.html\n\n### How do I set API keys?\nTwo options (both auto-load):\n\n**Option A: .env file**\n```bash\nexport SERPER_API_KEY=\"your-key\"\n```\n\n**Option B: config.json** (v2.2.1+)\n```json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## Routing Details\n\n### How do I know which provider handled my search?\nCheck `routing.provider` in JSON output, or `[๐Ÿ” Searched with: Provider]` in chat responses.\n\n### Why does it sometimes choose Serper for research questions?\nIf the query has brand/product signals (e.g., \"how does Tesla FSD work\"), shopping intent may outweigh research intent. Override with `-p tavily`.\n\n### What's the confidence threshold?\nDefault: 0.3 (30%). Below this = low confidence, uses fallback. Adjustable in config.json.\n\n---\n\n## You.com Specific\n\n### When should I use You.com over other providers?\nYou.com excels at:\n- **RAG applications**: Pre-extracted snippets ready for LLM consumption\n- **Real-time information**: Current events, breaking news, status updates\n- **Combined sources**: Web + news results in a single API call\n- **Summarization tasks**: \"What's the latest on...\", \"Key points about...\"\n\n### What's the livecrawl feature?\nYou.com can fetch full page content on-demand. Use `--livecrawl web` for web results, `--livecrawl news` for news articles, or `--livecrawl all` for both. Content is returned in Markdown format.\n\n### Does You.com include news automatically?\nYes! You.com's intelligent classification automatically includes relevant news results when your query has news intent. You can also use `--include-news` to explicitly enable it.\n\n---\n\n## SearXNG Specific\n\n### Do I need my own SearXNG instance?\nYes! SearXNG is self-hosted. Most public instances disable the JSON API to prevent bot abuse. You need to run your own instance with JSON format enabled. See: https://docs.searxng.org/admin/installation.html\n\n### How do I set up SearXNG?\nDocker is the easiest way:\n```bash\ndocker run -d -p 8080:8080 searxng/searxng\n```\nThen enable JSON in `settings.yml`:\n```yaml\nsearch:\n formats:\n - html\n - json\n```\n\n### Why am I getting \"403 Forbidden\"?\nThe JSON API is disabled on your instance. Enable it in `settings.yml` under `search.formats`.\n\n### What's the API cost for SearXNG?\n**$0!** SearXNG is free and open-source. You only pay for hosting (~$5/month VPS). Unlimited queries.\n\n### When should I use SearXNG?\n- **Privacy-sensitive queries**: No tracking, no profiling\n- **Budget-conscious**: $0 API cost\n- **Diverse results**: Aggregates 70+ search engines\n- **Self-hosted requirements**: Full control over your search infrastructure\n- **Fallback provider**: When paid APIs are rate-limited\n\n### Can I limit which search engines SearXNG uses?\nYes! Use `--engines google,bing,duckduckgo` to specify engines, or configure defaults in `config.json`.\n\n---\n\n## Provider Selection\n\n### Which provider should I use?\n\n| Query Type | Best Provider | Why |\n|------------|---------------|-----|\n| **Shopping** (\"buy laptop\", \"cheap shoes\") | **Serper** | Google Shopping, price comparisons, local stores |\n| **Research** (\"how does X work?\", \"explain Y\") | **Tavily** | Deep research, academic quality, full-page content |\n| **Startups/Papers** (\"companies like X\", \"arxiv papers\") | **Exa** | Semantic/neural search, startup discovery |\n| **RAG/Real-time** (\"summarize latest\", \"current events\") | **You.com** | LLM-ready snippets, combined web+news |\n| **Privacy** (\"search without tracking\") | **SearXNG** | No tracking, multi-source, self-hosted |\n\n**Tip:** Enable auto-routing and let the skill choose automatically! ๐ŸŽฏ\n\n### Do I need all 5 providers?\n**No!** All providers are optional. You can use:\n- **1 provider** (e.g., just Serper for everything)\n- **2-3 providers** (e.g., Serper + You.com for most needs)\n- **All 5** (maximum flexibility + fallback options)\n\n### How much do the APIs cost?\n\n| Provider | Free Tier | Paid Plan |\n|----------|-----------|-----------|\n| **Serper** | 2,500 queries/mo | $50/mo (5,000 queries) |\n| **Tavily** | 1,000 queries/mo | $150/mo (10,000 queries) |\n| **Exa** | 1,000 queries/mo | $1,000/mo (100,000 queries) |\n| **You.com** | Limited free | ~$10/mo (varies by usage) |\n| **SearXNG** | **FREE** โœ… | Only VPS cost (~$5/mo if self-hosting) |\n\n**Budget tip:** Use SearXNG as primary + others as fallback for specialized queries!\n\n### How private is SearXNG really?\n\n| Setup | Privacy Level |\n|-------|---------------|\n| **Self-hosted (your VPS)** | โญโญโญโญโญ You control everything |\n| **Self-hosted (Docker local)** | โญโญโญโญโญ Fully private |\n| **Public instance** | โญโญโญ Depends on operator's logging policy |\n\n**Best practice:** Self-host if privacy is critical.\n\n### Which provider has the best results?\n\n| Metric | Winner |\n|--------|--------|\n| **Most accurate for facts** | Serper (Google) |\n| **Best for research depth** | Tavily |\n| **Best for semantic queries** | Exa |\n| **Best for RAG/AI context** | You.com |\n| **Most diverse sources** | SearXNG (70+ engines) |\n| **Most private** | SearXNG (self-hosted) |\n\n**Recommendation:** Enable multiple providers + auto-routing for best overall experience.\n\n### How does auto-routing work?\nThe skill analyzes your query for keywords and patterns:\n\n```python\n\"buy cheap laptop\" โ†’ Serper (shopping signals)\n\"how does AI work?\" โ†’ Tavily (research/explanation)\n\"companies like X\" โ†’ Exa (semantic/similar)\n\"summarize latest news\" โ†’ You.com (RAG/real-time)\n\"search privately\" โ†’ SearXNG (privacy signals)\n```\n\n**Confidence threshold:** Only routes if confidence > 30%. Otherwise uses default provider.\n\n**Override:** Use `-p provider` to force a specific provider.\n\n---\n\n## Production Use\n\n### Can I use this in production?\n**Yes!** Web-search-plus is production-ready:\n- โœ… Error handling with automatic fallback\n- โœ… Rate limit protection\n- โœ… Timeout handling (30s per provider)\n- โœ… API key security (.env + config.json gitignored)\n- โœ… 5 providers for redundancy\n\n**Tip:** Monitor API usage to avoid exceeding free tiers!\n\n### What if I run out of API credits?\n1. **Fallback chain:** Other enabled providers automatically take over\n2. **Use SearXNG:** Switch to self-hosted (unlimited queries)\n3. **Upgrade plan:** Paid tiers have higher limits\n4. **Rate limit:** Use `disabled_providers` to skip exhausted APIs temporarily\n\n---\n\n## Updates\n\n### How do I update to the latest version?\n\n**Via ClawHub (recommended):**\n```bash\nclawhub update web-search-plus --registry \"https://www.clawhub.ai\" --no-input\n```\n\n**Manually:**\n```bash\ncd /path/to/workspace/skills/web-search-plus/\ngit pull origin main\npython3 scripts/setup.py # Re-run to configure new features\n```\n\n### Where can I report bugs or request features?\n- **GitHub Issues:** https://github.com/robbyczgw-cla/web-search-plus/issues\n- **ClawHub:** https://www.clawhub.ai/skills/web-search-plus\n\nFile v2.8.4:TROUBLESHOOTING.md\n\n# Troubleshooting Guide\n\n## Caching Issues (v2.7.0+)\n\n### Cache not working / always fetching fresh\n\n**Symptoms:**\n- Every request hits the API\n- `\"cached\": false` even for repeated queries\n\n**Solutions:**\n1. Check cache directory exists and is writable:\n ```bash\n ls -la .cache/ # Should exist in skill directory\n ```\n2. Verify `--no-cache` isn't being passed\n3. Check disk space isn't full\n4. Ensure query is EXACTLY the same (including provider and max_results)\n\n### Stale results from cache\n\n**Symptoms:**\n- Getting outdated information\n- Cache TTL seems too long\n\n**Solutions:**\n1. Use `--no-cache` to force fresh results\n2. Reduce TTL: `--cache-ttl 1800` (30 minutes)\n3. Clear cache: `python3 scripts/search.py --clear-cache`\n\n### Cache growing too large\n\n**Symptoms:**\n- Disk space filling up\n- Many .json files in `.cache/`\n\n**Solutions:**\n1. Clear cache periodically:\n ```bash\n python3 scripts/search.py --clear-cache\n ```\n2. Set up a cron job to clear weekly\n3. Use a smaller TTL so entries expire faster\n\n### \"Permission denied\" when caching\n\n**Symptoms:**\n- Cache write errors in stderr\n- Searches work but don't cache\n\n**Solutions:**\n1. Check directory permissions: `chmod 755 .cache/`\n2. Use custom cache dir: `export WSP_CACHE_DIR=\"/tmp/wsp-cache\"`\n\n---\n\n## Common Issues\n\n### \"No API key found\" error\n\n**Symptoms:**\n```\nError: No API key found for serper\n```\n\n**Solutions:**\n1. Check `.env` exists in skill folder with `export VAR=value` format\n2. Keys auto-load from skill's `.env` since v2.2.0\n3. Or set in system environment: `export SERPER_API_KEY=\"...\"`\n4. Verify key format in config.json:\n ```json\n { \"serper\": { \"api_key\": \"your-key\" } }\n ```\n\n**Priority order:** config.json > .env > environment variable\n\n---\n\n### Getting empty results\n\n**Symptoms:**\n- Search returns no results\n- `\"results\": []` in JSON output\n\n**Solutions:**\n1. Check API key is valid (try the provider's web dashboard)\n2. Try a different provider with `-p`\n3. Some queries have no results (very niche topics)\n4. Check if provider is rate-limited\n5. Verify internet connectivity\n\n**Debug:**\n```bash\npython3 scripts/search.py -q \"test query\" --verbose\n```\n\n---\n\n### Rate limited\n\n**Symptoms:**\n```\nError: 429 Too Many Requests\nError: Rate limit exceeded\n```\n\n**Good news:** Since v2.2.5, automatic fallback kicks in! If one provider hits rate limits, the script automatically tries the next provider.\n\n**Solutions:**\n1. Wait for rate limit to reset (usually 1 hour or end of day)\n2. Use a different provider: `-p tavily` instead of `-p serper`\n3. Check free tier limits:\n - Serper: 2,500 free total\n - Tavily: 1,000/month free\n - Exa: 1,000/month free\n4. Upgrade to paid tier for higher limits\n5. Use SearXNG (self-hosted, unlimited)\n\n**Fallback info:** Response will include `routing.fallback_used: true` when fallback was used.\n\n---\n\n### SearXNG: \"403 Forbidden\"\n\n**Symptoms:**\n```\nError: 403 Forbidden\nError: JSON format not allowed\n```\n\n**Cause:** Most public SearXNG instances disable JSON API to prevent bot abuse.\n\n**Solution:** Self-host your own instance:\n```bash\ndocker run -d -p 8080:8080 searxng/searxng\n```\n\nThen enable JSON in `settings.yml`:\n```yaml\nsearch:\n formats:\n - html\n - json # Add this!\n```\n\nRestart the container and update your config:\n```json\n{\n \"searxng\": {\n \"instance_url\": \"http://localhost:8080\"\n }\n}\n```\n\n---\n\n### SearXNG: Slow responses\n\n**Symptoms:**\n- SearXNG takes 2-5 seconds\n- Other providers are faster\n\n**Explanation:** This is expected behavior. SearXNG queries 70+ upstream engines in parallel, which takes longer than direct API calls.\n\n**Trade-off:** Slower but privacy-preserving + multi-source + $0 cost.\n\n**Solutions:**\n1. Accept the trade-off for privacy benefits\n2. Limit engines for faster results:\n ```bash\n python3 scripts/search.py -p searxng -q \"query\" --engines \"google,bing\"\n ```\n3. Use SearXNG as fallback (put last in priority list)\n\n---\n\n### Auto-routing picks wrong provider\n\n**Symptoms:**\n- Query about research goes to Serper\n- Query about shopping goes to Tavily\n\n**Debug:**\n```bash\npython3 scripts/search.py --explain-routing -q \"your query\"\n```\n\nThis shows the full analysis:\n```json\n{\n \"query\": \"how much does iPhone 16 Pro cost\",\n \"routing_decision\": {\n \"provider\": \"serper\",\n \"confidence\": 0.68,\n \"reason\": \"moderate_confidence_match\"\n },\n \"scores\": {\"serper\": 7.0, \"tavily\": 0.0, \"exa\": 0.0},\n \"top_signals\": [\n {\"matched\": \"how much\", \"weight\": 4.0},\n {\"matched\": \"brand + product detected\", \"weight\": 3.0}\n ]\n}\n```\n\n**Solutions:**\n1. Override with explicit provider: `-p tavily`\n2. Rephrase query to be more explicit about intent\n3. Adjust `confidence_threshold` in config.json (default: 0.3)\n\n---\n\n### Config not loading\n\n**Symptoms:**\n- Changes to config.json not applied\n- Using default values instead\n\n**Solutions:**\n1. Check JSON syntax (use a validator)\n2. Ensure file is in skill directory: `/path/to/skills/web-search-plus/config.json`\n3. Check file permissions\n4. Run setup wizard to regenerate:\n ```bash\n python3 scripts/setup.py --reset\n ```\n\n**Validate JSON:**\n```bash\npython3 -m json.tool config.json\n```\n\n---\n\n### Python dependencies missing\n\n**Symptoms:**\n```\nModuleNotFoundError: No module named 'requests'\n```\n\n**Solution:**\n```bash\npip3 install requests\n```\n\nOr install all dependencies:\n```bash\npip3 install -r requirements.txt\n```\n\n---\n\n### Timeout errors\n\n**Symptoms:**\n```\nError: Request timeout after 30s\n```\n\n**Causes:**\n- Slow network connection\n- Provider API issues\n- SearXNG instance overloaded\n\n**Solutions:**\n1. Try again (temporary issue)\n2. Switch provider: `-p serper`\n3. Check your internet connection\n4. If using SearXNG, check instance health\n\n---\n\n### Duplicate results\n\n**Symptoms:**\n- Same result appears multiple times\n- Results overlap between providers\n\n**Solution:** This is expected when using auto-fallback or multiple providers. The skill doesn't deduplicate across providers.\n\nFor single-provider results:\n```bash\npython3 scripts/search.py -p serper -q \"query\"\n```\n\n---\n\n## Debug Mode\n\nFor detailed debugging:\n\n```bash\n# Verbose output\npython3 scripts/search.py -q \"query\" --verbose\n\n# Show routing decision\npython3 scripts/search.py -q \"query\" --explain-routing\n\n# Dry run (no actual search)\npython3 scripts/search.py -q \"query\" --dry-run\n\n# Test specific provider\npython3 scripts/search.py -p tavily -q \"query\" --verbose\n```\n\n---\n\n## Getting Help\n\n**Still stuck?**\n\n1. Check the full documentation in `README.md`\n2. Run the setup wizard: `python3 scripts/setup.py`\n3. Review `FAQ.md` for common questions\n4. Open an issue: https://github.com/robbyczgw-cla/web-search-plus/issues\n\nFile v2.8.4:config.example.json\n\n{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"$comment\": \"Web Search Plus configuration โ€” intelligent routing and provider settings\",\n \"defaults\": {\n \"provider\": \"serper\",\n \"max_results\": 5\n },\n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"provider_priority\": [\n \"serper\",\n \"tavily\",\n \"exa\",\n \"you\",\n \"searxng\"\n ],\n \"disabled_providers\": [],\n \"confidence_threshold\": 0.3,\n \"keyword_mappings\": {\n \"serper\": [\n \"price\",\n \"buy\",\n \"shop\",\n \"shopping\",\n \"cost","readmeExcerpt":"Skill: Web Search Plus Owner: robbyczgw-cla Summary: Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neura... Tags: latest:2.8.5 Version history: v2.8.5 | 2026-02-20T15:58:22.076Z | auto web-search-plus 2.8.5 - Updated package version to 2.8.5. - Minor updates in CHANGELOG.md and scripts/search.py. - No changes to ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Interactive setup (recommended for first run)\npython3 scripts/setup.py\n\n# Or manual: copy config and add your keys\ncp config.example.json config.json"},{"language":"bash","snippet":"# Option A: .env file (recommended)\nexport SERPER_API_KEY=\"your-key\"\nexport TAVILY_API_KEY=\"your-key\"\n\n# Option B: config.json\n{ \"serper\": { \"api_key\": \"your-key\" } }"},{"language":"bash","snippet":"\"iPhone 16 price\" โ†’ Serper (shopping keywords)\n\"how does quantum computing work\" โ†’ Tavily (research question)\n\"companies like stripe.com\" โ†’ Exa (URL detected, similarity)\n\"events in Graz this weekend\" โ†’ Perplexity (local + direct answer)\n\"latest news on AI\" โ†’ You.com (real-time intent)\n\"search privately\" โ†’ SearXNG (privacy keywords)"},{"language":"bash","snippet":"python3 scripts/search.py -q \"Tesla Model 3 price\"\npython3 scripts/search.py -q \"explain machine learning\"\npython3 scripts/search.py -q \"startups like Figma\""},{"language":"bash","snippet":"python3 scripts/search.py -p serper -q \"weather Berlin\"\npython3 scripts/search.py -p tavily -q \"quantum computing\" --depth advanced\npython3 scripts/search.py -p exa --similar-url \"https://stripe.com\" --category company\npython3 scripts/search.py -p you -q \"breaking tech news\" --include-news\npython3 scripts/search.py -p searxng -q \"linux distros\" --engines \"google,bing\""},{"language":"json","snippet":"{\n \"auto_routing\": {\n \"enabled\": true,\n \"fallback_provider\": \"serper\",\n \"confidence_threshold\": 0.3,\n \"disabled_providers\": []\n },\n \"serper\": {\"country\": \"us\", \"language\": \"en\"},\n \"tavily\": {\"depth\": \"advanced\"},\n \"exa\": {\"type\": \"neural\"},\n \"you\": {\"country\": \"US\", \"include_news\": true},\n \"searxng\": {\"instance_url\": \"https://your-instance.example.com\"}\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: web-search-plus\nversion: 2.8.1\ndescription: Unified search skill with Intelligent Auto-Routing. Uses multi-signal analysis to automatically select between Serper (Google), Tavily (Research), Exa (Neural), Perplexity (AI Answers), You.com (RAG/Real-time), and SearXNG (Privacy/Self-hosted) with confidence scoring.\ntags: [search, web-search, serper, tavily, exa, perplexity, you, searxng, google, research, semantic-search, auto-routing, multi-provider, shopping, rag, free-tier, privacy, self-hosted, kilo]\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"bash\"],\"env\":{\"SERPER_API_KEY\":\"optional\",\"TAVILY_API_KEY\":\"optional\",\"EXA_API_KEY\":\"optional\",\"YOU_API_KEY\":\"optional\",\"SEARXNG_INSTANCE_URL\":\"optional\",\"KILOCODE_API_KEY\":\"optional โ€” required for Perplexity provider (via Kilo Gateway)\"},\"note\":\"Only ONE provider key needed. All are optional.\"}}}\n---\n\n# Web Search Plus\n\n**Stop choosing search providers. Let the skill do it for you.**\n\nThis skill connects you to 6 search providers (Serper, Tavily, Exa, Perplexity, You.com, SearXNG) and automatically picks the best one for each query. Shopping question? โ†’ Google results. Research question? โ†’ Deep research engine. Need a direct answer? โ†’ AI-synthesized with citations. Want privacy? โ†’ Self-hosted option.\n\n---\n\n## โœจ What Makes This Different?\n\n- **Just search** โ€” No need to think about which provider to use\n- **Smart routing** โ€” Analyzes your query and picks the best provider automatically\n- **6 providers, 1 interface** โ€” Google results, research engines, neural search, AI answers with citations, RAG-optimized, and privacy-first all in one\n- **Works with just 1 key** โ€” Start with any single provider, add more later\n- **Free options available** โ€” SearXNG is completely free (self-hosted)\n\n---\n\n## ๐Ÿš€ Quick Start\n\n```bash\n# Interactive setup (recommended for first run)\npython3 scripts/setup.py\n\n# Or manual: copy config and add your keys\ncp config.example.json config.json\n```\n\nThe wizard explains each provider, collects API keys, and configures defaults.\n\n---\n\n## ๐Ÿ”‘ API Keys\n\nYou only need **ONE** key to get started. Add more providers later for better coverage.\n\n| Provider | Free Tier | Best For | Sign Up |\n|----------|-----------|----------|---------|\n| **Serper** | 2,500/mo | Shopping, prices, local, news | [serper.dev](https://serper.dev) |\n| **Tavily** | 1,000/mo | Research, explanations, academic | [tavily.com](https://tavily.com) |\n| **Exa** | 1,000/mo | \"Similar to X\", startups, papers | [exa.ai](https://exa.ai) |\n| **Perplexity** | Via Kilo | Direct answers with citations | [kilo.ai](https://kilo.ai) |\n| **You.com** | Limited | Real-time info, AI/RAG context | [api.you.com](https://api.you.com) |\n| **SearXNG** | **FREE** โœ… | Privacy, multi-source, $0 cost | Self-hosted |\n\n**Setting your keys:**\n\n```bash\n# Option A: .env file (recommended)\nexport SERPER_API_KEY=\"your-key\"\nexport TAVILY_API_KEY=\"your-key\"\n\n# Option B: config.json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## ๐ŸŽฏ Whe"},{"path":"README.md","content":"# Web Search Plus\n\n> Unified multi-provider web search with **Intelligent Auto-Routing** โ€” uses multi-signal analysis to automatically select between **Serper**, **Tavily**, **Exa**, **You.com**, and **SearXNG** with confidence scoring.\n\n[![ClawHub](https://img.shields.io/badge/ClawHub-web--search--plus-blue)](https://clawhub.ai)\n[![Version](https://img.shields.io/badge/version-2.7.0-green)](https://clawhub.ai)\n[![GitHub](https://img.shields.io/badge/GitHub-web--search--plus-blue)](https://github.com/robbyczgw-cla/web-search-plus)\n\n---\n\n## ๐Ÿง  Features (v2.7.0)\n\n**Intelligent Multi-Signal Routing** โ€” The skill uses sophisticated query analysis:\n\n- **Intent Classification**: Shopping vs Research vs Discovery vs RAG/Real-time vs Privacy\n- **Linguistic Patterns**: \"how much\" (price) vs \"how does\" (research) vs \"privately\" (privacy)\n- **Entity Detection**: Product+brand combos, URLs, domains\n- **Complexity Analysis**: Long queries favor research providers\n- **Confidence Scoring**: Know how reliable the routing decision is\n\n```bash\npython3 scripts/search.py -q \"how much does iPhone 16 cost\" # โ†’ Serper (68% confidence)\npython3 scripts/search.py -q \"how does quantum entanglement work\" # โ†’ Tavily (86% HIGH)\npython3 scripts/search.py -q \"startups similar to Notion\" # โ†’ Exa (76% HIGH)\npython3 scripts/search.py -q \"companies like stripe.com\" # โ†’ Exa (100% HIGH - URL detected)\npython3 scripts/search.py -q \"summarize key points on AI\" # โ†’ You.com (68% MEDIUM - RAG intent)\npython3 scripts/search.py -q \"search privately without tracking\" # โ†’ SearXNG (74% HIGH - privacy intent)\n```\n\n---\n\n## ๐Ÿ” When to Use Which Provider\n\n### Built-in Brave Search (OpenClaw default)\n- โœ… General web searches\n- โœ… Privacy-focused\n- โœ… Quick lookups\n- โœ… Default fallback\n\n### Serper (Google Results)\n- ๐Ÿ› **Product specs, prices, shopping**\n- ๐Ÿ“ **Local businesses, places**\n- ๐ŸŽฏ **\"Google it\" - explicit Google results**\n- ๐Ÿ“ฐ **Shopping/images needed**\n- ๐Ÿ† **Knowledge Graph data**\n\n### Tavily (AI-Optimized Research)\n- ๐Ÿ“š **Research questions, deep dives**\n- ๐Ÿ”ฌ **Complex multi-part queries**\n- ๐Ÿ“„ **Need full page content** (not just snippets)\n- ๐ŸŽ“ **Academic/technical research**\n- ๐Ÿ”’ **Domain filtering** (trusted sources)\n\n### Exa (Neural Semantic Search)\n- ๐Ÿ”— **Find similar pages**\n- ๐Ÿข **Company/startup discovery**\n- ๐Ÿ“ **Research papers**\n- ๐Ÿ’ป **GitHub projects**\n- ๐Ÿ“… **Date-specific content**\n\n### You.com (RAG/Real-time)\n- ๐Ÿค– **RAG applications** (LLM-ready snippets)\n- ๐Ÿ“ฐ **Combined web + news** (single API call)\n- โšก **Real-time information** (current events)\n- ๐Ÿ“‹ **Summarization context** (\"What's the latest...\")\n- ๐Ÿ”„ **Live crawling** (full page content on demand)\n\n### SearXNG (Privacy-First/Self-Hosted)\n- ๐Ÿ”’ **Privacy-preserving search** (no tracking)\n- ๐ŸŒ **Multi-source aggregation** (70+ engines)\n- ๐Ÿ’ฐ **$0 API cost** (self-hosted)\n- ๐ŸŽฏ **Diverse perspectives** (results from multiple engines)\n- ๐Ÿ  **Self-hosted environments** (full control)\n\n---\n\n## Table o"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n \"slug\": \"web-search-plus\",\n \"version\": \"2.8.5\",\n \"publishedAt\": 1771603102076\n}"},{"path":"CHANGELOG.md","content":"# Changelog - Web Search Plus\n\n## [2.8.5] - 2026-02-20\n\n### โœจ Feature: Perplexity freshness filter\n\n- Added `freshness` parameter to Perplexity provider (`day`, `week`, `month`, `year`)\n- Maps to Perplexity's native `search_recency_filter` parameter\n- Example: `python3 scripts/search.py -p perplexity -q \"latest AI news\" --freshness day`\n- Consistent with freshness support in Serper and Brave providers\n\n## [2.8.4] - 2026-02-20\n\n### ๐Ÿ”’ Security Fix: SSRF protection in setup wizard\n\n- **Fixed:** `setup.py` SearXNG connection test had no SSRF protection (unlike `search.py`)\n- **Before:** Operator could be tricked into probing internal networks during setup\n- **After:** Same IP validation as `search.py` โ€” blocks private IPs, cloud metadata, loopback\n- **Credit:** ClawHub security scanner\n\n## [2.8.3] - 2026-02-20\n\n### ๐Ÿ› Critical Fix: Perplexity results empty\n\n- **Fixed:** Perplexity provider returned 0 results because the AI-synthesized answer wasn't mapped into the results array\n- **Before:** Only extracted URLs from the answer text were returned as results (often 0)\n- **After:** The full answer is now the primary result (title, snippet with cleaned text), extracted source URLs follow as additional results\n- **Impact:** Perplexity queries now always return at least 1 result with the synthesized answer\n\n## [2.8.0] - 2026-02-20\n\n### ๐Ÿ†• New Provider: Perplexity (AI-Synthesized Answers)\n\nAdded Perplexity as the 6th search provider via Kilo Gateway โ€” the first provider that returns **direct answers with citations** instead of just links:\n\n#### Features\n- **AI-Synthesized Answers**: Get a complete answer, not a list of links\n- **Inline Citations**: Every claim backed by `[1][2][3]` source references\n- **Real-Time Web Search**: Perplexity searches the web live, reads pages, and summarizes\n- **Zero Extra Config**: Works through Kilo Gateway with your existing `KILOCODE_API_KEY`\n- **Model**: `perplexity/sonar-pro` (best quality, supports complex queries)\n\n#### Auto-Routing Signals\nNew direct-answer intent detection routes to Perplexity for:\n- Status queries: \"status of\", \"current state of\", \"what is the status\"\n- Local info: \"events in [city]\", \"things to do in\", \"what's happening in\"\n- Direct questions: \"what is\", \"who is\", \"when did\", \"how many\"\n- Current affairs: \"this week\", \"this weekend\", \"right now\", \"today\"\n\n#### Usage Examples\n```bash\n# Auto-routed\npython3 scripts/search.py -q \"events in Graz Austria this weekend\" # โ†’ Perplexity\npython3 scripts/search.py -q \"what is the current status of Ethereum\" # โ†’ Perplexity\n\n# Explicit\npython3 scripts/search.py -p perplexity -q \"latest AI regulation news\"\n```\n\n#### Configuration\nRequires `KILOCODE_API_KEY` environment variable (Kilo Gateway account).\nNo additional API key needed โ€” Perplexity is accessed through Kilo's unified API.\n\n```bash\nexport KILOCODE_API_KEY=\"your-kilo-key\"\n```\n\n### ๐Ÿ”ง Routing Rebalance\n\nMajor overhaul of the auto-routing confidence scoring to fix Serper dominance:\n\n#### Problem\nSerper (G"},{"path":"FAQ.md","content":"# Frequently Asked Questions\n\n## Caching (NEW in v2.7.0!)\n\n### How does caching work?\nSearch results are automatically cached locally for 1 hour (3600 seconds). When you make the same query again, you get instant results at $0 API cost. The cache key is based on: query text + provider + max_results.\n\n### Where are cached results stored?\nIn `.cache/` directory inside the skill folder by default. Override with `WSP_CACHE_DIR` environment variable:\n```bash\nexport WSP_CACHE_DIR=\"/path/to/custom/cache\"\n```\n\n### How do I see cache stats?\n```bash\npython3 scripts/search.py --cache-stats\n```\nThis shows total entries, size, oldest/newest entries, and breakdown by provider.\n\n### How do I clear the cache?\n```bash\npython3 scripts/search.py --clear-cache\n```\n\n### Can I change the cache TTL?\nYes! Default is 3600 seconds (1 hour). Set a custom TTL per request:\n```bash\npython3 scripts/search.py -q \"query\" --cache-ttl 7200 # 2 hours\n```\n\n### How do I skip the cache?\nUse `--no-cache` to always fetch fresh results:\n```bash\npython3 scripts/search.py -q \"query\" --no-cache\n```\n\n### How do I know if a result was cached?\nThe response includes:\n- `\"cached\": true/false` โ€” whether result came from cache\n- `\"cache_age_seconds\": 1234` โ€” how old the cached result is (when cached)\n\n---\n\n## General\n\n### How does auto-routing decide which provider to use?\nMulti-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.\n\n### What if it picks the wrong provider?\nOverride with `-p serper/tavily/exa`. Check `--explain-routing` to understand why it chose differently.\n\n### What does \"low confidence\" mean?\nQuery is ambiguous (e.g., \"Tesla\" could be cars, stock, or company). Falls back to Serper. Results may vary.\n\n### Can I disable a provider?\nYes! In config.json: `\"disabled_providers\": [\"exa\"]`\n\n---\n\n## API Keys\n\n### Which API keys do I need?\nAt minimum ONE key (or SearXNG instance). You can use just Serper, just Tavily, just Exa, just You.com, or just SearXNG. Missing keys = that provider is skipped.\n\n### Where do I get API keys?\n- Serper: https://serper.dev (2,500 free queries, no credit card)\n- Tavily: https://tavily.com (1,000 free searches/month)\n- Exa: https://exa.ai (1,000 free searches/month)\n- You.com: https://api.you.com (Limited free tier for testing)\n- SearXNG: Self-hosted, no key needed! https://docs.searxng.org/admin/installation.html\n\n### How do I set API keys?\nTwo options (both auto-load):\n\n**Option A: .env file**\n```bash\nexport SERPER_API_KEY=\"your-key\"\n```\n\n**Option B: config.json** (v2.2.1+)\n```json\n{ \"serper\": { \"api_key\": \"your-key\" } }\n```\n\n---\n\n## Routing Details\n\n### How do I know which provider handled my search?\nCheck `routing.provider` in JSON output, or `[๐Ÿ” Searched with: Provider]` in chat responses.\n\n### Why does it sometimes choose Serper for research questions?\nIf the query has brand/"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1875,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"agent-directory","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:00:18.442Z","emptyReason":"No close protocol neighbors were found."},"items":[],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[]}}}