web-search-plus-plugin-v2
OpenClaw plugin for source-only Routing v2 multi-provider search, completion-order Research with quality quorum and attributed provenance, heading-aware extraction spans, Tavily-first extraction, explicit-only Octen/TinyFish, optional separately installed DonSeTch through the OpenClaw host runner, process-local health, routing preferences, and extraction benchmarks. Registers five optional web tools.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/robbyczgw-cla--web-search-plus-plugin)HTML
<a href="/listings/robbyczgw-cla--web-search-plus-plugin"><img src="/api/listings/robbyczgw-cla--web-search-plus-plugin/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 120 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: web-search-plus-plugin-v2
- version: 4.4.0
- description: OpenClaw plugin for source-only Routing v2 multi-provider search, completion-order Research with quality quorum and attributed provenance, heading-aware extraction spans, Tavily-first extraction, explicit-only Octen/TinyFish, optional separately installed DonSeTch through the OpenClaw host runner, process-local health, routing preferences, and extraction benchmarks. Registers five optional web tools.
- ---
- # Web Search Plus Plugin
- Use this OpenClaw plugin for current web search, multi-provider research, URL extraction, routing configuration, provider health, and bounded extraction benchmarks. `web_answer_plus` is not part of the source-only surface; use Search plus Extract.
- ## Enable the optional tools
- The plugin registers all five tools with `optional: true`:
- - `web_search_plus`
- - `web_extract_plus`
- - `web_routing_config_plus`
- - `web_search_health_plus`
- - `web_extract_benchmark_plus`
- They must be permitted by OpenClaw's tool policy. Add the exact tools the agent needs without replacing its existing profile:
- ```json
- {
- "tools": {
- "alsoAllow": [
- "web_search_plus",
- "web_extract_plus",
- "web_routing_config_plus",
- "web_search_health_plus",
- "web_extract_benchmark_plus"
- ]
- }
- }
- ```
- For least privilege, remove any names the agent does not need. `tools.alsoAllow` is additive. `tools.allow` is the restrictive alternative and must also retain every non-plugin tool the agent needs. A configured `plugins.allow` is separate and must include `web-search-plus-plugin-v2` so the plugin can load.
- ## Good starter setup
- Start with one or more of Brave, Serper, and Exa. Tavily is first in the default extraction order:
- Tavily → Exa → Linkup → Parallel → Firecrawl → You.com → Keenable → Serper → DonSeTch.
- DonSeTch appears last in the stable extraction priority but is skipped by automatic routing until an operator explicitly enables its `auto_allow` gate. Extraction targets reject private/internal destinations by default. Inline content uses deterministic URL/context limits, and full-text continuation references live only in the process-local LRU until eviction or host restart.
- Use `spans=true` for deterministic, query-conditioned passages. A query-matching ATX Markdown heading retains its body and deeper subheadings through the next same-or-shallower heading. At most two heading sections are added, each capped at 1,200 Unicode codepoints. Offsets are NFC Unicode-codepoint half-open ranges; `within_preview` reports whether a span is present in the inline preview.
- ## Provider configuration
- Hosted Search credentials/settings:
- - `serperApiKey`, `braveApiKey`, `tavilyApiKey`, `exaApiKey`
- - `queritApiKey`, `linkupApiKey`, `firecrawlApiKey`
- - `parallelApiKey`, `serpbaseApiKey`, `youApiKey`
- - `searxngInstanceUrl`, `keenableApiKey`
- - `monidApiKey` for Octen via Monid
- - `tinyfishApiKey`
- Local provider:
- - `donsetchBin` — absolute path to a separately installed DonSeTch executable
- Important controls:
- - `parallelMode`: `turbo`, `fast` (default), `basic`, or `advanced`; Parallel uses its stable v1 Search endpoint and is auto-allowed when configured
- - `octenTimeoutSeconds`, `tinyfishTimeoutSeconds`
- - `donsetchTimeoutSeconds`, `donsetchMaxContentChars`, `donsetchTier`
- - `keenableAllowPublic`, `searxngAllowPrivate`, `extractAllowPrivateUrls`
- - `extractCharLimit`, `extractMaxUrls`, `extractMaxContextChars`, `extractDeadlineSeconds`
- - `extractCacheMaxEntries`, `extractCacheMaxChars`
- - `localeCountry`, `localeLanguage`
- - `parallelMaxCharsPerResult`, `parallelMaxCharsTotal`
- - `qualityBlockedDomains`, `qualityAllowedDomains`, `qualityDiversityRerank`
- OpenClaw plugin config is the only credential source; this package does not discover `.env` files.
- ## Provider boundaries
- - Exa exposes source-only neural `/search`. Unified `day|week|month|year` freshness becomes absolute UTC publication-date bounds. Deep, deep-reasoning, answer, and synthesis output are not exposed.
- - Parallel uses stable v1 Search with `fast` as the default mode and participates in normal automatic routing when configured.
- - Octen via Monid and TinyFish are Search-only and explicit-only by default. Both support freshness and domain filters; TinyFish also supports native news and locale.
- - TinyFish's standard [Terms](https://www.tinyfish.ai/terms) permit Customer Data, including queries, to be used for model training and fine-tuning. Explicit-only is not a privacy guarantee. Review its [Privacy Policy](https://www.tinyfish.ai/privacy-policy) and the terms applicable to your account before sending sensitive data.
- ## DonSeTch
- Install the independent AGPL-3.0-only DonSeTch 4.7.0 package separately:
- ```bash
- npm install -g donsetch@4.7.0
- command -v donsetch
- donsetch --version
- donsetch doctor
- ```
- Set `donsetchBin` to the absolute executable path. Web Search Plus passes the bounded `[donsetchBin, "mcp"]` invocation to OpenClaw's trusted `api.runtime.system.runCommandWithTimeout` host runner; the plugin does not bundle DonSeTch or own a shell/process implementation. One stdio MCP session serves one Web Search Plus request, including every URL in a multi-URL extraction. Credentials unrelated to DonSeTch are removed from the child environment, outputs and diagnostics are bounded/sanitized, and browser success remains dependent on the host's Chrome/Chromium/display setup.
- Use `provider="donsetch"` explicitly first. Only after verifying the target host should an operator call `web_routing_config_plus(action="set_auto_allow", provider="donsetch", enabled=true)`.
- ## Routing v2
- Automatic routing picks the first provider by query intent (Hermes Web Search Plus 5.0 table): Exa for docs and academic queries, Serper for security and shopping, Brave for everything else (general, news, local, community). Fallback: Brave → Serper → Exa → Tavily → `provider_priority`. `provider_priority` orders the rest of the fallback chain; to use your own order for every query set `provider_order` to `custom` (`web_routing_config_plus(action="set_provider_order", order="custom")`, reason `custom_order`).
- Default search priority: Brave → Serper → Exa → Tavily → You.com → Firecrawl → Linkup → Parallel → SerpBase → Querit → SearXNG → Keenable.
- SerpBase, Querit, DonSeTch, Octen, and TinyFish are guarded by `auto_allow=false`; Brave and Parallel are in the normal automatic pool. Search and extraction priorities are independent. The `self_hosted` profile derives SearXNG/Keenable automatic pools while preserving explicit configured-provider calls.
- Use `quality_report=true` for routing, authority, diversity, fallback, and result-quality diagnostics. Provider health and shadow-quality state are process-local and disappear on restart.
- ## Research mode
- `web_search_plus(mode="research")` launches up to three providers concurrently and harvests completions as they arrive. Public results, attempts, and errors remain in deterministic submission order.
- The default quality quorum can stop waiting once at least two providers contribute `min(count, 5)` unique candidates across `min(result_target, 3)` domains. Pending providers remain visible as `preempted_after_quorum`; `metadata.research_quorum` reports the decision. Explicit `research_providers` are explicit choices rather than automatic-routing candidates, while disabled/unconfigured providers remain ineligible.
- Canonical-URL clusters preserve deterministic observation ids and attributed snippet fragments instead of discarding duplicate-provider evidence. Each Research result adds provider-neutral `source_type` and explainable `fetch_priority` hints; these are routing/fetch cues, not truth claims. `research_time_budget` still gates launch, completion waits, and extraction.
- ## Usage guidance
- Prefer `web_search_plus` for current information and finding sources. Use `mode="research"` when a question benefits from cross-provider evidence and extracted source summaries. Use `web_extract_plus` when URLs are already known. Use the routing/health/benchmark tools only when the host has explicitly allowed them and their diagnostics are needed.
README.md · README · 308 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Web Search Plus Plugin
- <p align="center">
- <img src="docs/assets/web-search-plus-logo.png" alt="web search plus logo" width="180">
- </p>
- 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`:
- ```json
- {
- "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
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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](https://www.tinyfish.ai/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](https://www.tinyfish.ai/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:
- ```json
- {
- "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`.
- | Plugin routing class | 5.0 intent | First provider |
- | --- | --- | --- |
- | docs/api | docs | Exa |
- | academic/arxiv | academic | Exa |
- | security/cve | security | Serper |
- | local/shopping with buy/price/shop words | shopping | Serper |
- | local/shopping otherwise (near me, place names) | local | Brave |
- | community/reddit | community | Brave |
- | multilingual/current | news | Brave |
- | everything else (official/*, finance/IR, weather/factual, oss-discovery, answer/synthesis, general) | general | Brave |
- 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.
- ```json
- {
- "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:
- ```bash
- npm test -- --test-reporter=spec
- npm run build
- npm pack --dry-run
- ```
- ## Contributing
- See [CONTRIBUTING.md](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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.