openclaw-serper

Serper

通过 Serper API 搜索 Google。获取搜索结果并读取实际网页，通过 trafilatura 提取干净的全文内容。不只是摘要，而是完整的文章正文。

限制

此技能已获取并提取完整的网页内容。请勿对此技能返回的 URL 使用 WebFetch、web_fetch、WebSearch、浏览器工具或任何其他 URL 获取／浏览工具。内容已包含在输出中。切勿另行获取内容——结果中已包含所需的一切。

查询规范

构造一个优质的搜索查询。这几乎总是足够的。

每次调用都会返回多个包含完整网页文本的结果；一次查询即可广泛覆盖主题。请勿为了“探索”主题而运行多次搜索。选择合适的模式并构造一个精心设计的查询即可覆盖所需内容。

仅当用户的请求确实涉及两个不同主题时，最多调用两次（例如，“比较 X 和 Y”，且 X 和 Y 需要分别搜索；或者针对不同方面分别调用一次 default 和一次 current）。绝不超过两次。

请勿：

• 用不同措辞运行相同查询来“获取更多结果”
• 连续搜索来“深入挖掘”——完整网页内容已经足够深入
• 先搜索以查找内容，再进行后续搜索——请阅读已有内容

两种搜索模式

仅有两种模式。请根据查询选择合适的模式：

default — 常规搜索（不限时间）

• Google 网页搜索（不限时间），5 条结果，每条均附有完整网页内容
• 适用于：常规问题、研究、操作指南、常青主题、产品信息、技术文档、比较、教程，以及任何非时效性内容

current — 新闻和近期信息

• 过去一周的 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（过去一周 + 新闻，各 3 条）
--gl	国家代码（例如：de、us、fr、at、ch）。默认值：world
--hl	语言代码（例如：en、de、fr）。默认值：en

边缘情况

• 如果 trafilatura 无法从页面提取内容，结果会回退到搜索摘要。
• 部分网站会完全禁止抓取，因此你只能获取摘要。
• 如果没有返回任何结果，脚本会退出并输出 {"error": "No results found", "query": "..."}。
• Serper API 密钥从技能目录中的 .env 加载。如果缺失，脚本会退出并显示设置说明。