Web Search Plus Plugin

Native OpenClaw source-only plugin for one clean set of web tools.

Current version: 4.4.0

Search accepts no_cache to bypass cache reads and writes and cache_ttl in seconds. Recency caps are 60 seconds for hour/live, 300 for day/latest, 1800 for week, and 3600 otherwise. time_range wins over freshness; the stricter query-intent cap still applies. Cached responses include age and a recency label. Research source summaries keep up to 500 characters, preferring query-matching evidence.

Set defaults.max_results in plugin config to choose the default search count. Explicit count wins; counts clamp to 1–20. Adaptive routing records every search attempt, including retries, in process memory.

It registers:

• web_search_plus — Intent-routed multi-provider web search with research mode and canonical-source reranking
• web_extract_plus — Tavily-first URL extraction across supported providers
• web_routing_config_plus — process-local routing preferences, valid until host restart
• web_search_health_plus — read-only process-local provider health and shadow-quality observations
• web_extract_benchmark_plus — explicit bounded extraction-provider benchmark with a process-local recommendation

web_answer_plus is removed in v3.0.0. Use search plus extraction; fewer tools, less mush.

All five tools are registered as optional OpenClaw tools. Installing or enabling the plugin does not by itself make them callable. Add the exact tools you want to the host's existing tool profile with tools.alsoAllow:

{
  "tools": {
    "alsoAllow": [
      "web_search_plus",
      "web_extract_plus",
      "web_routing_config_plus",
      "web_search_health_plus",
      "web_extract_benchmark_plus"
    ]
  }
}

List only the tools the agent needs. tools.alsoAllow is additive; it does not replace profile-derived or existing tools. Use tools.allow only when you intentionally want a restrictive absolute allowlist, in which case it must include these exact names plus every other tool the agent requires. plugins.allow is a separate plugin-load gate: if it is present, include web-search-plus-plugin-v2 there as well.

Install

openclaw plugins install clawhub:web-search-plus-plugin-v2

ClawHub: https://clawhub.ai/plugins/web-search-plus-plugin-v2 Source: https://github.com/robbyczgw-cla/web-search-plus-plugin

Quick setup

You only need one provider configured to start. The recommended starter stack is:

• You.com for fast snippets / factual queries
• Serper for Google-style local, shopping, and community search
• Linkup for source-grounded search and citations

Onboarding CLI:

web-search-plus-setup status --config ./web-search-plus-plugin.config.json
web-search-plus-setup list providers
web-search-plus-setup list presets
web-search-plus-setup setup --preset starter --config ./web-search-plus-plugin.config.json
web-search-plus-setup config --config ./web-search-plus-plugin.config.json --set routingConfigPath=memory:default

Runtime credentials still come from explicit OpenClaw plugin config fields. The CLI writes a JSON helper file for setup/onboarding, not runtime secret discovery.

Provider coverage

Search providers

• Serper — Google-style web/news/shopping/local
• Brave — independent-index current web and multilingual search in the default auto pool
• Tavily — source-result search; generated-answer output is disabled
• Exa — source-only neural search for docs/API and arXiv sources with native freshness bounds; synthesis/deep modes are not exposed
• Querit — multilingual/current AI search; guarded in auto routing
• Linkup — citation/source-grounded search
• Firecrawl — search with scrape-friendly metadata and vendor/source pages
• Parallel — stable v1 source search and extraction; fast mode by default and part of the normal auto pool when configured
• SerpBase — Google-style alternate search; guarded in auto routing
• You.com — current web / RAG-style snippets
• SearXNG — self-hosted metasearch
• Keenable — independent web index; keyed or opt-in keyless public tier, lowest-priority fallback
• Octen via Monid — source-only search with freshness and domain filters; explicit-only by default
• TinyFish — source-only web/news search with freshness, locale, and domain filters; BYOK and explicit-only by default
• DonSeTch — separately installed local stdio MCP source search and Markdown extraction; explicit-only by default

Extraction providers

Auto fallback order:

• Tavily
• Exa
• Linkup
• Parallel
• Firecrawl
• You.com
• Keenable (keyed or opt-in keyless public tier)
• Serper (webpage scraper via scrape.serper.dev, last resort)
• DonSeTch (separately installed local provider; skipped automatically until deliberately auto-allowed)

Tavily is the default first call because it was the fastest reliable benchmark head; Firecrawl stays the robust scraper safety net. Extraction targets are validated against private/internal destinations by default (see extractAllowPrivateUrls). Calls process at most 10 URLs and return at most 60,000 aggregate Unicode codepoints by default; max_urls and max_context_chars may request lower limits, while extractMaxUrls and extractMaxContextChars set operator ceilings. The aggregate budget first selects a deterministic prefix; extractCharLimit then turns an oversized prefix into the documented head/tail window with a truncation marker. Inline base64 images are replaced with [IMAGE: alt] placeholders. Inline raw_content mirrors the final budgeted content; a distinct provider raw text is retained only behind full_content_ref. Call web_extract_plus with that reference plus content_start/content_end to read a content range (at most 60,000 Unicode codepoints). When distinct provider raw text exists, the reference read reports its availability and length; request it with its own raw_content_start/raw_content_end range. The reference is only valid while its process-local cache entry remains in the LRU; restart or eviction expires both ranges.

Set spans: true to add up to three deterministic, non-overlapping passages per successful result. spans_query conditions lexical ranking. A query-matching ATX Markdown heading can retain its query-free body and deeper subheadings through the next same-or-shallower heading; heading candidates are capped at two sections and 1,200 Unicode codepoints each. Span offsets address the complete cleaned NFC text in Unicode codepoints using half-open [start,end) ranges; within_preview reports whether the selected text survived inline truncation.

DonSeTch installation and OpenClaw host runner

DonSeTch is not bundled or redistributed by this plugin. It is an independent AGPL-3.0-only component and must be installed and reviewed separately. The adapter is tested with DonSeTch 4.7.0:

npm install -g donsetch@4.7.0
command -v donsetch
donsetch --version
donsetch doctor

Set donsetchBin to the absolute path printed by command -v donsetch. The plugin does not spawn through a shell or import its own process runner. It delegates the exact executable invocation to OpenClaw's trusted api.runtime.system.runCommandWithTimeout host runner, sends one bounded stdio MCP session per Web Search Plus request, and reuses that session for all URLs in a multi-URL extraction. The adapter isolates unrelated provider credentials, bounds time/output/content, sanitizes diagnostics, and treats browser or anti-bot success as host-dependent. Chromium/Chrome and display infrastructure may still be required by DonSeTch on Linux.

Installing DonSeTch does not put it into automatic traffic. Use it explicitly with provider: "donsetch"; after local verification, opt it in with web_routing_config_plus(action="set_auto_allow", provider="donsetch", enabled=true). Search queries and fetched URLs can still reach public engines and target sites even though the control-plane process is local.

TinyFish data-use warning

TinyFish's standard Terms permit Customer Data, including queries, to be used for analytics, model training, and fine-tuning. Explicit-only routing is a traffic-control default, not a privacy guarantee. Review the current Terms and Privacy Policy, and do not send sensitive data unless your own contract provides acceptable protections.

Configuration

web_search_health_plus is a read-only tool for the adaptive provider samples collected by the current host process. It reports its process start time and only in-process observations; it does not run an HTTP server or retain history after restart.

The same tool includes passive shadow-quality aggregates from completed successful search requests (result/domain counts, thin snippets, and degraded outcomes). They are observational only and never change routing or returned sources.

Use routing_override_provider on web_search_plus or web_extract_plus to force a configured provider for one call and disable automatic selection. The response's routing.override_provider makes that override explicit.

web_extract_benchmark_plus is the only way to benchmark extraction providers. It is never automatic, has a hard limit of one to three provider calls, bypasses the cache, and returns a process-local recommended priority. Explicit-only providers such as DonSeTch remain excluded unless their auto_allow gate is enabled.

Use explicit OpenClaw plugin config fields. The runtime uses only plugin config fields for credentials.

Search provider fields

• serperApiKey
• braveApiKey
• tavilyApiKey
• exaApiKey
• queritApiKey
• linkupApiKey
• firecrawlApiKey
• parallelApiKey
• serpbaseApiKey
• youApiKey
• searxngInstanceUrl
• keenableApiKey
• monidApiKey — Octen access through Monid
• tinyfishApiKey
• donsetchBin — absolute path to the separately installed DonSeTch executable

Extra fields

• braveSafesearch
• searxngAllowPrivate
• routingConfigPath — optional namespace for in-memory routing preferences
• keenableAllowPublic — opt-in keyless Keenable public tier (unauthenticated shared service, off by default)
• parallelMode — Parallel stable v1 Search mode: turbo, fast (default), basic, or advanced
• octenTimeoutSeconds / tinyfishTimeoutSeconds — bounded hosted-provider request timeouts
• donsetchTimeoutSeconds / donsetchMaxContentChars / donsetchTier — bounded host-runner timeout, extraction content, and browser tier (auto, 1, or 2)
• extractAllowPrivateUrls — opt-in: allow extraction of private/internal URLs (trusted intranets only)
• extractCharLimit — per-result inline character budget applied after aggregate prefix allocation and before head/tail truncation (default 15000)
• extractMaxUrls — operator ceiling for URLs processed per extraction call (default 10, hard maximum 50)
• extractMaxContextChars — operator ceiling for aggregate inline extraction content (default 60000 Unicode codepoints, maximum 200000)
• extractCacheMaxEntries — process-local LRU capacity for completed extraction requests (default 64, range 1–500; lost on host restart)
• extractCacheMaxChars — process-local full-text cache budget in Unicode codepoints (default 4,000,000, range 1–20,000,000); an oversized response is returned normally but has no full_content_ref
• extractDeadlineSeconds — request-scoped provider-start deadline ceiling (default 30 seconds, range 1–180); no daily quota is kept because that would require a persistent ledger
• localeCountry / localeLanguage — default search locale for Serper, Brave, Querit, Firecrawl, You.com, and SearXNG; localeLanguage: "auto" enables conservative query language inference. Explicit location hints in the query win the country; query language never implies the country. Without these fields the providers keep their us/en defaults.
• parallelMaxCharsPerResult / parallelMaxCharsTotal — Parallel extraction full-content budgets (defaults 60000 / 120000)
• qualityBlockedDomains / qualityAllowedDomains — extend or rescue from the built-in spam/mirror result blocklist

Example:

{
  "plugins": {
    "entries": {
      "web-search-plus-plugin-v2": {
        "config": {
          "youApiKey": "...",
          "serperApiKey": "...",
          "linkupApiKey": "..."
        }
      }
    }
  }
}

Routing v2

web_search_plus(provider="auto") picks the first provider by query intent, using the Hermes Web Search Plus 5.0 first-provider table. The plugin keeps its own query classes and maps them onto the 5.0 intents (it does not port Hermes' intent classifier). Diagnostics expose routing_class (plugin class), routing_intent (5.0 intent), provider_order, reason, language_hint and routing_policy.

The first provider is the first one in that list that is configured, enabled and auto-allowed. Fallback order: first provider, then Brave, Serper, Exa, Tavily, then provider_priority. routing_class still drives authority reranking, so the authority rules for docs, security, vendor releases, regulatory pages and finance IR pages are unchanged.

Your own order: provider_order is an explicit setting in the routing preferences (routingPreferences.provider_order in plugin config, or web_routing_config_plus(action="set_provider_order", order="custom")). With measured (the default) the intent table above picks the first provider and provider_priority orders the rest of the fallback chain after Brave, Serper, Exa and Tavily. With custom, provider_priority is the order for every query (reason: custom_order, provider_order: custom), for example set_provider_priority providers=["exa","serper","brave"] followed by set_provider_order order="custom". Setting only provider_priority does not switch to custom. A stored 4.x default provider_priority is replaced by the new default. action="reset" returns to measured. An explicit fallback_provider other than the default serper is tried right after the first provider. confidence_threshold and adaptive scoring no longer influence the first provider.

Default search priority is Brave, Serper, Exa, Tavily, You.com, Firecrawl, Linkup, Parallel, SerpBase, Querit, SearXNG, then Keenable. Configured Parallel and Brave are in the normal automatic pool; operators can still opt either out with auto_allow=false.

Guarded providers require auto_allow=true for automatic traffic: SerpBase, Querit, DonSeTch, Octen, and TinyFish. Explicit calls remain available when the provider is configured and enabled. This gate is operational policy, not a privacy or contractual guarantee.

Search provider_priority and extraction extract_provider_priority are independent. Partial extraction lists are completed in the public Tavily-first order, and can be updated with web_routing_config_plus(action="set_extract_provider_priority", providers=[...]).

web_routing_config_plus(action="set_profile", profile="self_hosted") derives a local-first routing view: SearXNG then Keenable for search, and Keenable first for extraction. Other providers are excluded from automatic selection and fallback but remain available when explicitly requested. Auto mode fails with a clear readiness error until searxngInstanceUrl, keenableApiKey, or the opted-in Keenable public tier is configured. Return to the normal pool with profile="standard". The setup CLI also exposes --preset self-hosted.

Pass quality_report: true to receive routing scores, result-quality hints, fallback-chain diagnostics, authority_signals (canonical domain hits, demoted domain hits, and whether the top result is a primary source), and a deterministic diversity score. The score combines registrable-domain coverage, canonical-URL uniqueness, snippet-trigram diversity, and provider mix. Set qualityDiversityRerank: true to move near-duplicate Research candidates behind the diverse head without removing results.

Every call still records latency, result volume, and errors into an in-memory rolling window for web_search_health_plus. Since 4.4.0 these samples no longer adjust routing scores (Hermes removed adaptive routing in 5.0).

Result hygiene

Results from known SEO mirror/scraper domains (Stack Overflow clones, GitHub issue mirrors, documentation mirrors) are removed, and a single domain is capped at two head slots via a stable diversity rerank (overflow is demoted, not dropped). Explicit site: queries and include_domains bypass both. Removals and demotions are reported in metadata.result_filter.

Freshness, news vertical, and locale

• freshness: day|week|month|year maps to each provider's native recency filter; providers without one run normally and report freshness.applied=false in metadata. Exa translates the unified value into absolute UTC startPublishedDate/endPublishedDate bounds for /search and reports the effective range.
• search_type: news uses Serper's native /news endpoint (with date, source, thumbnail, and position metadata); other providers report search_type.applied=false.
• localeCountry/localeLanguage set default region and language for the locale-capable providers, with query-aware language inference when localeLanguage: "auto". The resolved locale and its per-value source are reported in metadata.locale.

Canonical-source reranking

For routing classes where source authority beats snippet luck (official/vendor-release, docs/api, official/regulatory, finance/IR, security/cve), auto-routed results are reranked so primary sources (vendor blogs, official docs, regulators, IR pages, NVD/CVE records) outrank mirrors like YouTube, Medium, or Reddit. When the order changes, metadata.intent_rerank reports the routing class and the top domain before/after.

Research mode

web_search_plus(mode="research") runs a compact multi-provider sweep for grounding-heavy questions:

1. Picks up to 3 configured, auto-allowed providers (primary route first, then Linkup/Tavily/Exa/Firecrawl/… by preference), or uses an explicit research_providers list.
2. Queries them concurrently and harvests completions as they arrive, so a blocked earlier submission cannot hide a later useful provider. Final results, attempts, and diagnostics are restored to deterministic submission order.
3. Deduplicates canonical URLs without discarding contributing observations. Cross-provider clusters retain deterministic observation ids and attributed snippet fragments, plus transparent source_type and fetch_priority hints.
4. Extracts the top research_extract_count URLs (default 3, max 5) via web_extract_plus auto fallback into source_summaries.

Research mode is best-effort: each launched/skipped provider is recorded in routing.provider_attempts; provider or extraction failures produce diagnostics in routing.provider_errors / routing.extraction_error. Partial evidence returns status="degraded", while total fan-out failure returns a complete status="failed" envelope. A research_time_budget (seconds, default 55) gates launches, cancels the response wait for started overruns, and gates extraction. Quality reports are attached once after the merge. Optional qualityDiversityRerank moves later URL/content duplicate candidates behind the diverse result head before source extraction.

The 3.3 quality quorum is enabled by default. Once at least two providers have contributed the unique-result target (min(count, 5)) across the unique-domain target (min(result_target, 3)), still-pending work may be preempted. Such providers remain visible as preempted_after_quorum; this optimization does not degrade an otherwise successful response. metadata.research_quorum reports the thresholds, contributors, unique result/domain counts, and whether the quorum triggered.

{
  "query": "What changed in the EU AI Act enforcement timeline?",
  "mode": "research",
  "research_extract_count": 3,
  "research_time_budget": 55
}

Routing preferences

web_routing_config_plus manages runtime routing behavior in memory, separate from provider secrets. ClawHub scanner constraints intentionally avoid runtime filesystem reads in this package.

Supported actions:

• show
• set_default_provider
• set_auto_routing
• set_auto_allow
• set_provider_priority
• set_provider_order (order: measured or custom)
• set_extract_provider_priority
• set_profile
• set_fallback_provider
• disable_provider
• enable_provider
• set_confidence_threshold
• reset

Behavior notes:

• if auto_routing=false, provider:auto becomes strict default_provider
• explicit provider requests stay strict and do not silently fall back
• normal auto mode can still use priority order, fallback provider, cooldowns, and retries
• invalid plugin-provided routing config falls back to defaults with a warning
• reset restores in-memory defaults for the selected namespace

Verification

Recommended checks:

npm test -- --test-reporter=spec
npm run build
npm pack --dry-run

Contributing

See CONTRIBUTING.md for the upstream-first porting model, OpenClaw runtime boundaries, provider requirements, security/privacy rules, package synchronization, and pull-request expectations.

Acknowledgments

This OpenClaw plugin tracks the useful feature direction from the Hermes and MCP sister projects, adapted for OpenClaw/ClawHub instead of copied blindly.