Google Search 🔍
Google web search powered by Gemini 2.5 Flash with Search Grounding + Custom Search API.
⭐ This is the PRIMARY web search tool. Prefer over built-in web_search (Perplexity).
Requirements
- -
GOOGLE_API_KEY environment variable - Enable in Google Cloud Console: Gemini API, Custom Search JSON API
Configuration
| Env Variable | Default | Description |
|---|
| INLINECODE2 | — | Required. Google API key |
| INLINECODE3 |
— | Custom Search Engine ID (required for raw/image modes) |
|
GOOGLE_SEARCH_LANG |
he | Default language code (he, en, ar, ja, etc.) |
|
GOOGLE_SEARCH_COUNTRY |
IL | Default country code (IL, US, DE, etc.) |
Set in OpenClaw config:
CODEBLOCK0
Script Location
CODEBLOCK1
Output Modes
- - Text mode (default): Best for most use cases. Clean readable output with answer, sources, and search queries.
- JSON mode (
--json): For programmatic processing. Includes confidence scores, grounding supports, and search queries.
Modes
search — Grounded Search (Default, Recommended)
Gemini 2.0 Flash + Google Search tool → synthesized answer with numbered citations.
CODEBLOCK2
When to use: Questions, current events, "what is X", Hebrew queries, anything needing a direct answer.
Examples:
CODEBLOCK3
Output format:
<Synthesized answer text>
Sources:
1. Source Title
https://example.com/article
2. Another Source
https://example.com/other
raw — Raw Search Results
Custom Search JSON API → links with titles and snippets.
CODEBLOCK5
When to use: Need actual URLs, research, building reference lists, when you want links not answers.
Examples:
CODEBLOCK6
Output format:
1. Page Title
https://example.com/page
Brief snippet from the page...
2. Another Page
https://example.com/other
Another snippet...
image — Image Search
Custom Search image search → image URLs with titles.
CODEBLOCK8
When to use: Finding images, visual references, thumbnails.
Examples:
python3 lib/google_search.py image "aurora borealis" -n 5
python3 lib/google_search.py image "תל אביב חוף" --json
Options Reference
| Option | Applies To | Description | Default |
|---|
| INLINECODE9 | all | Language code (he, en, ar, ja…) | env GOOGLE_SEARCH_LANG (he) |
| INLINECODE11 |
all | Country code (IL, US, DE…) | env
GOOGLE_SEARCH_COUNTRY (IL) |
|
-n NUM | raw, image | Number of results (1–10) | 10 |
|
--json | all | Structured JSON output | off |
Language resolution order: --lang flag → GOOGLE_SEARCH_LANG env → None (auto)
Country resolution order: --country flag → GOOGLE_SEARCH_COUNTRY env → None (auto)
Error Handling
- - Missing API key: Clear error message with setup instructions.
- 429 Rate Limit: Automatic retry once after 5-second wait.
- Network errors: Descriptive error with cause.
- No results: Clean "No results found." message.
- Timeout: 30-second timeout on all HTTP requests.
Quota & Rate Limits
| API | Free Tier | Rate Limit |
|---|
| Gemini API (grounded search) | Generous free tier | ~15 RPM (free), higher on paid |
| Custom Search JSON API (raw/image) |
100 queries/day | 10K queries/day (paid) |
On 429 errors: Script retries once automatically. If quota exhausted, fall back to built-in web_search (Perplexity).
Multilingual Support
Works with queries in any language. Hebrew is the default:
CODEBLOCK10
Install
CODEBLOCK11
Google 搜索 🔍
由 Gemini 2.5 Flash 驱动的 Google 网页搜索，支持搜索接地 + 自定义搜索 API。
⭐ 这是主要的网页搜索工具。优先于内置的 web_search（Perplexity）。
要求
- - GOOGLEAPIKEY 环境变量
- 在 Google Cloud Console 中启用：Gemini API、自定义搜索 JSON API
配置
| 环境变量 | 默认值 | 描述 |
|---|
| GOOGLEAPIKEY | — | 必需。 Google API 密钥 |
| GOOGLECSECX |
— | 自定义搜索引擎 ID（raw/image 模式必需） |
| GOOGLE
SEARCHLANG | he | 默认语言代码（he、en、ar、ja 等） |
| GOOGLE
SEARCHCOUNTRY | IL | 默认国家代码（IL、US、DE 等） |
在 OpenClaw 配置中设置：
json
{
env: {
GOOGLEAPIKEY: AIza...,
GOOGLESEARCHLANG: he,
GOOGLESEARCHCOUNTRY: IL
}
}
脚本位置
bash
python3 skills/google-search/lib/google_search.py query [options]
输出模式
- - 文本模式（默认）：适用于大多数用例。输出包含答案、来源和搜索查询的清晰可读内容。
- JSON 模式（--json）：适用于程序化处理。包含置信度分数、接地支持和搜索查询。
模式
search — 接地搜索（默认，推荐）
Gemini 2.0 Flash + Google 搜索工具 → 带有编号引用的综合答案。
bash
python3 lib/google_search.py search query [--lang he] [--country IL] [--json]
使用场景： 问题、时事、什么是 X、希伯来语查询、任何需要直接答案的情况。
示例：
bash
希伯来语（默认）
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
输出格式：
<综合答案文本>
来源：
1. 来源标题
https://example.com/article
2. 另一个来源
https://example.com/other
raw — 原始搜索结果
自定义搜索 JSON API → 带有标题和摘要的链接。
bash
python3 lib/google_search.py raw query [-n 5] [--lang he] [--country IL] [--json]
使用场景： 需要实际 URL、研究、构建参考列表、需要链接而非答案时。
示例：
bash
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. 页面标题
https://example.com/page
来自页面的简短摘要...
- 2. 另一个页面
https://example.com/other
另一个摘要...
image — 图片搜索
自定义搜索图片搜索 → 带有标题的图片 URL。
bash
python3 lib/google_search.py image query [-n 5] [--lang he] [--country IL] [--json]
使用场景： 查找图片、视觉参考、缩略图。
示例：
bash
python3 lib/google_search.py image aurora borealis -n 5
python3 lib/google_search.py image תל אביב חוף --json
选项参考
| 选项 | 适用范围 | 描述 | 默认值 |
|---|
| --lang CODE | 全部 | 语言代码（he、en、ar、ja…） | 环境变量 GOOGLESEARCHLANG（he） |
| --country CODE |
全部 | 国家代码（IL、US、DE…） | 环境变量 GOOGLE
SEARCHCOUNTRY（IL） |
| -n NUM | raw、image | 结果数量（1–10） | 10 |
| --json | 全部 | 结构化 JSON 输出 | 关闭 |
语言解析顺序： --lang 标志 → GOOGLESEARCHLANG 环境变量 → 无（自动）
国家解析顺序： --country 标志 → GOOGLESEARCHCOUNTRY 环境变量 → 无（自动）
错误处理
- - 缺少 API 密钥： 清晰的错误信息及设置说明。
- 429 速率限制： 等待 5 秒后自动重试一次。
- 网络错误： 包含原因的描述性错误。
- 无结果： 清晰的未找到结果。消息。
- 超时： 所有 HTTP 请求 30 秒超时。
配额和速率限制
| API | 免费层级 | 速率限制 |
|---|
| Gemini API（接地搜索） | 慷慨的免费层级 | 约 15 RPM（免费），付费更高 |
| 自定义搜索 JSON API（raw/image） |
100 次查询/天 | 10K 次查询/天（付费） |
429 错误时： 脚本自动重试一次。如果配额耗尽，回退到内置的 web_search（Perplexity）。
多语言支持
支持任何语言的查询。希伯来语为默认：
bash
希伯来语（默认，无需标志）
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
bash skills/google-search/install.sh
