Google Search

Google web search via Gemini Search Grounding (primary) and Custom Search JSON API (fallback). Use for: (1) Synthesized answers with citations (grounded sear...

Security Scan

The skill does what it says: it uses the Google GenAI library (Gemini grounding) and the Custom Search JSON API, requests the expected Google API key, and contains a reasonable installer and runtime script.

Purpose & Capability

Name/description, required env vars (GOOGLE_API_KEY and optional GOOGLE_CSE_CX), and the declared dependency (google-genai) align with a skill that performs Gemini-grounded search and falls back to Custom Search. No unrelated credentials or tools are requested.

Instruction Scope

SKILL.md and the Python code instruct the agent to call Gemini via google-genai and the Google Custom Search API. Runtime actions are limited to network calls to Google APIs and local formatting; there are no instructions to read unrelated files, harvest other environment variables, or send data to non-Google endpoints.

Install Mechanism

Installer is a simple install.sh that runs pip install google-genai and a smoke test. This is a moderate-risk but expected install method (PyPI package). The script uses --break-system-packages as a first attempt (falls back), which can affect system-managed Python on some systems — a minor operational concern. There are no downloads from personal servers or URL shorteners, and no archives extracted from arbitrary hosts. Note: registry summary indicated 'no install spec' but the package includes an install.sh and an install hint in SKILL.md metadata — minor metadata inconsistency.

Credentials

Only GOOGLE_API_KEY is required as the primary credential; GOOGLE_CSE_CX and locale vars are optional and justified by raw/image modes. No unrelated secrets are requested.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and does not persist elevated system-wide privileges. It runs on-demand and via normal autonomous invocation behavior.

Assessment

This skill appears coherent and implements Google Gemini grounding plus Custom Search as described. Before installing: (1) ensure you supply a Google API key with only the necessary APIs enabled (Gemini + Custom Search) and restrict its allowed IPs/referrers and billing limits where possible; (2) be aware pip will install the google-genai package from PyPI — verify the package/version you install and consider installing in a virtualenv or isolated environment; (3) the installer runs a smoke test that executes the skill script (which will make network calls), so run install in a controlled environment if you are cautious; (4) if you will use raw/image modes, supply your own GOOGLE_CSE_CX (the skill will not embed any CSE IDs); (5) monitor quota and billing for API usage. If you want higher assurance, review the full python file (included) or pin the google-genai version before installing.

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
GOOGLE_API_KEY	—	Required. Google API key
GOOGLE_CSE_CX	—	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:

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

Script Location

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

---

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.

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

When to use: Questions, current events, "what is X", Hebrew queries, anything needing a direct answer.

Examples:

# Hebrew (default)
python3 lib/google_search.py search "מזג אוויר תל אביב"

# English override
python3 lib/google_search.py search "latest AI news" --lang en --country US

# JSON output
python3 lib/google_search.py search "OpenAI GPT-5 release date" --json

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.

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

When to use: Need actual URLs, research, building reference lists, when you want links not answers.

Examples:

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

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.

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

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
--lang CODE	all	Language code (he, en, ar, ja…)	env GOOGLE_SEARCH_LANG (he)
--country CODE	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:

# Hebrew (default, no flags needed)
python3 lib/google_search.py search "חדשות טכנולוגיה"

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

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

---

Install

bash skills/google-search/install.sh