web-search-plus

Web Search Plus

多提供商网页搜索，具备智能自动路由：Serper（Google）、Tavily（研究）、Exa（神经搜索）。

v2.3.0 新增：交互式设置向导！运行 python3 scripts/setup.py，按照向导进行配置。

v2.2.5 新增：自动错误回退——如果某个提供商失败（速率限制、超时等），则会按照优先级自动尝试下一个提供商！

---

🚀 首次运行（设置向导）

第一次使用 web-search-plus？交互式设置向导会引导你完成配置：

python3 scripts/setup.py

向导将：

1. 介绍每个提供商 — 说明各自最适合的用途、免费套餐限额和注册链接
2. 询问要启用哪些提供商 — 可选择 1 个、2 个或全部 3 个
3. 收集 API 密钥 — 密钥会本地存储在 config.json 中（已加入 gitignore）
4. 配置默认选项 — 默认提供商、自动路由、结果数量

各提供商最适合的用途

提供商	最适合的用途	免费套餐
Serper	Google 搜索结果、购物、价格、本地商家、新闻	每月 2,500 次
Tavily	研究问题、解释、学术内容、完整页面内容	每月 1,000 次
Exa	语义搜索、“与 X 类似”、初创公司发现、论文	每月 1,000 次

随时重新配置

python3 scripts/setup.py --reset

---

🔑 API 密钥设置（手动）

v2.2.0 新增：脚本会自动加载技能目录中 .env 文件里的 API 密钥！

快速设置

选项 A：.env 文件（推荐）

# /path/to/skills/web-search-plus/.env
export SERPER_API_KEY="your-key"   # https://serper.dev
export TAVILY_API_KEY="your-key"   # https://tavily.com  
export EXA_API_KEY="your-key"      # https://exa.ai

选项 B：config.json（v2.2.1 新增）

# Copy the example config
cp config.example.json config.json

然后添加你的密钥：

{
  "serper": { "api_key": "your-serper-key" },
  "tavily": { "api_key": "your-tavily-key" },
  "exa": { "api_key": "your-exa-key" }
}

⚠️ config.json 已加入 gitignore——你的密钥安全无虞！

直接运行——密钥会自动加载：

python3 scripts/search.py -q "your query"
# No need for 'source .env' anymore! ✨

优先级： config.json > .env > 环境变量

获取免费 API 密钥

提供商	免费套餐	注册
Serper	每月 2,500 次查询	https://serper.dev
Tavily	每月 1,000 次查询	https://tavily.com
Exa	每月 1,000 次查询	https://exa.ai

---

⚠️ 不要修改 OpenClaw 核心配置

Tavily、Serper 和 Exa 不是 OpenClaw 的核心提供商。

❌ 不要添加到 ~/.openclaw/openclaw.json：

"tools": { "web": { "search": { "provider": "tavily" }}}  // WRONG!

✅ 请使用此技能的脚本——密钥会从 .env 自动加载

OpenClaw 核心仅支持 brave 作为内置网页搜索提供商。此技能通过自己的脚本添加 Serper、Tavily 和 Exa 作为额外选项。

---

🧠 智能自动路由

无需选择提供商——直接搜索即可！此技能会使用多信号分析来理解你的查询意图：

# These queries are intelligently routed with confidence scoring:
python3 scripts/search.py -q "how much does iPhone 16 cost"     # → Serper (68% MEDIUM)
python3 scripts/search.py -q "how does quantum entanglement work"  # → Tavily (86% HIGH)
python3 scripts/search.py -q "startups similar to Notion"       # → Exa (76% HIGH)
python3 scripts/search.py -q "MacBook Pro M3 specs review"      # → Serper (70% HIGH)
python3 scripts/search.py -q "explain pros and cons of React"   # → Tavily (85% HIGH)
python3 scripts/search.py -q "companies like stripe.com"        # → Exa (100% HIGH)

工作原理

路由引擎会分析多种信号：

🛒 购物意图 → Serper

信号类型	示例	权重
价格相关表达	“多少钱”、“……的价格”、“……的成本”	高
购买意图	“买”、“购买”、“订购”、“哪里可以买到”	高
优惠信号	“优惠”、“折扣”、“便宜”、“最佳价格”	中
产品 + 品牌	“iPhone 16”、“Sony 耳机” + 规格/评测	高
本地商家	“附近”、“餐厅”、“酒店”	高

📚 研究意图 → Tavily

信号类型	示例	权重
解释	“……如何运作”、“……为什么会这样”、“解释”、“什么是”	高
分析	“比较”、“优缺点”、“……之间的区别”	高
学习	“教程”、“指南”、“理解”、“学习”	中
深度	“深入”、“全面”、“详细”	中
复杂查询	较长、包含多个分句的问题	加成

🔍 发现意图 → Exa

信号类型	示例	权重
相似性	“与……类似”、“……的替代方案”、“竞争对手”	非常高
公司发现	“类似……的公司”、“从事……的初创公司”、“还有谁”	高
URL 检测	任何 URL 或域名（stripe.com）	非常高
学术内容	“arxiv”、“研究论文”、“github 项目”	高
融资	“A 轮”、“YC”、“获得融资的初创公司”	高

置信度评分

每个路由决策都包含一个置信度级别：

置信度	级别	含义
70-100%	HIGH	信号匹配度高，非常可靠
40-69%	MEDIUM	匹配度良好，应该效果不错
0-39%	LOW	查询含糊，使用备用方案

调试路由决策

查看完整分析：

python3 scripts/search.py --explain-routing -q "how much does iPhone 16 Pro cost"

输出：

{
  "query": "how much does iPhone 16 Pro cost",
  "routing_decision": {
    "provider": "serper",
    "confidence": 0.68,
    "confidence_level": "medium",
    "reason": "moderate_confidence_match"
  },
  "scores": {"serper": 7.0, "tavily": 0.0, "exa": 0.0},
  "top_signals": [
    {"matched": "how much", "weight": 4.0},
    {"matched": "brand + product detected", "weight": 3.0}
  ],
  "query_analysis": {
    "word_count": 7,
    "is_complex": false,
    "has_url": null,
    "recency_focused": false
  }
}

---

🔍 何时使用此技能，何时使用内置的 Brave Search

在以下情况下使用内置的 Brave Search：

• ✅ 常规网页搜索（新闻、信息、问题）
• ✅ 注重隐私
• ✅ 无特定要求的快速查询

在以下情况下使用 web-search-plus：

→ Serper（Google 结果）：

• 🛍️ 产品规格、价格、购物 - “比较 iPhone 16 和 Samsung S24”
• 📍 本地商家、地点 - “柏林最好的披萨”
• 🎯 “用 Google 搜一下” - 明确希望获得 Google 结果
• 📰 购物/图片/新闻 - --type shopping/images/news
• 🏆 知识图谱 - 结构化信息（价格、评分等）

→ Tavily（针对 AI 优化的研究）：

• 📚 研究问题 - “量子计算是如何运作的？”
• 🔬 深入探究 - 复杂的多部分问题
• 📄 完整页面内容 - 不只是摘要（--raw-content）
• 🎓 学术研究 - 综合整理后的答案
• 🔒 域名筛选 - 使用 --include-domains 筛选可信来源

→ Exa（神经语义搜索）：

• 🔗 相似页面 - “类似 OpenAI.com 的网站”（--similar-url）
• 🏢 公司发现 - “类似 Anthropic 的 AI 公司”
• 📝 研究论文 - --category "research paper"
• 💻 GitHub 项目 - --category github
• 📅 指定日期 - --start-date / --end-date

---

提供商对比

功能	Serper	Tavily	Exa
速度	⚡⚡⚡	⚡⚡	⚡⚡
事实准确性	⭐⭐⭐	⭐⭐⭐	⭐⭐
语义理解	⭐	⭐⭐	⭐⭐⭐
研究质量	⭐⭐	⭐⭐⭐	⭐⭐
完整页面内容	✗	✓	✓
购物/本地搜索	✓	✗	✗
相似页面	✗	✗	✓
知识图谱	✓	✗	✗

---

使用示例

自动路由（推荐）

python3 scripts/search.py -q "iPhone 16 Pro Max price"          # → Serper
python3 scripts/search.py -q "how does HTTPS encryption work"   # → Tavily
python3 scripts/search.py -q "startups similar to Notion"       # → Exa

指定提供商

python3 scripts/search.py -p serper -q "weather Berlin" --type weather
python3 scripts/search.py -p tavily -q "quantum computing" --depth advanced
python3 scripts/search.py -p exa --similar-url "https://stripe.com" --category company

---

配置

config.json

{
  "auto_routing": {
    "enabled": true,
    "fallback_provider": "serper",
    "confidence_threshold": 0.3,
    "disabled_providers": []
  },
  "serper": {"country": "us", "language": "en"},
  "tavily": {"depth": "advanced"},
  "exa": {"type": "neural"}
}

---

输出格式

{
  "provider": "serper",
  "query": "iPhone 16 price",
  "results": [{"title": "...", "url": "...", "snippet": "...", "score": 0.95}],
  "answer": "Synthesized answer...",
  "routing": {
    "auto_routed": true,
    "provider": "serper",
    "confidence": 0.78,
    "confidence_level": "high",
    "reason": "high_confidence_match",
    "top_signals": [{"matched": "price", "weight": 3.0}]
  }
}

---

常见问题

常规问题

Q：自动路由如何决定使用哪个提供商？

多信号分析会根据价格模式、解释短语、相似性关键词、URL、产品与品牌组合以及查询复杂度为每个提供商评分。得分最高者胜出。使用 --explain-routing 查看决策详情。

Q：如果选错了提供商怎么办？

使用 -p serper/tavily/exa 覆盖选择。查看 --explain-routing，了解它为何作出不同选择。

Q：“低置信度”是什么意思？

查询含糊（例如，“Tesla”可能指汽车、股票或公司）。系统会回退到 Serper。结果可能有所不同。

Q：可以禁用某个提供商吗？

可以！在 config.json 中设置："disabled_providers": ["exa"]

API 密钥

Q：我需要哪些 API 密钥？

至少需要一个密钥。你可以只使用 Serper、只使用 Tavily，也可以三个都用。缺少密钥时，会跳过对应的提供商。

Q：在哪里获取 API 密钥？

• Serper：https://serper.dev（2,500 次免费查询，无需信用卡）
• Tavily：https://tavily.com（每月 1,000 次免费搜索）
• Exa：https://exa.ai（每月 1,000 次免费搜索）

Q：如何设置 API 密钥？

有两种方式（都会自动加载）：

选项 A：.env 文件

export SERPER_API_KEY="your-key"

选项 B：config.json（v2.2.1+）

{ "serper": { "api_key": "your-key" } }

路由详情

问：如何知道搜索使用了哪个提供商？

查看 JSON 输出中的 routing.provider，或聊天回复中的 [🔍 Searched with: Provider]。

问：为什么有时会为研究问题选择 Serper？

如果查询包含品牌／产品信号（例如“Tesla FSD 如何工作”），购物意图可能会优先于研究意图。使用 -p tavily 覆盖选择。

问：置信度阈值是多少？

默认值：0.3（30%）。低于此值表示置信度较低，将使用备用方案。可在 config.json 中调整。

故障排除

问：出现“No API key found”错误？

1. 检查 skill 文件夹中是否存在 .env，且格式为 export VAR=value
2. 从 v2.2.0 起，会自动从 skill 的 .env 加载密钥
3. 或在系统环境中设置：export SERPER_API_KEY="..."

问：结果为空？

1. 检查 API 密钥是否有效
2. 使用 -p 尝试其他提供商
3. 有些查询没有结果（主题非常冷门）

问：遇到速率限制？

v2.2.5 新增：自动回退！如果某个提供商触发速率限制，脚本会按优先级自动尝试下一个提供商（serper → tavily → exa）。你会在 stderr 中看到回退信息，回复中也会包含 routing.fallback_used: true。

提供商限额：Serper 免费总额度为 2,500 次，Tavily 免费额度为每月 1,000 次，Exa 免费额度为每月 1,000 次。

OpenClaw 用户须知

问：如何在聊天中使用？

直接提问即可！OpenClaw 会自动检测搜索意图。或者明确地说：“使用 web-search-plus 搜索……”

问：它会取代内置的 Brave Search 吗？

不会，两者是互补的。快速查询使用 Brave，研究／购物／发现使用 web-search-plus。

问：能查看使用了哪个提供商吗？

可以！SOUL.md 可以包含来源标注：[🔍 Searched with: Serper/Tavily/Exa]