free-search-aggregator

Free Search Aggregator

OpenClaw 向けの信頼性が高く、プロバイダーが多様なウェブ検索です。高い稼働率と低い運用負荷を実現します。

このスキルを使う理由

• 12 の検索プロバイダー。うち 6 つは API キーが不要です
• 自動フェイルオーバー：あるプロバイダーに障害が発生すると、すぐに次のプロバイダーを試します
• クォータを考慮：日ごとの使用量を追跡し、80% で警告を表示し、上限に達したプロバイダーをスキップします
• 複数の視点から調査するクエリ向けのタスク検索モード
• ストレージのライフサイクルを内蔵（キャッシュ／インデックス／レポート）し、ワークスペースを散らかしません
• 自己修復：ヘルスベースのスマートルーティングにより、信頼性の高いプロバイダーを自動的に優先します
• 品質最適化：関連性スコアリング、ファジー重複排除、ドメインの多様性、再ランキング
• 自動検出：候補となる検索エンジンや SearXNG インスタンスを調査し、新しいソースを見つけます
• セルフ診断：オンボーディングをスムーズにする doctor と setup コマンド

---

プロバイダーの概要

プロバイダー	キーが必要	無料クォータ	インデックスのソース	備考
brave	BRAVE_API_KEY	2000/日	Brave 独自	高品質、プライバシーに配慮
exa	EXA_API_KEY	約 33/日（1k/月）	ニューラル＋ウェブ	セマンティック検索、独自の検索結果
tavily	TAVILY_API_KEY	1000/日	ウェブ（AI に最適化）	AI エージェント向けに設計
duckduckgo	なし	約 500/日	Bing＋独自	キー不要、プライバシー重視
bing_html	なし	約 300/日	Microsoft Bing RSS	キー不要、安定した XML フィード
mojeek	なし（または MOJEEK_API_KEY）	200/日	Mojeek 独自	Google／Bing 以外のインデックス
serper	SERPER_API_KEY	2500/日	Google	無料枠のクォータが大きい
searchapi	SEARCHAPI_API_KEY	100/月	Google／Bing	マルチエンジン
google_cse	GOOGLE_API_KEY + GOOGLE_CX	100/日	Google	Google 公式 API
baidu	BAIDU_API_KEY	200/日	Baidu	中国語コンテンツに最適
wikipedia	なし	1000/日	Wikipedia	事実確認／百科事典的なクエリ
searxng	なし	無制限（セルフホスト可能）	メタ（すべてのエンジン）	独自のインスタンスが必要

全キーを設定した場合の合計日次クォータ：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. タスクレベルの複数クエリ検索

• 1 つの目標を複数の対象を絞ったクエリに展開します
• 結果を集約し、重複を排除します
• プレフィックスのプリセット：
  • デフォルト：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）— API キー不要

Bing の組み込み RSS エンドポイント（format=rss）を使用し、ボット検出を回避します。すぐに利用できます。

Mojeek — API キー不要（API キーは任意）

標準で HTML スクレイピングを行います。より高いクォータと安定性を得るには：

1. https://www.mojeek.com/services/search/api/ で登録します
2. MOJEEK_API_KEY を設定すると、自動的に JSON API モードに切り替わります

Wikipedia — API キー不要

多言語に対応しています。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 件の検索（1 日あたり約 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. 無料枠：1 日あたり 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 を実行してください