OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Gemini search

OpenClaw supports Gemini models with built-in Google Search grounding, which returns AI-synthesized answers backed by live Google Search results with citations.

Get an API key

  • Create a key

    Go to Google AI Studio and create an API key.

  • Store the key

    Set GEMINI_API_KEY in the Gateway environment, reuse models.providers.google.apiKey, or configure a dedicated web-search key via:

    bash
    openclaw configure --section web

    • Config

    json5
    {  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-3.6-flash", // default          },        },      },    },  },  tools: {    web: {      search: {        provider: "gemini",      },    },  },}

    Credential precedence: Gemini web search uses plugins.entries.google.config.webSearch.apiKey first, then GEMINI_API_KEY, then models.providers.google.apiKey. For base URLs, the dedicated plugins.entries.google.config.webSearch.baseUrl wins before models.providers.google.baseUrl.

    For a gateway install, put env keys in ~/.openclaw/.env.

    Request headers

    Set plugins.entries.google.config.webSearch.headers when an operator gateway needs extra request metadata. Plain string values use normal config handling; they are not automatically treated as secret merely because they are headers. When a header contains a secret, use a SecretRef value as shown above. OpenClaw resolves that value at runtime and applies the existing secret redaction path to it.

    The Gemini request keeps ownership of Content-Type, x-goog-api-key, and x-goog-api-client; those values override same-named configured headers. models.providers.google.headers are not inherited because they belong to the model provider endpoint, which can differ from the web-search endpoint.

    Empty plain-string values are valid. Invalid fields and transport-owned or framing names such as Content-Length, Host, and Transfer-Encoding fail the current search before cache lookup or network I/O.

    Effective header names and values partition the in-memory search cache through a digest, so two routing targets do not share results. Configured values for the provider-owned names above are ignored and do not partition the cache. On a cross-origin redirect, the guarded fetch path retains only its standard safe redirect headers.

    How it works

    Unlike traditional search providers that return a list of links and snippets, Gemini uses Google Search grounding to produce AI-synthesized answers with inline citations. The results include both the synthesized answer and the source URLs.

    • Citation URLs from Gemini grounding are automatically resolved from Google redirect URLs to direct URLs via a HEAD request through OpenClaw's SSRF-guarded fetch path (redirect following, http/https validation).
    • Redirect resolution uses strict SSRF defaults, so redirects to private/internal targets are blocked.

    Supported parameters

    Gemini search supports query, freshness, date_after, and date_before.

    count is accepted for shared web_search compatibility, but Gemini grounding still returns one synthesized answer with citations rather than an N-result list.

    freshness accepts day, week, month, year, and the shared shortcuts pd, pw, pm, and py. day/pd adds a recency instruction to the Gemini query instead of a hard 24-hour range. week, month, year, and explicit date_after/date_before ranges set Gemini Google Search grounding's timeRangeFilter. country, language, and domain_filter are not supported.

    Model selection

    The default model is the stable gemini-3.6-flash. Omitting plugins.entries.google.config.webSearch.model uses this default; an explicit model stays pinned. You can select any Gemini model that supports grounding and is available to your API key.

    Gemini 3 grounding is billed per search query, while Gemini 2.5 grounding is billed per prompt. See Google Search grounding pricing.

    Base URL overrides

    Set plugins.entries.google.config.webSearch.baseUrl when Gemini web search must route through an operator proxy or custom Gemini-compatible endpoint. If that is unset, Gemini web search reuses models.providers.google.baseUrl. A plain https://generativelanguage.googleapis.com value is normalized to https://generativelanguage.googleapis.com/v1beta; custom proxy paths are kept as provided after trimming trailing slashes.

    Was this useful?
    On this page

    On this page