这些命令的作用：

• doctor.mjs：运行时现在是否可用？
• bootstrap.mjs：智能体现在可以依赖什么？
• search.mjs：在添加提供商凭据之前，证明基线检索路径成功

选项 B：添加一个高级提供商

如果只添加一个高级提供商，请从 TAVILY_API_KEY 开始。

原因：

• 一个凭据可改善通用网络搜索
• 一个凭据可改善新闻搜索
• 一个凭据可改善提取质量

export TAVILY_API_KEY=tvly-xxxxx
node {baseDir}/scripts/doctor.mjs --json
node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json

首次成功搜索

node {baseDir}/scripts/search.mjs "OpenClaw web search" --json
node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --plan --json
node {baseDir}/scripts/extract.mjs "https://platform.openai.com/docs" --json

然后尝试文档、新闻和研究

node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --json
node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json
node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --plan --json

运行时契约

智能体应将以下字段视为主要的运行时契约。

路由字段

• selectedProvider 规划器的主要路由。它并不意味着“唯一使用的提供商”。
• routingSummary 包含 selectionMode、confidence、topSignals、备选方案、被阻止的提供商和联合摘要的紧凑路由解释。
• routing.diagnostics 由 --explain-routing 或 --plan 暴露的完整路由诊断信息。

联合字段

• federated.providersUsed 当扇出激活时实际返回结果的提供商。
• federated.value.additionalProvidersUsed 真正做出贡献的非主要提供商数量。
• federated.value.resultsRecoveredByFanout 在仅主要提供商模式下会消失的最终结果。
• federated.value.resultsCorroboratedByFanout 得到主要提供商和至少一个扇出提供商支持的最终结果。
• federated.value.duplicateSavings 通过合并移除的精确或近似重复结果。

缓存和执行字段

• cached 结果是否来自缓存。
• cache 缓存年龄 / TTL 遥测数据，用于智能体决策。
• renderLane 浏览器支持渲染通道的运行时可用性和策略摘要。
• failed 当前命令失败的提供商或失败的检索单元。
• meta 命令级别的执行元数据和任务输入塑造。

研究字段

• topicType 研究包的主要主题类别。
• topicSignals 混合主题提示，例如 docs + latest。
• researchAxes 研究包为何分解为给定的一组子问题。
• claimClusters 按规范化主张分组的证据。
• candidateFindings 具有支持概况和差距敏感性的候选结论。
• uncertainties 剩余的不确定性和对后续跟进敏感的差距。

为何联合搜索很重要

联合不仅仅是“更多提供商”。它使多提供商增益可见，以便智能体能够判断扇出是否改善了最终结果集。

重要的增益指标：

• federated.value.additionalProvidersUsed
• federated.value.resultsRecoveredByFanout
• federated.value.resultsCorroboratedByFanout
• federated.value.duplicateSavings
• routingSummary.federation.value

解释：

• 恢复的结果回答“扇出拯救了什么？”
• 确证的结果回答“什么得到了更强的支持？”
• 重复节省回答“合并移除了什么噪音？”

按任务划分的命令

搜索

node {baseDir}/scripts/search.mjs "query" --json
node {baseDir}/scripts/search.mjs "query" --plan --json
node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json
node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --plan --json
node {baseDir}/scripts/search.mjs "query" --engine serpapi --search-engine baidu --json

面向用户的输入：

• searchType 当前已发布的值为 web | news。
• intentPreset 当前已发布的值为 general | code | company | docs | research。

重要边界：

• searchType 和 intentPreset 塑造路由输入
• engine 仍然是显式的提供商覆盖

提取和渲染

node {baseDir}/scripts/extract.mjs "https://example.com/article" --json
node {baseDir}/scripts/extract.mjs "https://example.com/article" --render --render-policy fallback --json
node {baseDir}/scripts/extract.mjs "https://example.com/article" --plan
node {baseDir}/scripts/render.mjs "https://example.com/article" --json

爬取和站点地图

node {baseDir}/scripts/crawl.mjs "https://example.com/docs" --depth 2 --max-pages 10 --json
node {baseDir}/scripts/map.mjs "https://example.com/docs" --depth 2 --max-pages 50 --json

研究

node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --json
node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --plan --json

运行时检查

node {baseDir}/scripts/capabilities.mjs --json
node {baseDir}/scripts/doctor.mjs --json
node {baseDir}/scripts/bootstrap.mjs --json
node {baseDir}/scripts/review.mjs --json
node {baseDir}/scripts/cache.mjs stats --json
node {baseDir}/scripts/health.mjs --json

基准测试

node {baseDir}/scripts/eval.mjs list --json
node {baseDir}/scripts/eval.mjs run --suite core --json
node {baseDir}/scripts/eval.mjs run --suite research --json
node {baseDir}/scripts/eval.mjs run --suite head-to-head --json
node {baseDir}/scripts/eval.mjs run --suite head-to-head-live --json

研究包边界

research.mjs 是一个面向模型的证据层，而不是最终的叙事答案层。

该技能负责：

• 问题分解
• 检索规划
• 证据规范化
• 来源优先级排序
• 主张聚类
• 紧凑的候选发现
• 不确定性暴露

上游模型仍然负责：

• 跨证据包的最终推理
• 叙事综合
• 面向用户的写作风格
• 当证据不完整或冲突时的最终判断

详细契约：

• docs/research-layer.md

运行时配置

默认配置路径：

• {baseDir}/config.json

覆盖路径：

• WEB_SEARCH_PRO_CONFIG=/path/to/config.json

配置优先级：

CLI 标志 > process.env > config.json > 内置默认值

当技能在 OpenClaw 之外直接运行时，提供商密钥必须已存在于 shell 环境中。如果 OpenClaw 启动该技能，其注入的运行时环境就足够了。

关键配置领域：

• routing
• cache
• health
• fetch
• crawl
• render

重要的路由配置字段：

• routing.allowNoKeyBaseline
• routing.enableFederation
• routing.federationTriggers
• routing.maxFanoutProviders
• routing.maxPerProvider
• routing.mergePolicy
• routing.fallbackPolicy

重要的渲染配置字段：

• render.enabled
• render.policy
• render.budgetMs
• render.waitUntil
• render.blockTypes
• render.sameOriginOnly

提供商升级路径

基线不需要 API 密钥。可选的提供商凭据或端点可解锁更强的覆盖范围：

可选的提供商凭据或端点可解锁增强功能。

TAVILY_API_KEY=tvly-xxxxx
EXA_API_KEY=exa-xxxxx
QUERIT_API_KEY=xxxxx
SERPER_API_KEY=xxxxx
BRAVE_API_KEY=xxxxx
SERPAPI_API_KEY=xxxxx
YOU_API_KEY=xxxxx
SEARXNG_INSTANCE_URL=https://searx.example.com

# Perplexity / Sonar: 选择一种传输路径
PERPLEXITY_API_KEY=xxxxx
OPENROUTER_API_KEY=xxxxx
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
KILOCODE_API_KEY=xxxxx

# 或使用自定义的 OpenAI 兼容网关
PERPLEXITY_GATEWAY_API_KEY=xxxxx
PERPLEXITY_BASE_URL=https://gateway.example.com/v1
PERPLEXITY_MODEL=perplexity/sonar-pro

提供商角色：

• Tavily：通用搜索、新闻和提取的最强高级默认选项
• Exa：语义检索和提取回退
• Querit：具有原生地理和语言过滤器的多语言 AI 搜索
• Serper：类似 Google 的搜索，具有强大的新闻和区域覆盖
• Brave：结构化的通用网络搜索
• SerpAPI：包括 Baidu 和 Yandex 在内的多引擎路由
• You.com：面向 LLM 的网络搜索，具有新鲜度和混合的网络/新闻覆盖
• SearXNG：自托管的隐私优先元搜索回退
• Perplexity / Sonar：通过原生或网关传输的答案优先的接地搜索
• DDG：尽力而为的无密钥基线搜索
• Fetch：无密钥提取 / 爬取 / 站点地图基线
• Render：可选的本地浏览器通道

验证与审查

对智能体和维护者最有用的验证界面是：

• capabilities.mjs 此环境现在真正能做什么。
• doctor.mjs 运行时是否就绪、降级或被阻止？
• bootstrap.mjs 上游智能体可以安全地假设什么？
• review.mjs 当前的安全和合规边界是什么？
• health.mjs 哪些提供商已降级或处于冷却期？
• eval.mjs 针对核心、研究或比较套件的行为是否已退化？

捆绑的 head-to-head 套件侧重于与本地 ../web-search-plus 检出进行路由优先比较。

捆绑的 head-to-head-live 套件在共享提供商凭据下，为新鲜度和引用质量添加了真实的网络比较。

审查安全保证

• 元数据仅声明 node 为硬性运行时要求
• 提供商凭据是可选的
• ddg 是尽力而为的无密钥基线，不是保证的高召回率提供商
• 安全提取拒绝非 HTTP(S)、携带凭据、本地、私有和元数据目标
• 重定向目标会重新验证
• 安全提取保持 JavaScript 执行禁用
• 浏览器渲染是可选的，默认关闭
• 浏览器渲染仅在启用时使用本地无头浏览器
• 浏览器渲染将反机器人或挑战性插页报告为失败，而不是静默成功
• 提供商健康状态区分 degraded 和 cooldown

文档

• README.md
• docs/research-layer.md
• docs/search-routing-model.md
• docs/search-ux-model.md
• docs/head-to-head-eval.md
• docs/clawhub-package.md
• docs/clawhub-compliance.md

每周安装数

108

仓库

zjianru/web-search-pro

首次出现

2026年2月10日

安全审计

Gen Agent Trust HubPassSocketWarnSnykWarn

安装于

codex102

openclaw100

kimi-cli100

opencode100

github-copilot99

amp99

Baseline roles:

• ddg: best-effort web search

• fetch: no-key extract / crawl / map fallback

  node {baseDir}/scripts/doctor.mjs --json node {baseDir}/scripts/bootstrap.mjs --json node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --json

What these commands are for:

• doctor.mjs: is the runtime usable right now?
• bootstrap.mjs: what can the agent rely on right now?
• search.mjs: prove the baseline retrieval path succeeds before adding provider credentials

Option B: Add one premium provider

If only one premium provider is added, start with TAVILY_API_KEY.

Reason:

• one credential improves general web search

• one credential improves news search

• one credential improves extract quality

  export TAVILY_API_KEY=tvly-xxxxx node {baseDir}/scripts/doctor.mjs --json node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json

First successful searches

node {baseDir}/scripts/search.mjs "OpenClaw web search" --json
node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --plan --json
node {baseDir}/scripts/extract.mjs "https://platform.openai.com/docs" --json

Then try docs, news, and research

node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --json
node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json
node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --plan --json

Runtime Contract

The agent should treat these fields as the primary runtime contract.

Routing fields

• selectedProvider The planner's primary route. It does not mean "the only provider used".
• routingSummary Compact route explanation with selectionMode, confidence, topSignals, alternatives, blocked providers, and federation summary.
• routing.diagnostics Full route diagnostics exposed by --explain-routing or --plan.

Federation fields

• federated.providersUsed Providers that actually returned results when fanout is active.
• federated.value.additionalProvidersUsed Number of non-primary providers that really contributed.
• federated.value.resultsRecoveredByFanout Final results that would disappear in primary-only mode.
• federated.value.resultsCorroboratedByFanout Final results supported by both the primary and at least one fanout provider.
• federated.value.duplicateSavings Exact or near-duplicate results removed by merge.

Cache and execution fields

• cached Whether the result came from cache.
• cache Cache age / TTL telemetry for agent decisions.
• renderLane Runtime availability and policy summary for the browser-backed render lane.
• failed Failed providers or failed retrieval units for the current command.
• meta Command-level execution metadata and task input shaping.

Research fields

• topicType Primary topic class for the research pack.
• topicSignals Mixed-topic hints such as docs + latest.
• researchAxes Why the research pack decomposed into a given set of subquestions.
• claimClusters Evidence grouped by normalized claim.
• candidateFindings Candidate conclusions with support profile and gap sensitivity.
• uncertainties Remaining uncertainty and follow-up-sensitive gaps.

Why Federated Search Matters

Federation is not just "more providers". It makes multi-provider gain visible so an agent can tell whether fanout improved the final result set.

Important gain metrics:

• federated.value.additionalProvidersUsed
• federated.value.resultsRecoveredByFanout
• federated.value.resultsCorroboratedByFanout
• federated.value.duplicateSavings
• routingSummary.federation.value

Interpretation:

• recovered results answer "what did fanout rescue?"
• corroborated results answer "what got stronger support?"
• duplicate savings answer "what noise did merge remove?"

Commands By Task

Search

node {baseDir}/scripts/search.mjs "query" --json
node {baseDir}/scripts/search.mjs "query" --plan --json
node {baseDir}/scripts/search.mjs "latest OpenAI news" --type news --json
node {baseDir}/scripts/search.mjs "OpenAI Responses API docs" --preset docs --plan --json
node {baseDir}/scripts/search.mjs "query" --engine serpapi --search-engine baidu --json

User-facing inputs:

• searchType Current shipped values are web | news.
• intentPreset Current shipped values are general | code | company | docs | research.

Important boundary:

• searchType and intentPreset shape routing input
• engine remains the explicit provider override

Extract and render

node {baseDir}/scripts/extract.mjs "https://example.com/article" --json
node {baseDir}/scripts/extract.mjs "https://example.com/article" --render --render-policy fallback --json
node {baseDir}/scripts/extract.mjs "https://example.com/article" --plan
node {baseDir}/scripts/render.mjs "https://example.com/article" --json

Crawl and map

node {baseDir}/scripts/crawl.mjs "https://example.com/docs" --depth 2 --max-pages 10 --json
node {baseDir}/scripts/map.mjs "https://example.com/docs" --depth 2 --max-pages 50 --json

Research

node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --json
node {baseDir}/scripts/research.mjs "OpenClaw search skill landscape" --plan --json

Runtime inspection

node {baseDir}/scripts/capabilities.mjs --json
node {baseDir}/scripts/doctor.mjs --json
node {baseDir}/scripts/bootstrap.mjs --json
node {baseDir}/scripts/review.mjs --json
node {baseDir}/scripts/cache.mjs stats --json
node {baseDir}/scripts/health.mjs --json

Benchmarking

node {baseDir}/scripts/eval.mjs list --json
node {baseDir}/scripts/eval.mjs run --suite core --json
node {baseDir}/scripts/eval.mjs run --suite research --json
node {baseDir}/scripts/eval.mjs run --suite head-to-head --json
node {baseDir}/scripts/eval.mjs run --suite head-to-head-live --json

Research Pack Boundary

research.mjs is a model-facing evidence layer, not a final narrative answer layer.

The skill is responsible for:

• question decomposition
• retrieval planning
• evidence normalization
• source prioritization
• claim clustering
• compact candidate findings
• uncertainty exposure

The upstream model remains responsible for:

• final reasoning across the evidence pack
• narrative synthesis
• user-facing writing style
• final judgment when evidence is incomplete or conflicting

Detailed contract:

• docs/research-layer.md

Runtime Config

Default config path:

• {baseDir}/config.json

Override path:

• WEB_SEARCH_PRO_CONFIG=/path/to/config.json

Config precedence:

CLI flags > process.env > config.json > built-in defaults

When the skill is run directly outside OpenClaw, provider keys must already exist in the shell environment. If OpenClaw launches the skill, its injected runtime environment is sufficient.

Key config areas:

• routing
• cache
• health
• fetch
• crawl
• render

Important routing config fields:

• routing.allowNoKeyBaseline
• routing.enableFederation
• routing.federationTriggers
• routing.maxFanoutProviders
• routing.maxPerProvider
• routing.mergePolicy
• routing.fallbackPolicy

Important render config fields:

• render.enabled
• render.policy
• render.budgetMs
• render.waitUntil
• render.blockTypes
• render.sameOriginOnly

Provider Upgrade Paths

No API key is required for the baseline. Optional provider credentials or endpoints unlock stronger coverage:

Optional provider credentials or endpoints unlock enhanced features.

TAVILY_API_KEY=tvly-xxxxx
EXA_API_KEY=exa-xxxxx
QUERIT_API_KEY=xxxxx
SERPER_API_KEY=xxxxx
BRAVE_API_KEY=xxxxx
SERPAPI_API_KEY=xxxxx
YOU_API_KEY=xxxxx
SEARXNG_INSTANCE_URL=https://searx.example.com

# Perplexity / Sonar: choose one transport path
PERPLEXITY_API_KEY=xxxxx
OPENROUTER_API_KEY=xxxxx
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
KILOCODE_API_KEY=xxxxx

# Or use a custom OpenAI-compatible gateway
PERPLEXITY_GATEWAY_API_KEY=xxxxx
PERPLEXITY_BASE_URL=https://gateway.example.com/v1
PERPLEXITY_MODEL=perplexity/sonar-pro

Provider roles:

• Tavily: strongest premium default for general search, news, and extract
• Exa: semantic retrieval and extract fallback
• Querit: multilingual AI search with native geo and language filters
• Serper: Google-like search with strong news and locale coverage
• Brave: structured general web search
• SerpAPI: multi-engine routing including Baidu and Yandex
• You.com: LLM-ready web search with freshness and mixed web/news coverage
• SearXNG: self-hosted privacy-first metasearch fallback
• Perplexity / Sonar: answer-first grounded search via native or gateway transport
• DDG: best-effort no-key baseline search
• Fetch: no-key extract / crawl / map baseline
• Render: optional local browser lane

Validation And Review

The most useful validation surfaces for agents and maintainers are:

• capabilities.mjs What this environment can truly do right now.
• doctor.mjs Is the runtime ready, degraded, or blocked?
• bootstrap.mjs What can an upstream agent safely assume?
• review.mjs What are the current safety and compliance boundaries?
• health.mjs Which providers are degraded or cooling down?
• eval.mjs Has behavior regressed against core, research, or comparative suites?

The bundled head-to-head suite focuses on route-first comparisons against a local ../web-search-plus checkout.

The bundled head-to-head-live suite adds real networked comparisons for freshness and citation quality under shared provider credentials.

Review-Safe Guarantees

• metadata only declares node as the hard runtime requirement
• provider credentials are optional
• ddg is a best-effort no-key baseline, not a guaranteed high-recall provider
• Safe Fetch rejects non-HTTP(S), credential-bearing, local, private, and metadata targets
• redirect targets are revalidated
• Safe Fetch keeps JavaScript execution disabled
• browser render is optional and off by default
• browser render uses a local headless browser only when enabled
• browser render reports anti-bot or challenge interstitials as failures instead of silent success
• provider health distinguishes degraded from cooldown

Docs

• README.md
• docs/research-layer.md
• docs/search-routing-model.md
• docs/search-ux-model.md
• docs/head-to-head-eval.md
• docs/clawhub-package.md
• docs/clawhub-compliance.md

Weekly Installs

108

Repository

zjianru/web-search-pro

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPassSocketWarnSnykWarn

Installed on

codex102

openclaw100

kimi-cli100

opencode100

github-copilot99

amp99