Google Gemini Provider Setup and Configuration

The Google plugin grants access to Gemini models via Google AI Studio, along with image generation, media comprehension covering images, audio, and video, text-to-speech, and web search powered by Gemini Grounding.

• Provider: google
• Auth: GEMINI_API_KEY or GOOGLE_API_KEY
• API: Google Gemini API
• Managed-cloud provider: google-vertex with Google Cloud Application Default Credentials
• Optional runtime: agentRuntime.id: "google-gemini-cli" executes a specifically configured model through the local Gemini CLI

Getting started

For the majority of setups, an API key from Google AI Studio is the way to go. Opt for google-vertex when the Gateway is already operating inside a managed Google Cloud environment.

AI Studio API key

Recommended for: standard Gemini API access.

Get an API key

A free key can be created in Google AI Studio.

Run onboarding

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

Alternatively, supply the key directly:

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"

Set a default model

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}

Verify the model is available

openclaw models list --provider google

Tip

Both GEMINI_API_KEY and GOOGLE_API_KEY are valid. Go with whichever one is already set up in your environment.

Once an API key is configured, OpenClaw pulls the text-model list from Google AI Studio through the Gemini models.list API. This means newly launched Gemini 3 Pro, Flash, and Flash-Lite variants show up in openclaw models list --provider google without requiring an OpenClaw update. Should discovery fail, OpenClaw falls back to the catalog that ships with it.

Gemini CLI runtime

Advanced use only: run a canonical google/* model through an installed Gemini CLI while keeping authentication on the supported AI Studio API-key path.

OpenClaw does not offer new Gemini CLI OAuth or Antigravity OAuth setup. Google ended consumer Gemini CLI Login with Google access on June 18, 2026, and the Antigravity terms prohibit third-party tools from accessing the service through Antigravity OAuth. Use an AI Studio API key or Vertex AI instead.

Configure Google AI Studio

Finish the API-key configuration in the first tab. OpenClaw requires a working google API-key profile before the CLI runtime becomes selectable.

Install Gemini CLI

The gemini command needs to be present locally on PATH.

# Homebrew
brew install gemini-cli

# or npm
npm install -g @google/gemini-cli

OpenClaw accommodates both Homebrew and global npm installations, including typical Windows/npm directory layouts.

Select the CLI runtime

Maintain the canonical Google model ref and enable the CLI runtime for that model:

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
      models: {
        "google/gemini-3.1-pro-preview": {
          agentRuntime: { id: "google-gemini-cli" },
        },
      },
    },
  },
}

• Runtime: google-gemini-cli
• Auth: selected Google AI Studio API-key profile
• Model refs: canonical google/*

Existing valid Gemini CLI OAuth profiles continue to run for compatibility reasons, but OpenClaw cannot create or fix them. If one stops working, swap it out for a Google AI Studio API-key profile.

google-gemini-cli/* refs remain legacy compatibility aliases. New configs should use google/* model refs plus the explicit runtime selection above.

Note

google/gemini-3-pro-preview was retired on 2026-03-09; use google/gemini-3.1-pro-preview instead. Re-running Gemini API key setup (openclaw onboard --auth-choice gemini-api-key or openclaw models auth login --provider google) rewrites a stale configured default to the current model.

Capabilities

Web search

The bundled gemini web-search provider relies on Gemini Google Search grounding. Set up a dedicated search key under plugins.entries.google.config.webSearch, or allow it to reuse models.providers.google.apiKey following GEMINI_API_KEY:

{
  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", // falls back to models.providers.google.baseUrl
            model: "gemini-2.5-flash",
          },
        },
      },
    },
  },
}

Credential precedence goes dedicated webSearch.apiKey first, then GEMINI_API_KEY, and finally models.providers.google.apiKey. webSearch.baseUrl is optional, intended for operator proxies or compatible Gemini API endpoints; when absent, Gemini web search falls back to models.providers.google.baseUrl. For provider-specific tool behavior, check Gemini search.

Tip

For Gemini 3 models, thinkingLevel is used instead of thinkingBudget. When handling Gemini 3, Gemini 3.1, and gemini-*-latest, OpenClaw maps reasoning controls to thinkingLevel, so runs at default or low latency avoid sending disabled thinkingBudget values.

Rather than locking in a fixed OpenClaw level, /think adaptive preserves Google's dynamic thinking semantics. No fixed thinkingLevel is sent for Gemini 3 and Gemini 3.1, letting Google pick the level; Gemini 2.5 transmits Google's dynamic sentinel thinkingBudget: -1.

Thinking mode is available on Gemma 4 models, such as gemma-4-26b-a4b-it. For Gemma 4, OpenClaw converts thinkingBudget into a supported Google thinkingLevel. When thinking is set to off, thinking stays disabled rather than being translated to MINIMAL.

Gemini 2.5 Pro operates exclusively in thinking mode and rejects an explicit thinkingBudget: 0; OpenClaw removes that value from Gemini 2.5 Pro requests instead of forwarding it.

Image generation

The bundled google image-generation provider is set to google/gemini-3.1-flash-image by default.

• google/gemini-3-pro-image is also supported
• Generate: up to 4 images per request
• Edit mode: enabled, up to 5 input images
• Geometry controls: size, aspectRatio, and resolution

To make Google the default image provider:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "google/gemini-3.1-flash-image",
        },
      },
    },
  },
}

Note

Shared tool parameters, provider selection, and failover behavior are covered in Image Generation.

Video generation

Video generation is also registered by the bundled google plugin through the shared video_generate tool.

• Default video model: google/veo-3.1-fast-generate-preview
• Modes: text-to-video, image-to-video, and single-video reference flows
• Supports aspectRatio (16:9, 9:16) and resolution (720P, 1080P); Veo currently does not support audio output
• Supported durations: 4, 6, or 8 seconds (other values snap to the nearest allowed value)

To make Google the default video provider:

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "google/veo-3.1-fast-generate-preview",
        },
      },
    },
  },
}

Note

Shared tool parameters, provider selection, and failover behavior are covered in Video Generation.

Music generation

The bundled google plugin additionally registers music generation through the shared music_generate tool.

• Default music model: google/lyria-3-clip-preview
• google/lyria-3-pro-preview is also supported
• Prompt controls: lyrics and instrumental
• Output format: mp3 by default, plus wav on google/lyria-3-pro-preview
• Reference inputs: up to 10 images
• Session-backed runs detach through the shared task/status flow, including action: "status"

To make Google the default music provider:

{
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "google/lyria-3-clip-preview",
        },
      },
    },
  },
}

Note

Shared tool parameters, provider selection, and failover behavior are covered in Music Generation.

Text-to-speech

The bundled google speech provider routes through the Gemini API TTS path with gemini-3.1-flash-tts-preview.

• Default voice: Kore
• Auth: tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY, or GOOGLE_API_KEY
• Output: WAV for regular TTS attachments, Opus for voice-note targets, PCM for Talk/telephony
• Voice-note output: Google PCM is wrapped as WAV and transcoded to 48 kHz Opus with ffmpeg

Generated audio from Google's batch Gemini TTS path arrives in the completed generateContent response. For spoken conversations with the least latency, opt for the Google realtime voice provider, which relies on the Gemini Live API, rather than batch TTS.

To make Google the default TTS provider:

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        model: "gemini-3.1-flash-tts-preview",
        speakerVoice: "Kore",
        audioProfile: "Speak professionally with a calm tone.",
      },
    },
  },
}

Gemini API TTS relies on natural-language prompting to control style. Assign audioProfile to insert a reusable style prompt ahead of the spoken text. Assign speakerName when your prompt text references a specific speaker.

Expressive square-bracket audio tags, such as [whispers] or [laughs], are also accepted by Gemini API TTS within the text. To prevent those tags from appearing in the visible chat reply while still transmitting them to TTS, enclose them in a [[tts:text]]...[[/tts:text]] block:

Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

Note

A Google Cloud Console API key scoped to the Gemini API works with this provider. This is distinct from the separate Cloud Text-to-Speech API path.

Realtime voice

The included google plugin registers a realtime voice provider backed by the Gemini Live API, intended for backend audio bridges like Voice Call and Google Meet.

Example Voice Call realtime configuration:

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          realtime: {
            enabled: true,
            provider: "google",
            providers: {
              google: {
                model: "gemini-3.1-flash-live-preview",
                speakerVoice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "audio-activity-and-all-video",
              },
            },
          },
        },
      },
    },
  },
}

Note

Bidirectional audio and function calling over a WebSocket are provided by the Google Live API. OpenClaw converts telephony/Meet bridge audio into Gemini's PCM Live API stream and maintains tool calls on the shared realtime voice contract. Leave temperature unset unless you need sampling changes; OpenClaw drops non-positive values because Google Live can return transcripts without audio for temperature: 0. Gemini API transcription is active without languageCodes; the current Google SDK rejects language-code hints on this API path.

Note

Conversational text arrives through realtime input on Gemini 3.1 Live, which also uses sequential function calling. OpenClaw omits the older NON_BLOCKING, function response scheduling, and affective-dialog fields for this model. Prefer thinkingLevel; configured positive thinkingBudget values map to the nearest supported level, while -1 preserves Google's default. Consult the Gemini Live capability comparison.

Note

Control UI Talk supports Google Live browser sessions with restricted one-use tokens. In Video Talk, the browser sends bounded JPEG frames straight to Google Live at the provider's cap of one frame per second. The describe_view function indicates whether that camera stream is live. Camera frames bypass the Gateway. Backend-only realtime voice providers can also operate through the generic Gateway relay transport, which keeps provider credentials on the Gateway.

For maintainer live verification, execute OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. The smoke also covers OpenAI backend/WebRTC paths; the Google leg mints the same constrained Live API token shape used by Control UI Talk, opens the browser WebSocket endpoint, sends the initial setup payload plus a JPEG frame, and verifies a text response and describe_view function roundtrip. The OpenAI path also performs a synthesized PCM24 speech-to-response audio roundtrip; pass --openai-audio-cycles 3 for a short repeated lifecycle soak.

Advanced configuration

Direct Gemini cache reuse

For direct Gemini API runs (api: "google-generative-ai"), OpenClaw passes a configured cachedContent handle through to Gemini requests.

• Configure per-model or global params with either cachedContent or legacy cached_content
• Params from a more specific scope (model-level over global) always win. Within the same scope, if both keys are set, cached_content wins. Use only one key per scope to avoid surprises.
• Example value: cachedContents/prebuilt-context
• Gemini cache-hit usage is normalized into OpenClaw cacheRead from upstream cachedContentTokenCount

{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}

Gemini CLI usage notes

The optional google-gemini-cli runtime uses Gemini CLI stream-json output by default and normalizes usage from the final stats payload. Legacy --output-format json overrides still use the JSON parser.

• Assistant message events carry the streamed reply text.
• When outputting legacy JSON, the reply text sits in the CLI JSON response field.
• If the CLI leaves usage blank, usage defaults to stats.
• OpenClaw normalizes stats.cached into cacheRead.
• In cases where stats.input is absent, OpenClaw calculates input tokens from stats.input_tokens - stats.cached.

Environment and daemon setup

When the Gateway operates as a daemon (launchd/systemd), confirm that GEMINI_API_KEY is accessible to that process, such as through ~/.openclaw/.env or env.shellEnv.

Related

• Model selection, How to pick providers, model references, and failover behavior.

• Image generation, Common image tool parameters and how to choose a provider.

• Video generation, Shared video tool settings and provider selection.

• Music generation, Standard music tool parameters and provider selection.