web-search-plus

Web Search Plus

不用再纠结选哪个搜索提供方，交给这个 skill 就行。

这个 skill 现在可连接 11 个搜索提供方，并新增了一条配套的提取流程，用于从 URL 中抓取内容。宽泛的网络查询？→ Brave 或 Serper。研究型问题？→ Tavily 或 Exa。需要引用和依据？→ Linkup。想要可直接抓取的内容？→ Firecrawl。更看重隐私？→ SearXNG。需要低成本、预付费额度的 Google SERP？→ SerpBase（仅显式调用/仅作回退）。想要一个独立的索引作为最后手段的回退（甚至无需密钥）？→ Keenable。

这个 skill 是仅提供来源：返回排序后的链接和抽取的页面文本，而不是模型撰写的答案。Perplexity/Kilo 的答案合成已在 4.0.0 中移除。原生 OpenClaw 插件是 web-search-plus-plugin-v2。

---

🔐 数据处理与隐私

在使用敏感查询进行搜索前，请先阅读本节。

• 搜索查询和提取 URL 会发送给第三方提供方。 每次搜索都会把你的查询文本传输给所选定的已配置提供方（Serper、Brave、Tavily、Linkup、Querit、Exa、Firecrawl、SerpBase、Keenable、You.com 或你的 SearXNG 实例）。每次提取都会把目标 URL 传输给所选的提取提供方（Tavily、Exa、Linkup、Firecrawl、You.com、Keenable、Serper），随后由其基础设施抓取该页面。各提供方自己的隐私政策和保留规则均适用。
• 处理敏感工作时，请显式选择提供方（--provider <name>），而不要依赖自动路由，这样你就能确切控制哪个第三方接收该查询。可自托管的 SearXNG 会让查询保留在你掌控的基础设施上。
• 不要提交内部或私有 URL 进行提取。 你提取的 URL 会被转发给外部服务。此外，该 skill 默认会阻止私有/回环/链路本地目标以及云元数据端点（见下方安全部分）。
• 默认开启本地缓存。 查询、结果、提供方失败历史以及提供方性能采样（延迟/结果数/错误，用于自适应路由）都会持久化到缓存目录下（默认为 .cache，可用 WSP_CACHE_DIR 更改位置），其中包括带有提供方错误信息的 provider_health.json 和 provider_stats.json。缓存文件以仅属主可访问的权限写入（目录 0700，文件 0600）。
  • 单次调用绕过缓存：--no-cache
  • 全局禁用：WSP_DISABLE_CACHE=1
  • 清空：python3 scripts/search.py --clear-cache（用 --cache-stats 查看）
• API 密钥绝不会被该 skill 记录或持久化；错误在进入缓存或 stderr 之前会先被净化处理。

---

🎯 触发条件

为避免在日常请求中被自动激活，manifest 只注册了范围很窄的触发短语：

• web search plus
• wsp search
• search the web for
• multi-provider web search
• extract url content
• extract content from url

像 "search"、"find"、"look up" 或 "research" 这样的通用词有意不会触发这个 skill。

---

✨ 有何不同？

• 只管搜索 — 无需考虑该用哪个提供方
• 智能路由 — 通过查询分析自动挑选最佳提供方
• 11 个提供方，1 个接口 — 通用网络、研究、语义发现、隐私优先、预付费额度以及支持提取的提供方齐聚一处
• 内置 URL 提取 — 以七个提供方作为回退（优先 Tavily），抓取 markdown/HTML 内容
• 研究模式 — 一次调用即可并发多提供方搜索 + 去重 + 顶级来源提取
• 权威来源重排 — 对于发布/文档/政策/金融/安全类查询，官方/一手来源优先于镜像域名
• 仅凭 1 个凭据即可使用 — 从任意单个提供方开始，之后再添加更多
• 提供免费/可自托管选项 — SearXNG 可以做到 $0 API 成本运行

---

🚀 快速开始

# Interactive setup (recommended for first run)
python3 scripts/setup.py

# Or manually
cp .env.example .env
python3 scripts/search.py -q "latest OpenClaw release"
python3 scripts/extract.py --url https://example.com

向导会介绍各提供方、收集密钥并设置默认值。

---

🔑 提供方

搜索提供商

• Serper — 购物、价格、本地及通用 Google 风格结果；快速广泛的兜底方案
• Brave — 独立的网络索引与通用实时网络查询；强大的非 Google 补充
• Tavily — 研究、解释与综合；强大的研究路由
• Querit — 多语言与国际更新；适合跨语言时效性需求
• Linkup — 基于来源、引用丰富的搜索；证据优先的查询
• Exa — 语义发现与相似站点搜索，带来源 URL
• Firecrawl — 带抓取就绪元数据的搜索；同时是强大的提取提供商
• You.com — 实时网络 / 适合 RAG 的摘要；同时支持提取
• SearXNG — 私有/可自托管搜索；无需 API key，只需实例 URL
• SerpBase — 低成本 Google SERP，使用预付额度；仅显式/兜底使用（通过 --provider serpbase 选择启用，或添加到 config.json 中的 provider_priority）
• Keenable — 独立的网络索引；通过 KEENABLE_API_KEY 使用密钥，或免密钥针对 选择性启用 的共享公共层级（WSP_KEENABLE_ALLOW_PUBLIC=1，约 1000 请求/小时，无 SLA，结果元数据中有警告）。自动路由优先级最低 — 永远不会取代已配置密钥的提供商

提取提供商

scripts/extract.py 会自动依次兜底（为保证可靠性优先使用 Tavily）：

1. Tavily
2. Exa
3. Linkup
4. Firecrawl
5. You.com
6. Keenable
7. Serper（通过 scrape.serper.dev 的网页抓取器，优先 markdown）

---

🧠 路由概览

默认优先级（SerpBase 按设计排除 — 仅选择性启用）：

tavily → linkup → querit → exa → firecrawl → brave → serper → you → searxng → keenable

路由还会应用 自适应提供商性能记忆：每次提供商调用都会将延迟/结果数量/错误记录到滚动窗口中（50 个样本，7 天新鲜度，持久化为 provider_stats.json），在 5 个新鲜样本后为路由分数提供有界（±1.0）的调整 — 足以打破平局并微调接近的调用，但永远不会覆盖明确的查询类别获胜者（routing.adaptive_adjustments）。

示例：

python3 scripts/search.py -q "weather in Vienna today"
# generic current-web intent → Brave or Serper

python3 scripts/search.py -q "find credible sources for AI tutoring outcomes"
# citation/evidence intent → Linkup

python3 scripts/search.py -q "latest AI policy updates in Germany"
# multilingual + recency → Querit or Tavily

python3 scripts/search.py -p exa --exa-depth deep -q "LLM scaling laws research"
python3 scripts/search.py -p firecrawl -q "YC startups web scraping"
python3 scripts/search.py -p serpbase -q "best laptop 2026"   # explicit SerpBase

调试路由：

python3 scripts/search.py --explain-routing -q "your query"

以短横线开头的查询可以使用 --query=-foo 或 -q -- "-foo"。省略 -n 时，由 defaults.max_results 提供数量（兜底 5）；数量被限制在 1–20。

--time-range 优先于 --freshness。Tavily 将 day/week/month/year 作为原生 time_range 发送；Exa 报告随请求发送的发布时间范围。

--cache-ttl SECONDS 设置搜索缓存生存时间，对于 live/hour 查询上限为 60 秒，对于 latest/day 为 300 秒，对于 week 过滤器为 1800 秒。缓存结果包含 cache_age_seconds。--no-cache 绕过搜索结果缓存。设置 WSP_HTTP_KEEPALIVE=0 以禁用连接复用；通过代理的请求使用标准传输。

新鲜度、新闻垂直领域与区域设置

python3 scripts/search.py -q "AI regulation" --freshness week
# providers with native date filters receive the mapped value; others run the
# normal search and report freshness.applied=false in metadata

python3 scripts/search.py -p serper --type news -q "quantum computing"
# Serper serves the Google news vertical natively (date/source/thumbnail);
# other providers report search_type.applied=false

python3 scripts/search.py -q "beste Kaffeehäuser Wien"
# explicit location hints (curated city/country table) set the country (at);
# set locale.language="auto" (or WSP_LOCALE_LANGUAGE=auto) to also infer the
# query language conservatively. Resolved values + sources appear in
# metadata.locale. Without configuration behavior stays exactly us/en.

结果质量过滤器

来自已知 Stack Overflow/GitHub/文档镜像域的结果会被移除（严格的精确域/真实子域匹配，无误报相似域）；可通过 config.json 中的 quality.blocked_domains 扩展，或通过 quality.allowed_domains 挽救。域多样性重排序将单个域限制在 2 个头部位置（溢出降级，而非丢弃）。显式域意图（site: 查询、--include-domains）绕过两者。移除和降级会在 metadata.result_filter 中报告。

---

📖 提取示例

python3 scripts/extract.py --url https://example.com
python3 scripts/extract.py --url https://docs.linkup.so --provider linkup
python3 scripts/extract.py --url https://example.com --url https://example.org --include-images
python3 scripts/extract.py --url https://example.com --format html --include-raw-html
python3 scripts/extract.py --url https://example.com --provider serper   # Serper webpage scraper
python3 scripts/extract.py --url https://example.com --extract-char-limit 30000

超大页面返回头部/尾部窗口以及说明性页脚（默认内联预算 15,000 字符；WSP_EXTRACT_CHAR_LIMIT 或 --extract-char-limit 覆盖）。内联 base64 图像数据在测量内容前会替换为 [IMAGE: alt] 占位符，防止 data-URI token 炸弹，同时保留正常的 http(s) 图像链接。

---

🔬 研究模式与质量报告

研究模式最多并发查询三个提供方（实际耗时 ≈ 最慢的提供方，而非各提供方耗时之和），跨提供方去重并采用确定性排序，然后提取排名靠前的来源用于接地：

python3 scripts/search.py --mode research -q "EU AI Act obligations for foundation models"
python3 scripts/search.py --mode research -q "..." --research-providers tavily linkup exa
python3 scripts/search.py --mode research -q "..." --research-extract-count 2 --research-time-budget 30

时间预算决定哪些提供方启动以及是否运行提取；已耗尽时间的步骤会报告在 routing.provider_errors / routing.extraction_error 中，而不是让调用失败。

质量报告增加了透明的路由/结果诊断信息，包括针对规范来源路由类别的权威信号（canonical_domain_hits、demoted_domain_hits、canonical_top_result）：

python3 scripts/search.py -q "official anthropic claude release notes" --quality-report

对于这些规范类别（官方厂商发布、官方文档、政策 PDF、金融/投资者关系、安全公告），结果还会按意图重新排序：主要来源被提升，镜像/聚合域名被降级（metadata.intent_rerank 显示发生了什么变化）。

---

⚙️ 配置说明

• .env.example 记录了支持的环境变量
• config.example.json 包含提供方优先级和提供方特定的默认值
• config.json 是你的本地运行时配置
• SearXNG 仍支持显式 URL 配置和 docker 感知的自动检测
• SerpBase 默认是显式/仅回退；要将其纳入自动路由，请在 config.json 的 auto_routing.provider_priority 中追加 "serpbase"
• Keenable 在自动路由和提取回退中位于最后；通过 WSP_KEENABLE_ALLOW_PUBLIC=1 或 "keenable": {"allow_public": true} 显式启用无密钥使用
• 区域设置默认值：config.json 中的 "locale": {"country": "...", "language": "..."}（或 WSP_LOCALE_COUNTRY/WSP_LOCALE_LANGUAGE）；--country/--language 命令行标志始终优先
• 速率限制：429 响应会解析 Retry-After，最多重试一次（≤30s 的等待会被就地遵守），并将提供方请求的等待时间纳入冷却阶梯；超过 30 分钟的失败历史会衰减，而不是无限升级冷却；缺少密钥的配置错误永远不会触发冷却

---

🔒 安全

URL SSRF 防护（提取、--similar-url）：

• 仅接受 http / https URL
• 主机名会被解析，如果指向私有/环回/链路本地/保留地址范围（10/8、127/8、169.254/16、172.16/12、192.168/16、CGNAT 100.64/10、::1、fc00::/7、fe80::/10、IPv4 映射的 IPv6、0.0.0.0）则会被阻止
• 云元数据端点（169.254.169.254、metadata.google.internal）始终被阻止
• 对于受信任的私有网络，可通过 --allow-private-urls 或 WSP_ALLOW_PRIVATE_URLS=1 选择退出（默认关闭；元数据端点仍被阻止）

SearXNG SSRF 防护：

• 仅强制执行 http / https
• 阻止常见的云元数据端点
• 除非 SEARXNG_ALLOW_PRIVATE=1，否则阻止私有/内部 IP 解析
• 实例 URL 仅使用操作员控制的配置/环境变量

本地数据：

• 缓存目录以 0700 创建；缓存、提供方健康状态和提供方统计数据文件以 0600 通过原子临时文件替换写入
• API 密钥永远不会写入缓存或日志

声明的权限（参见 package.json → clawhub.permissions）：

• 出站网络访问仅限于所列提供方 API 主机（加上任何用户配置的 SearXNG 实例）
• 环境变量读取仅限于提供方 *_API_KEY 变量、SEARXNG_* 和 WSP_* 设置
• 文件系统写入仅限于缓存目录

---

✅ 验证

python3 -m unittest discover -s tests -p 'test_*.py'
python3 scripts/search.py --explain-routing -q "find credible sources for climate change impacts"
python3 scripts/extract.py --url https://example.com --provider auto --compact