free-search-aggregator

免费搜索聚合器

为 OpenClaw 提供可靠且来源多样的网页搜索，兼具高可用性和低运维开销。

为什么要使用此技能

• 12 个搜索提供商，其中 6 个完全不需要 API 密钥
• 自动故障转移：一个提供商发生故障时，立即尝试下一个
• 配额感知：跟踪每日用量，在达到 80% 时发出警告，并跳过配额耗尽的提供商
• 任务搜索模式，适用于多角度研究查询
• 内置存储生命周期管理（缓存／索引／报告），不造成工作区杂乱
• 自我修复：基于健康状况的智能路由会自动提升可靠的提供商
• 质量优化：相关性评分、模糊去重、域名多样性和重新排序
• 自动发现：探测候选搜索引擎和 SearXNG 实例，寻找新的来源
• 自我诊断：提供 doctor 和 setup 命令，实现轻松上手

---

提供商概览

提供商	是否需要密钥	免费配额	索引来源	备注
brave	BRAVE_API_KEY	2000/day	Brave 独立索引	质量高，注重隐私
exa	EXA_API_KEY	~33/day (1k/mo)	神经网络 + 网页	语义搜索，独特发现
tavily	TAVILY_API_KEY	1000/day	网页（针对 AI 优化）	专为 AI Agent 设计
duckduckgo	无	~500/day	Bing + 自有索引	无需密钥，注重隐私
bing_html	无	~300/day	Microsoft Bing RSS	无需密钥，稳定的 XML 源
mojeek	无（或 MOJEEK_API_KEY）	200/day	Mojeek 独立索引	非 Google/Bing 索引
serper	SERPER_API_KEY	2500/day	Google	免费层配额高
searchapi	SEARCHAPI_API_KEY	100/mo	Google / Bing	多搜索引擎
google_cse	GOOGLE_API_KEY + GOOGLE_CX	100/day	Google	Google 官方 API
baidu	BAIDU_API_KEY	200/day	Baidu	最适合中文内容
wikipedia	无	1000/day	Wikipedia	事实类／百科类查询
searxng	无	unlimited（可自托管）	元搜索（所有引擎）	需要自有实例

每日总配额（配置所有密钥）：8400+ 次请求

---

凭据模式（重要）

• 不强制要求 API 密钥——DuckDuckGo、Bing RSS、Mojeek 和 Wikipedia 开箱即用。
• 缺少密钥时，依赖 API 密钥的提供商会优雅失败（AuthError → 跳过，不消耗配额，也不增加延迟）：
  • BRAVE_API_KEY
  • EXA_API_KEY
  • TAVILY_API_KEY
  • SERPER_API_KEY
  • SEARCHAPI_API_KEY
  • GOOGLE_API_KEY + GOOGLE_CX
  • BAIDU_API_KEY
  • MOJEEK_API_KEY（可选——不配置时使用 HTML 抓取）

---

核心功能

1. 搜索故障转移

默认提供商顺序：

brave → exa → tavily → duckduckgo → bing_html → mojeek → serper → searchapi → google_cse → baidu → wikipedia

第一个返回非空结果的提供商会立即返回结果。

2. 任务级多查询搜索

• 将一个目标扩展为多个有针对性的查询
• 汇总并去重结果
• 前缀预设：
  • 默认：workers=1
  • @dual ... → workers=2
  • @deep ... → workers=3 + 更深入的查询覆盖

3. 配额智能管理

• 按提供商跟踪每日用量
• 在支持的情况下获取实际配额（Tavily、SearchAPI，以及通过探测获取的 Brave 配额）
• 配额使用率达到 80% 时自动降低并发

4. 提供商健康监控

• 随时间跟踪各提供商的成功率、延迟和错误类型
• 计算健康评分（成功率 50%，延迟 30%，新鲜度 20%）
• 智能排序：自动提升健康状况良好的提供商，降低状态不佳的提供商的优先级
• 查看仪表板：python -m free_search health

5. 优化结果质量

• 相关性评分（查询词、标题和摘要的词元重合度）
• 增强去重：URL + 标题相似度（Jaccard 阈值）
• 域名多样性：限制来自同一域名的结果数量（默认最多 3 条）
• 自动过滤低质量结果（标题过短、缺少 URL）

6. 自动发现来源

• 探测所有已配置提供方的可用性
• 扫描候选搜索引擎（Marginalia、Wiby、公共 SearXNG 实例）
• 验证响应格式、延迟和结果质量
• 为集成新来源生成建议
• 运行：python -m free_search discover

7. 托管式持久化

• memory/search-cache/YYYY-MM-DD/*.json
• memory/search-index/search-index.jsonl
• memory/search-reports/YYYY-MM-DD/*.md

---

快捷命令

# Normal search
scripts/search "latest AI agent frameworks 2026" --max-results 5

# Task search (multi-query, parallel)
scripts/search task "@dual Compare Claude vs GPT-4 for code generation" --max-results 5

# Deep research mode
scripts/search task "@deep autonomous vehicle safety 2026" --max-results 8 --max-queries 10

# Quota status
scripts/status

# Real quota from provider APIs
scripts/remaining --real

# Cleanup cache
python3 -m free_search gc --cache-days 14

# Provider health dashboard
python3 -m free_search health

# Discover new search sources
python3 -m free_search discover

# System diagnostics
python3 -m free_search doctor

# Setup status & recommendations
python3 -m free_search setup

---

提供方设置指南

Bing RSS（bing_html）— 无需密钥

使用 Bing 内置的 RSS 端点（format=rss）——绕过机器人检测。开箱即用。

Mojeek — 无需密钥（可选 API 密钥）

开箱即用的 HTML 抓取。如需更高配额或更稳定的服务：

1. 在 https://www.mojeek.com/services/search/api/ 注册
2. 设置 MOJEEK_API_KEY → 自动切换到 JSON API 模式

Wikipedia — 无需密钥

支持多种语言 — 在 providers.yaml 中更改 lang：

wikipedia:
  lang: it   # en | zh | it | de | fr | ja ...

Exa.ai — 需要 API 密钥

1. 在 https://exa.ai/ 注册
2. 设置 EXA_API_KEY
3. 免费层级：每月 1000 次搜索（约每天 33 次）

Google Custom Search — 需要 API 密钥 + CX

1. 获取 API 密钥：https://developers.google.com/custom-search/v1/introduction
2. 创建搜索引擎：https://programmablesearchengine.google.com/
3. 设置 GOOGLE_API_KEY 和 GOOGLE_CX
4. 免费层级：每天 100 次查询

Baidu Qianfan — 需要 API 密钥

1. 在 https://cloud.baidu.com/ 注册
2. 设置 BAIDU_API_KEY
3. 最适合中文内容

SearXNG — 需要自托管实例

公共实例会对服务器到服务器的请求进行速率限制。请使用自己的实例：

docker run -d -p 8080:8080 searxng/searxng

然后在 providers.yaml 中：

searxng:
  endpoint: http://localhost:8080
  enabled: true

---

安装后自检

# 1) Confirm provider load
scripts/status --compact

# 2) Smoke test (uses duckduckgo/bing/mojeek out of the box)
scripts/search "openclaw" --max-results 3 --compact

# 3) Verify storage paths
ls -la /home/openclaw/.openclaw/workspace/memory/search-cache/ | tail -n 5

# 4) Check real quota (optional)
scripts/remaining --real --compact

---

输出约定（稳定）

• 搜索：query、provider、results[]、meta.attempted、meta.quota
• 任务搜索：task、queries[]、grouped_results[]、merged_results[]、meta
• 配额：date、providers[]、totals；使用 --real 时：real_quota.providers[]

---

运维说明

• 默认模式：workers=1 — 以保守方式控制成本
• 仅对研究任务使用 @dual / @deep
• SearXNG 和 YaCy 默认 enabled: false（仅限自托管）
• MOJEEK_API_KEY 为可选项 — 提供方会自动回退到 HTML 抓取
• 提供方运行状况数据存储在 memory/provider-health/health.jsonl
• 发现结果存储在 memory/provider-discovery/discovery.jsonl
• 设置后运行 python -m free_search doctor，验证一切正常
• 定期运行 python -m free_search discover，查找新的搜索来源