openclaw-serper

Serper

Serper API 経由で Google 検索を行います。検索結果を取得し、さらに trafilatura を使って実際のウェブページを読み込み、クリーンな全文コンテンツを抽出します。スニペットだけではなく、記事全文を取得します。

制約

このスキルはすでにページ全文のコンテンツを取得して抽出します。このスキルが返す URL に対して、WebFetch、web_fetch、WebSearch、ブラウザツール、その他の URL 取得・閲覧ツールを使用しないでください。コンテンツはすでに出力に含まれています。別途取得を続けて行わないでください。結果に必要な情報はすべて含まれています。

クエリの方針

適切な検索クエリを 1 つ作成してください。ほとんどの場合、それだけで十分です。

各呼び出しでは、全文テキスト付きの複数の結果が返されます。1 つのクエリで幅広く調べられます。トピックを「探る」ために複数回検索しないでください。適切なモードで的確なクエリを 1 つ選べば、十分に網羅できます。

ユーザーのリクエストが実際に 2 つの異なるトピックにまたがる場合に限り、最大 2 回まで呼び出せます（例：「X と Y を比較する」のように X と Y を別々に検索する必要がある場合や、異なる観点について default と current を 1 回ずつ呼び出す場合）。2 回を超えてはいけません。

次のことはしないでください：

• 「結果を増やす」ために、同じクエリを別の表現で検索する
• ページ全文のコンテンツがすでにあるのに、「さらに深掘りする」ために続けて検索する
• 何かを見つけるために検索してから、追加情報を得るためにもう一度検索する。すでに取得したコンテンツを読んでください

2 つの検索モード

モードは 2 つだけです。クエリに応じて適切なものを選んでください。

default — 一般検索（全期間）

• Google ウェブ検索（全期間）で 5 件の結果を取得し、それぞれにページ全文のコンテンツを付加します
• 用途：一般的な質問、調査、ハウツー、普遍的なトピック、製品情報、技術ドキュメント、比較、チュートリアル、時間に左右されないあらゆる内容

current — ニュースおよび最新情報

• 過去 1 週間の Google ウェブ検索（3 件）と Google ニュース（3 件）の結果を取得し、それぞれにページ全文のコンテンツを付加します
• 用途：ニュース、時事問題、最近の動向、速報、発表など、時間に左右される内容

モード選択ガイド

クエリの手がかり	モード
「X はどのように機能するか」「X とは何か」「X を説明して」	default
製品調査、比較、チュートリアル	default
技術ドキュメント、ガイド	default
歴史的なトピック、普遍的な内容	default
「ニュース」「最新」「今日」「今週」「最近」	current
「何が起きたか」「速報」「発表された」「リリースされた」	current
時事問題、政治、スポーツのスコア、株価	current

地域と言語

デフォルトはグローバルです。国のフィルターはなく、英語の検索結果が返されます。これは英語のクエリでのみ機能します。

次のいずれかに該当する場合は、必ず --gl と --hl を指定してください：

• ユーザーのメッセージが英語以外の言語で書かれている
• 作成する検索クエリが英語以外の言語である
• ユーザーが特定の国、都市、地域に言及している
• ユーザーが英語以外の文脈で、地域に限定した結果（価格、ニュース、店舗など）を求めている

ユーザーがドイツ語で書いている場合は、必ず --gl de --hl de を指定してください。例外はありません。

ケース	フラグ
英語のクエリで、対象国の指定なし	(--gl と --hl は省略)
ドイツ語のクエリ、ユーザーがドイツ語で記述、または DE/AT/CH が対象	--gl de --hl de
フランス語のクエリ、ユーザーがフランス語で記述、またはフランスが対象	--gl fr --hl fr
その他の英語以外の言語／国	--gl XX --hl XX（ISO コード）

目安： クエリ文字列に英語以外の単語が含まれる場合は、その言語に合わせて --gl と --hl を指定してください。

呼び出し方法

python3 scripts/search.py -q "QUERY" [--mode MODE] [--gl COUNTRY] [--hl LANG]

例

# English, general research
python3 scripts/search.py -q "how does HTTPS work"

# English, time-sensitive
python3 scripts/search.py -q "OpenAI latest announcements" --mode current

# German query — set locale + current mode for news/prices
python3 scripts/search.py -q "aktuelle Preise iPhone" --mode current --gl de --hl de

# German news
python3 scripts/search.py -q "Nachrichten aus Berlin" --mode current --gl de --hl de

# French product research
python3 scripts/search.py -q "meilleur smartphone 2026" --gl fr --hl fr

出力形式

スクリプトは JSON 配列をストリーム出力します。最初の要素はメタデータで、残りは抽出した全文コンテンツを含む検索結果です。

[{"query": "...", "mode": "default", "locale": {"gl": "world", "hl": "en"}, "results": [{"title": "...", "url": "...", "source": "web"}]}
,{"title": "Page Title", "url": "https://example.com", "source": "web", "content": "Full extracted page text..."}
,{"title": "News Article", "url": "https://news.com", "source": "news", "date": "2 hours ago", "content": "Full article text..."}
]

フィールド	説明
title	ページタイトル
url	ソース URL
source	"web"、"news"、または "knowledge_graph"
content	抽出したページ全文のテキスト（抽出に失敗した場合は検索スニペットを使用）
date	利用可能な場合に表示（ニュース結果では常に、ウェブ結果では場合による）

CLI リファレンス

フラグ	説明
-q, --query	検索クエリ（必須）
-m, --mode	default（全期間、5 件）または current（過去 1 週間＋ニュース、それぞれ 3 件）
--gl	国コード（例：de、us、fr、at、ch）。デフォルト：world
--hl	言語コード（例：en、de、fr）。デフォルト：en

エッジケース

• trafilatura がページからコンテンツを抽出できない場合、検索結果のスニペットを使用します。
• スクレイピングを全面的にブロックするサイトもあります。その場合、取得できるのはスニペットのみです。
• 結果が 0 件の場合、スクリプトは {"error": "No results found", "query": "..."} を出力して終了します。
• Serper API キーはスキルディレクトリ内の .env から読み込まれます。キーがない場合、スクリプトはセットアップ手順を表示して終了します。