OpenClaw with Gemini: model setup, API keys and cost checks

OpenClaw reaches Gemini through its bundled google plugin: set GEMINI_API_KEY or GOOGLE_API_KEY, run openclaw onboard --auth-choice gemini-api-key, then set the model explicitly — because adding auth does not change your default model. The part most setup posts miss is that on an AI Studio key OpenClaw has three separate Gemini surfaces, each with its own credential, endpoint and bill. (Vertex AI is a fourth, separate credential path through gcloud Application Default Credentials, and is not covered here.) Getting chat working does not enable Gemini search, and enabling Gemini search can put a charge on a Google project your chat route never touches.

The Gemini integration is not a separate install. It ships inside OpenClaw itself as the bundled google provider plugin (official provider plugins, September 21, 2026), and OpenClaw is MIT-licensed and published as openclaw@2026.9.5 on npm, requiring Node >=24.16.0 <25 || >=26.1.0 (npm registry, September 21, 2026). The software costs nothing; everything below is about what the keys cost.

Three Gemini surfaces, three credentials

The precedence rules are the useful part. Gemini web search reads plugins.entries.google.config.webSearch.apiKey first, then GEMINI_API_KEY, then models.providers.google.apiKey, and the dedicated webSearch.baseUrl wins before models.providers.google.baseUrl. OpenClaw also declines to inherit model-provider headers here, because they "belong to the model provider endpoint, which can differ from the web-search endpoint", and keeps ownership of Content-Type, x-goog-api-key and x-goog-api-client on the search request (Gemini search docs, September 21, 2026). Two routes, deliberately independent.

Before following an older tutorial: OpenClaw states it "does not offer new Gemini CLI OAuth or Antigravity OAuth setup", citing the end of consumer Gemini CLI Login with Google access on June 18, 2026 (provider docs). Google's own post of May 19, 2026 says Gemini CLI and Code Assist IDE extensions stop serving Google AI Pro and Ultra subscribers and free users (Google developers blog). Both statements are about the CLI and IDE surface, not about AI Studio API keys — the API-key path is the one below.

Setting the Gemini API key

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

openclaw onboard --auth-choice gemini-api-key

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

The bundled plugin also reads GEMINI_API_KEYS, GEMINI_API_KEY_1 and GEMINI_API_KEY_2 for rotation and OPENCLAW_LIVE_GEMINI_KEY as a single override (official provider plugins, September 21, 2026). Those are documented as the google plugin's own variables; the custom-provider reference does not list them for a provider id you declare yourself, which sets its key through apiKey ($${ENV_VAR} expansion is shown there).

The last line matters more than it looks. openclaw configure "preserves an existing agents.defaults.model.primary when you add or reauth a provider", and openclaw models auth login does the same unless you pass --set-default (quick rules). Authenticating Gemini and still getting answers from the old model is expected behaviour, not a bug.

Do not copy a model id from any tutorial, this one included. With a configured key OpenClaw refreshes Google AI Studio's text-model catalog from the Gemini models.list API, so new variants appear without an OpenClaw release — and OpenClaw's own pages disagree about the example id, naming google/gemini-3.5-flash in one place, google/gemini-3.1-flash and google/gemini-3.1-pro-preview in another, and defaulting the search tool to gemini-3.6-flash. The live list is the only authority. OpenClaw does normalize some legacy refs — google/gemini-3.1-pro is "accepted and normalized" to google/gemini-3.1-pro-preview (official provider plugins) — and google/gemini-3-pro-preview "was retired on 2026-03-09", with google/gemini-3.1-pro-preview named as its replacement (provider docs, September 21, 2026).

What a Gemini API key actually bills

Tokens and search grounding are two line items, and Google's page reads as one at a glance. Standard-tier Gemini Developer API rates per 1M tokens, from Google's pricing page (last updated September 16, 2026, read September 21, 2026):

Read the last column twice. OpenClaw's default Gemini web-search model is gemini-3.6-flash, a Gemini 3.x model whose grounding is "Not available" on Google's free tier — so the out-of-the-box Gemini search setup needs a billed project even though the same model's tokens are free. The units differ too: OpenClaw itself notes that "Gemini 3 grounding is billed per search query, while Gemini 2.5 grounding is billed per prompt", and Google adds that a request "may result in one or more queries to Google Search. You will be charged for each individual search query performed". Grounding sits on top of token cost — "Costs for Gemini always apply" (both quotes from the same pricing page). Illustratively, a month with 6,500 Gemini 3.x search queries bills 1,500 of them at $14 per 1,000, or $21.00 in search fees alone, before any tokens.

Two more inputs from the same page: the paid tier adds context caching and a Batch API at a 50% cost reduction, and it flips the data-use bullet — free tier content is "used to improve our products", paid content is not, which matters for an always-on assistant. Gemini is also only one of OpenClaw's search providers; DuckDuckGo ("None (key-free)"), SearXNG ("None (self-hosted)") and Parallel Search (Free) ("None (free Search MCP)") are listed as key-free options in its web-search provider table (web search, September 21, 2026), so "do I need Gemini grounding at all" is a fair first question.

Routing Gemini chat through an OpenAI-compatible gateway

OpenClaw's custom-provider reference says to use explicit models.providers.<id> entries "only when you want to override the default base URL, headers, or model list", and the gateway configuration reference lists an api enum of openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages and azure-openai-responses. Kunavo's Gemini models are reached over its OpenAI-compatible surface at POST /v1/chat/completions (chat endpoint), and Kunavo publishes no generativelanguage or v1beta endpoint — so the reachable route is a separate provider id, never a redirected google plugin.

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

Four details there are load-bearing. The slug is dashed — Kunavo's id is gemini-3-8-flash where Google's and OpenClaw's are dotted, and those are different strings. contextWindow is declared because a custom model with no context metadata falls back to a 200,000-token budget, wasting most of the window Kunavo's catalog records here (1,048,576 tokens — Kunavo's metadata, not a Google-published limit). input names images because OpenClaw defaults a custom model to text only. And cost is omitted, so OpenClaw's local estimate defaults to zero on this route: a $0 readout is missing metadata, not free inference.

What this route gives up is documented rather than guessed. On api: "openai-completions" against a host that is not OpenAI's own, OpenClaw forces compat.supportsDeveloperRole: false and skips native request shaping — no service_tier, no Responses or Completions store, no prompt-cache hints, no reasoning-compat payload shaping (custom providers). The Gemini-specific extras stay behind too: params.cachedContent is documented for direct Gemini runs, the key-rotation variables are plugin features, and OpenClaw's thinkingLevel / thinkingBudget mapping is described for the google provider — whether it survives a gateway route is not something this page verified.

Kunavo serves no embedding model and no text-to-speech or speech-to-text model. The google plugin's embedding and speech contracts therefore stay on a Google key regardless of how chat is routed.

On capabilities, be careful whose word you are taking. Google's current model page no longer renders per-model token limits, so a context figure quoted anywhere else is somebody's copy of an older source. Kunavo's catalog flags vision, function calling, streaming and long context on its Gemini listings, and thinking on all but gemini-2-5-flash. Each claim is scoped to whoever published it — verify tool calls on your own task first.

Price the model you actually chose

Per-model, against Google's Standard tier, because the family-wide version of this comparison is false today:

Kunavo rates come from the live catalog and Google's from the pricing page read September 21, 2026; the intro window closes on December 31, 2026, after which the Flash comparison inverts again.

A worked estimate, which is token arithmetic and not a measured OpenClaw task or a bill ceiling. Assume a week of assistant work sending 4,000,000 uncached input tokens and receiving 150,000 output tokens, with no caching and no search. On Gemini 3.8 Flash at Kunavo's rates that is $2.49; the same arithmetic on Google's intro Flash rate is $3.56, rising to $7.13 on the 2027 rate. Run the same volumes on Gemini 3.6 Flash at Kunavo and you get $4.99 — above the Google intro figure, which is exactly why the model id, not the provider name, is the decision.

Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. Cache charges, search grounding and hosting sit outside this example, and the minimum top-up is $10 in prepaid credit — a funding minimum, not a task fee or a subscription. See billing details, and OpenClaw pricing for the full operating bill.

Verify with one request, then read both ledgers

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list reads published inventory and openclaw models status shows the resolved default and auth state; neither proves a paid task works, and openclaw models set on a known provider saves an uncatalogued model with only a warning. openclaw doctor --json --severity-min info also surfaces active models the local catalog cannot confirm (CLI reference). The single request above is the first evidence that costs money.

Triage by status code. OpenClaw documents the model_not_found signature for a local OpenAI-compatible server, and the three fields it names are the same three a custom provider entry sets: verify the baseUrl includes /v1, that api is "openai-completions" for a /v1/chat/completions backend, and that models[].id is the bare provider-local id, with the provider prefix used only at selection time (troubleshooting). Against Kunavo, the check that tells you the base URL is right is an unauthenticated request to a real API path: GET https://api.kunavo.com/v1/models answers 401 with an authentication_error body, meaning the URL is right and the key is not. The bare host and the bare /v1 path are not API paths and answer with HTML, so a client pointed at either will fail before it ever reaches a model (checked September 21, 2026). A 403 is the one to stop and read: OpenClaw warns it "can come from an upstream security layer such as a CDN, WAF, bot-management rule, or reverse proxy", and that a successful minimal curl does not guarantee real SDK-style requests pass the same layer. See model not found and Gemini API key not working for the longer versions.

For the native route, start at Kunavo's Gemini API key notes and Google AI Studio; for the gateway route, create a key in API keys and open a Kunavo account, then follow the custom-provider walkthrough in best API for OpenClaw. Keep your working route available while you test.

Which route wins when

If you are still choosing a provider rather than configuring one, Gemini API pricing and OpenAI-compatible API cover the two halves of that decision.

FAQ

Fetched for this page on September 21, 2026: OpenClaw's Google-provider, official-provider-plugins, Gemini-search, web-search, custom-provider (both the concepts and the gateway reference), quick-rules, CLI-models and troubleshooting documentation; Google's Gemini API pricing page (last updated September 16, 2026), its models page, its Google Search grounding page and its May 19, 2026 developers-blog post; the npm registry entry for openclaw; and Kunavo's own catalog. The only live request made for this page was an unauthenticated GET to Kunavo's /v1/models, to record the 401 described above. Nothing here was runtime-tested against an OpenClaw installation, on Kunavo's endpoint or on Google's; every dollar figure is illustrative arithmetic on published rates.