web-search-pro

Web Search Pro 2.1

这项技能适用于需要执行多轮网页搜索的 Agent。

当调用方需要以下功能时，请使用此技能：

• 实时网页搜索或时事查询
• 可解释路由的新闻搜索
• 官方文档、API 文档或代码查询
• 公司、产品或竞争对手调研
• 网站爬取、网站地图或文档发现
• 可交由上游模型使用的结构化证据包

这项技能不负责撰写叙述性报告。它的职责是搜索、检索、整理并清晰呈现证据，以便上游模型能基于这些证据继续推理。

适用场景

• 任务从网页搜索开始，但可能继续进行信息提取或调研
• Agent 需要知道为何选择某个服务提供商
• Agent 可能需要联邦搜索，而非仅使用单个服务提供商
• 首次运行时，无需 API 密钥的基础行为很重要
• 工作流包含运行时诊断或能力发现

不适用场景

• 调用方只需要最轻量的单次网页搜索封装
• 任务需要托管式抓取服务
• 任务要求技能本身撰写润色完善的最终叙述性报告
• 调用方需要保证无需密钥即可无限搜索

快速开始

最简的成功路径如下：

• 从无需密钥的基础配置开始
• 仅在需要更强的召回能力或时效性时添加一个高级服务提供商
• 然后尝试文档、新闻和调研工作流

选项 A：无需密钥的基础配置

首次成功运行无需 API 密钥。

基础配置的作用：

• ddg：尽力执行网页搜索
• fetch：无需密钥的提取、爬取和地图回退方案

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

这些命令的用途：

• doctor.mjs：当前运行时是否可用？
• bootstrap.mjs：Agent 当前可以依赖哪些功能？
• 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

运行时契约

Agent 应将以下字段视为主要运行时契约。

路由字段

• 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 用于 Agent 决策的缓存时长 / TTL 遥测信息。
• renderLane 基于浏览器的渲染通道的运行时可用性和策略摘要。
• failed 当前命令中失败的服务提供商或检索单元。
• meta 命令级执行元数据和任务输入整形信息。

研究字段

• topicType 研究包的主要主题类别。
• topicSignals 混合主题提示，例如 docs + latest。
• researchAxes 说明研究包为何拆分为给定一组子问题。
• claimClusters 按规范化后的主张分组的证据。
• candidateFindings 带有支持情况和缺口敏感性的候选结论。
• uncertainties 尚存的不确定性，以及可能受后续跟进影响的缺口。

联邦搜索为何重要

联邦搜索不只是“更多提供方”。它能体现多提供方带来的增益，让 Agent 判断扇出搜索是否改善了最终结果集。

重要的增益指标：

• 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 flags > process.env > config.json > built-in defaults

在 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: 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

提供方角色：

• Tavily：通用搜索、新闻和提取的最佳高级默认选项
• Exa：语义检索和提取的备用选项
• Querit：支持原生地理位置和语言筛选的多语言 AI 搜索
• Serper：类似 Google 的搜索，新闻和地区覆盖能力强
• Brave：结构化通用网页搜索
• SerpAPI：支持多引擎路由，包括百度和 Yandex
• You.com：适用于 LLM 的网页搜索，具备时效性及网页和新闻混合覆盖能力
• SearXNG：可自托管、隐私优先的元搜索备用选项
• Perplexity / Sonar：通过原生或网关传输实现的答案优先、有依据的搜索
• DDG：尽力而为的免密钥基础搜索
• Fetch：免密钥提取 / 抓取 / 映射基础功能
• Render：可选的本地浏览器通道

验证与审查

对 Agent 和维护者最有用的验证入口包括：

• capabilities.mjs 此环境当前实际能够执行的操作。
• doctor.mjs 运行时已就绪、处于降级状态，还是受到阻止？
• bootstrap.mjs 上游 Agent 可以安全地做出哪些假设？
• review.mjs 当前的安全与合规边界是什么？
• health.mjs 哪些提供方处于降级或冷却状态？
• eval.mjs 与核心、研究或对比套件相比，行为是否出现回归？

随附的 head-to-head 套件侧重于与本地 ../web-search-plus 检出版本进行路由优先的对比。

随附的 head-to-head-live 套件还会在共享的提供方凭据下进行真实网络对比，评估时效性和引用质量。

审查安全保障

• 元数据仅将 node 声明为硬性运行时要求
• 提供方凭据为可选项
• ddg 是尽力而为的无密钥基线，并非保证具有高召回率的提供方
• Safe Fetch 会拒绝非 HTTP(S)、包含凭据、本地、私有和元数据目标
• 重定向目标会重新验证
• Safe Fetch 会保持 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