Gemini Search with Google Grounding

OpenClaw ships with Gemini model support that includes Google Search grounding, so you get AI-generated answers that draw on live Google Search results and include citations.

Get an API key

Create a key

Head over to Google AI Studio and generate an API key.

Store the key

Define GEMINI_API_KEY in the Gateway environment, reuse models.providers.google.apiKey, or point a separate web-search key at it via:

openclaw configure --section web

Config

{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional; falls back to models.providers.google.baseUrl
            headers: {
              "X-Routing-Target": "staging",
              "X-Gateway-Token": {
                source: "env",
                provider: "default",
                id: "GEMINI_GATEWAY_TOKEN",
              },
            },
            model: "gemini-2.5-flash", // default
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "gemini",
      },
    },
  },
}

How credentials are chosen: the web-search path checks plugins.entries.google.config.webSearch.apiKey first, falls back to GEMINI_API_KEY, and finally to models.providers.google.apiKey. When it comes to base URLs, the dedicated plugins.entries.google.config.webSearch.baseUrl takes priority over models.providers.google.baseUrl.

For gateway deployments, place the env keys in ~/.openclaw/.env.

Request headers

When an operator gateway must attach extra request metadata, set plugins.entries.google.config.webSearch.headers. Ordinary string values follow standard config handling; being headers does not automatically mark them as secrets. If a header does hold a secret, supply a SecretRef value, like in the example above. OpenClaw resolves that value at runtime and routes it through the current secret redaction mechanism.

The Gemini request keeps ownership of Content-Type, x-goog-api-key, and x-goog-api-client; any configured headers with those names get overridden. models.providers.google.headers are not carried over, since they belong to the model provider endpoint, which may differ from the web-search endpoint.

Empty plain-string values are accepted. Fields that are invalid, or names owned by transport or framing layers such as Content-Length, Host, and Transfer-Encoding, abort the current search before cache lookup or any network I/O.

The in-memory search cache is partitioned by a digest of effective header names and values, so two different routing targets never share results. Configured values for the provider-owned names above are discarded and do not affect cache partitioning. When a cross-origin redirect occurs, the guarded fetch path keeps only its usual safe redirect headers.

How it works

Conventional search providers hand back a list of links with snippets. Gemini behaves differently: it uses Google Search grounding to craft AI-synthesized answers with inline citations. The output carries both the synthesized answer and the source URLs.

Citation URLs from Gemini grounding are turned from Google redirect URLs into direct URLs automatically, using a HEAD request that goes through OpenClaw's SSRF-guarded fetch path (redirect following, http/https validation).
Redirect resolution enforces strict SSRF defaults, so redirects aimed at private/internal targets are refused.

Supported parameters

Gemini search works with query, freshness, date_after, and date_before.

For shared web_search compatibility, count is accepted, but Gemini grounding still delivers one synthesized answer with citations rather than a list of N results.

freshness understands day, week, month, year, plus the shared shortcuts pd, pw, pm, and py. Using day/pd adds a recency instruction to the Gemini query instead of enforcing a strict 24-hour window. week, month, year, and explicit date_after/date_before ranges configure timeRangeFilter on Gemini Google Search grounding. country, language, and domain_filter are not supported.

Model selection

By default the model is gemini-2.5-flash (fast and cost-effective). Any Gemini model that supports grounding can be selected through plugins.entries.google.config.webSearch.model.

Base URL overrides

Set plugins.entries.google.config.webSearch.baseUrl whenever Gemini web search needs to go through an operator proxy or a custom endpoint that is Gemini-compatible. When that setting is left empty, models.providers.google.baseUrl is used again by Gemini web search. A basic https://generativelanguage.googleapis.com value gets normalized into https://generativelanguage.googleapis.com/v1beta; custom proxy paths remain exactly as you entered them, with any trailing slashes removed.

Web Search overview -- covers all providers and automatic detection
Brave Search -- delivers structured results complete with snippets
Perplexity Search -- offers structured results along with content extraction