Google 搜索 🔍

由 Gemini 2.5 Flash 驱动的 Google 网页搜索，支持 Search Grounding（搜索溯源）及 Custom Search API。

⭐ 这是主要的网页搜索工具，优先于内置的 web_search（Perplexity）。

前提要求

• 设置环境变量 GOOGLE_API_KEY
• 在 Google Cloud Console 中启用以下 API：Gemini API、Custom Search JSON API

配置项

在 OpenClaw 配置中设置：

{
  "env": {
    "GOOGLE_API_KEY": "AIza...",
    "GOOGLE_SEARCH_LANG": "he",
    "GOOGLE_SEARCH_COUNTRY": "IL"
  }
}

脚本路径

python3 skills/google-search/lib/google_search.py  "query" [options]

输出模式

• 文本模式（默认）：适用于大多数场景。输出格式清晰易读，包含合成答案、信息来源及原始搜索查询。
• JSON 模式（--json）：适用于程序化处理。返回内容包含置信度评分、溯源依据（grounding supports）及原始搜索查询。

运行模式

search — 带溯源的搜索（默认，推荐）

使用 Gemini 2.5 Flash + Google 搜索工具 → 生成带编号引用的综合答案。

python3 lib/google_search.py search "query" [--lang he] [--country IL] [--json]

适用场景：回答问题、追踪时事、“什么是 X” 类查询、希伯来语查询，或任何需要直接答案的场景。

示例：

# 希伯来语（默认）
python3 lib/google_search.py search "מזג אוויר תל אביב"

# 强制指定英语
python3 lib/google_search.py search "latest AI news" --lang en --country US

# 输出 JSON 格式
python3 lib/google_search.py search "OpenAI GPT-5 release date" --json

输出格式：

<合成答案文本>

Sources:
  1. Source Title
     https://example.com/article
  2. Another Source
     https://example.com/other

raw — 原始搜索结果

调用 Custom Search JSON API → 返回带标题与摘要片段的链接列表。

python3 lib/google_search.py raw "query" [-n 5] [--lang he] [--country IL] [--json]

适用场景：需要获取真实 URL、开展研究、构建参考文献列表，或仅需链接而无需答案时。

示例：

python3 lib/google_search.py raw "python asyncio tutorial" -n 5
python3 lib/google_search.py raw "best restaurants tel aviv" --json
python3 lib/google_search.py raw "rust vs go performance" -n 3 --lang en

输出格式：

1. Page Title
   https://example.com/page
   Brief snippet from the page...

2. Another Page
   https://example.com/other
   Another snippet...

image — 图像搜索

调用 Custom Search 图像搜索功能 → 返回带标题的图像 URL 列表。

python3 lib/google_search.py image "query" [-n 5] [--lang he] [--country IL] [--json]

适用场景：查找图片、视觉参考资料、缩略图等。

示例：

python3 lib/google_search.py image "aurora borealis" -n 5
python3 lib/google_search.py image "תל אביב חוף" --json

选项参考

语言参数解析顺序： --lang 命令行参数 → GOOGLE_SEARCH_LANG 环境变量 → 未设置（自动检测）
国家/地区参数解析顺序： --country 命令行参数 → GOOGLE_SEARCH_COUNTRY 环境变量 → 未设置（自动检测）

错误处理

• 缺少 API 密钥： 显示清晰错误信息，并附带配置说明。
• 429 请求频率超限： 自动等待 5 秒后重试一次。
• 网络错误： 返回带有具体原因的描述性错误信息。
• 无搜索结果： 清晰提示 “No results found.”
• 请求超时： 所有 HTTP 请求均设为 30 秒超时。

配额与速率限制

遇到 429 错误时： 脚本将自动重试一次；若配额已完全耗尽，则自动回退至内置 web_search（Perplexity）。

多语言支持

支持任意语言的查询输入。希伯来语为默认语言：

# 希伯来语（默认，无需额外参数）
python3 lib/google_search.py search "חדשות טכנולוגיה"

# 英语
python3 lib/google_search.py search "technology news" --lang en

# 阿拉伯语
python3 lib/google_search.py search "أخبار التكنولوجيا" --lang ar

安装

bash skills/google-search/install.sh