web-search-pro

Web Search Pro 2.1

このスキルは、1回きりのウェブ検索以上の機能を必要とするエージェント向けです。

呼び出し元が次のことを必要とする場合に使用します。

• ライブウェブ検索や最新ニュースの検索
• 説明可能なルーティングによるニュース検索
• 公式ドキュメント、API ドキュメント、またはコードの検索
• 企業、製品、競合他社の調査
• サイトのクロール、サイトマップ、またはドキュメントの探索
• 上流モデルに渡せる、構造化されたエビデンスパック

このスキルは、読み物としてのレポートを作成するものではありません。上流モデルがエビデンスをもとに推論を続けられるよう、エビデンスを検索、取得、構造化し、明確に提示することが役割です。

このスキルを使用する場合

• タスクはウェブ検索から始まるものの、情報抽出や調査に進む可能性がある
• エージェントがプロバイダーの選択理由を知る必要がある
• エージェントが単一プロバイダーではなく、複数プロバイダーを横断する検索を必要とする可能性がある
• 初回実行時に、API キーなしの基本動作が重要となる
• ランタイム診断や機能の検出がワークフローに含まれる

このスキルを使用しない場合

• 呼び出し元が可能な限りシンプルな、1回きりのウェブ検索ラッパーだけを求めている
• タスクでホスト型のスクレイピングサービスが必要となる
• スキル自体に、最終的な完成済みの文章レポートの作成が求められている
• 呼び出し元が、API キーなしで無制限に検索できることを求めている

クイックスタート

最短で成功する手順は次のとおりです。

• API キーなしの基本構成から始める
• より強力な再現率や鮮度が必要な場合にのみ、プレミアムプロバイダーを1つ追加する
• 次に、ドキュメント、ニュース、調査の各フローを試す

オプション A：API キーなしの基本構成

最初の実行を成功させるために、API キーは必要ありません。

基本構成での役割：

• ddg：ベストエフォートのウェブ検索
• fetch：API キーなしでの抽出／クロール／サイトマップのフォールバック

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：エージェントが現在頼れるものは何か
• search.mjs：プロバイダーの認証情報を追加する前に、基本の情報取得経路が成功することを確認する

オプション B：プレミアムプロバイダーを1つ追加する

プレミアムプロバイダーを1つだけ追加する場合は、TAVILY_API_KEY から始めてください。

理由：

• 認証情報1つで、一般的なウェブ検索が改善される
• 認証情報1つで、ニュース検索が改善される
• 認証情報1つで、情報抽出の品質が向上する

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

ランタイムの契約

エージェントは、これらのフィールドを主要なランタイム契約として扱ってください。

ルーティングフィールド

• selectedProvider プランナーが選んだ主要なルートです。「使用されるプロバイダーはこれだけ」という意味ではありません。
• routingSummary selectionMode、confidence、topSignals、代替候補、ブロックされたプロバイダー、フェデレーションの概要を含む、簡潔なルートの説明です。
• routing.diagnostics --explain-routing または --plan で表示される、ルートの詳細な診断情報です。

フェデレーションフィールド

• federated.providersUsed ファンアウトが有効な場合に実際に結果を返したプロバイダーです。
• federated.value.additionalProvidersUsed 実際に結果に貢献した、主要プロバイダー以外のプロバイダーの数です。
• federated.value.resultsRecoveredByFanout 主要プロバイダーのみのモードでは失われる最終結果です。
• federated.value.resultsCorroboratedByFanout 主要プロバイダーと少なくとも1つのファンアウトプロバイダーの両方に裏付けられた最終結果です。
• federated.value.duplicateSavings 統合時に削除された完全一致またはほぼ重複する結果です。

キャッシュと実行のフィールド

• cached 結果がキャッシュから取得されたかどうかです。
• cache エージェントの判断に役立つ、キャッシュの経過時間／TTL のテレメトリーです。
• renderLane ブラウザーを利用するレンダリングレーンのランタイムでの可用性とポリシーの概要です。
• failed 現在のコマンドで失敗したプロバイダー、または情報取得単位です。
• meta コマンドレベルの実行メタデータと、タスク入力の整形情報です。

リサーチフィールド

• topicType リサーチパックの主要なトピック分類です。
• topicSignals docs + latest のような、複数のトピックにまたがるヒントです。
• researchAxes リサーチパックが特定のサブ質問群に分解された理由です。
• claimClusters 正規化された主張ごとにまとめたエビデンスです。
• candidateFindings 裏付けの状況と不足情報への感度を含む、結論の候補です。
• uncertainties 残っている不確実性と、追加調査によって解消できる不足情報です。

フェデレーション検索が重要な理由

フェデレーションは、単に「プロバイダーを増やす」ことではありません。複数のプロバイダーを使うことで得られる効果を可視化し、エージェントがファンアウトによって最終的な結果セットが改善されたかどうかを判断できるようにします。

重要な効果指標：

• 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 の外部でスキルを直接実行する場合、プロバイダーのキーがシェル環境にすでに存在している必要があります。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：Baidu や Yandex を含む、複数の検索エンジンへのルーティングを提供します。
• You.com：鮮度とウェブ・ニュースの混合検索に対応した、LLM 向けのウェブ検索です。
• SearXNG：セルフホスト型の、プライバシーを重視したメタ検索のフォールバックです。
• Perplexity / Sonar：ネイティブまたはゲートウェイ経由の転送による、回答優先の根拠付き検索です。
• DDG：キー不要のベースライン検索をベストエフォートで提供します。
• Fetch：キー不要の抽出／クロール／マッピングのベースラインです。
• Render：オプションのローカルブラウザーレーンです。

検証とレビュー

エージェントとメンテナーにとって、最も有用な検証手段は次のとおりです。

• capabilities.mjs この環境で現時点で実際に何ができるかを確認します。
• doctor.mjs ランタイムの準備ができているか、機能が低下しているか、ブロックされているかを確認します。
• bootstrap.mjs 上流のエージェントが安全に前提とできることを確認します。
• 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