Google Gemini Provider: Setup, API Key, OAuth, and Features

The Google plugin gives you access to Gemini models via Google AI Studio, along with image generation, media comprehension (image, audio, and video), text-to-speech, and web search through Gemini Grounding.

• Provider: google
• Auth: GEMINI_API_KEY or GOOGLE_API_KEY
• API: Google Gemini API
• Runtime option: agentRuntime.id: "google-gemini-cli" reuses Gemini CLI OAuth while keeping model references canonical as google/*.

Getting started

Pick the authentication method that works for you and go through the setup steps.

API key

Best for: standard Gemini API access through Google AI Studio.

Get an API key

Generate a free key in Google AI Studio.

Run onboarding

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

Alternatively, pass the key directly:

openclaw onboard --non-interactive \
  --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 accepted. Use whichever one you have already set up.

Once an API key is configured, OpenClaw pulls the latest text-model catalog from the Gemini models.list API. This means newly released Gemini 3 Pro, Flash, and Flash-Lite variants show up in openclaw models list --provider google without needing an OpenClaw update. If discovery is unavailable, OpenClaw falls back to the bundled catalog.

Gemini CLI (OAuth)

Best for: signing in with your Google account through Gemini CLI OAuth rather than using a separate API key.

Warning

The google-gemini-cli provider is not an official integration. Some users have reported account restrictions when using OAuth this way. Proceed at your own risk.

Install the Gemini CLI

The local gemini command must be available on PATH.

# Homebrew
brew install gemini-cli

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

OpenClaw supports both Homebrew installs and global npm installs, including common Windows and npm layouts.

Log in via OAuth

openclaw models auth login --provider google-gemini-cli --set-default

Verify the model is available

openclaw models list --provider google

• Default model: google/gemini-3.1-pro-preview
• Runtime: google-gemini-cli
• Alias: gemini-cli

The Gemini API model id for Gemini 3.1 Pro is gemini-3.1-pro-preview. OpenClaw accepts the shorter google/gemini-3.1-pro as a convenience alias and normalizes it before making provider calls.

Environment variables:

• OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
• OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

Note

If Gemini CLI OAuth requests fail after login, set GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID on the gateway host and try again.

Note

If login fails before the browser flow starts, confirm the local gemini command is installed and on PATH.

Onboarding auto-detection will identify an existing Gemini CLI login but never auto-tests it, since Gemini CLI has no tool-free probe. Choose Gemini CLI OAuth or a Gemini API key to proceed.

google-gemini-cli/* model refs are legacy compatibility aliases. New configurations should use google/* model refs along with the google-gemini-cli runtime when local Gemini CLI execution is desired.

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) overwrites a stale configured default with the current model.

Capabilities

Web search

The bundled gemini web-search provider uses Gemini Google Search grounding. Configure a dedicated search key under plugins.entries.google.config.webSearch, or let it reuse models.providers.google.apiKey after 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 priority starts with webSearch.apiKey, followed by GEMINI_API_KEY, then models.providers.google.apiKey. You can optionally provide webSearch.baseUrl for operator proxies or compatible Gemini API endpoints. If it is not set, Gemini web search falls back to models.providers.google.baseUrl. Check Gemini search for tool behavior specific to this provider.

Tip

Gemini 3 models use thinkingLevel instead of thinkingBudget. OpenClaw maps Gemini 3, Gemini 3.1, and gemini-*-latest alias reasoning controls to thinkingLevel, so default or low-latency runs avoid sending disabled thinkingBudget values.

/think adaptive preserves Google's dynamic thinking semantics rather than picking a fixed OpenClaw level. For Gemini 3 and Gemini 3.1, no fixed thinkingLevel is sent, letting Google choose the level. Gemini 2.5 sends Google's dynamic sentinel thinkingBudget: -1.

Thinking mode is available on Gemma 4 models (for instance gemma-4-26b-a4b-it). OpenClaw converts thinkingBudget into a supported Google thinkingLevel for Gemma 4. Setting thinking to off keeps thinking disabled instead of mapping to MINIMAL.

Gemini 2.5 Pro only functions in thinking mode and refuses an explicit thinkingBudget: 0. OpenClaw removes that value for Gemini 2.5 Pro requests instead of sending it.

Image generation

The built-in google image generation provider uses google/gemini-3.1-flash-image as its default.

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

To set Google as the default image provider:

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

Note

Refer to Image Generation for shared tool parameters, provider selection, and failover behavior.

Video generation

The built-in google plugin also registers video generation 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 set Google as the default video provider:

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

Note

Refer to Video Generation for shared tool parameters, provider selection, and failover behavior.

Music generation

The built-in google plugin also registers music generation through the shared music_generate tool.

• Default music model: google/lyria-3-clip-preview
• Also supports google/lyria-3-pro-preview
• 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 set Google as the default music provider:

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

Note

Refer to Music Generation for shared tool parameters, provider selection, and failover behavior.

Text-to-speech

The built-in google speech provider uses the Gemini API TTS path with gemini-3.1-flash-tts-preview.

• Default voice model: Kore
• Authentication: tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY, or GOOGLE_API_KEY
• Output formats: WAV for standard TTS attachments, Opus for voice-note targets, PCM for Talk and telephony
• For voice notes, Google PCM is wrapped as WAV and then transcoded to 48 kHz Opus using ffmpeg

When you use Google's batch Gemini TTS path, the generated audio appears inside the completed generateContent response. For spoken conversations where latency is critical, choose the Google realtime voice provider that relies on the Gemini Live API instead of batch TTS.

To set Google as 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.",
      },
    },
  },
}

Style control in Gemini API TTS works through natural-language prompting. Use audioProfile to insert a reusable style prompt before the spoken text. Set speakerName when your prompt mentions a named speaker.

Gemini API TTS also processes expressive audio tags written in square brackets within the text, for example [whispers] or [laughs]. To prevent these tags from appearing in the visible chat reply while still sending them to TTS, enclose them inside a [[tts:text]]...[[/tts:text]] block:

Here is the clean reply text.

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

Note

An API key from Google Cloud Console that is restricted to the Gemini API works with this provider. This is not 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.

Here is an 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 adapts telephony and Meet bridge audio to Gemini's PCM Live API stream, and keeps tool calls on the shared realtime voice contract. Leave temperature unset unless you need sampling changes; OpenClaw omits non-positive values because Google Live can return transcripts without audio for temperature: 0. Gemini API transcription is enabled without languageCodes; the current Google SDK rejects language-code hints on this API path.

Note

Conversational text through realtime input is accepted by Gemini 3.1 Live, which 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 are mapped to the nearest supported level, while -1 leaves Google's default in place. See the Gemini Live capability comparison.

Note

Control UI Talk supports Google Live browser sessions using constrained one-use tokens. In Video Talk, the browser sends bounded JPEG frames directly to Google Live at the provider's maximum of one frame per second. The describe_view function reports whether that camera stream is active. Camera frames do not pass through the Gateway. Backend-only realtime voice providers can also run through the generic Gateway relay transport, which keeps provider credentials on the Gateway.

For maintainer live verification, run OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. The smoke also covers OpenAI backend and 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.

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.

• Use either cachedContent or legacy cached_content to configure per-model or global parameters
• Parameters 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

With the google-gemini-cli OAuth provider active, OpenClaw defaults to reading Gemini CLI stream-json output, then normalizes usage data from the final stats payload. The JSON parser remains in use for legacy --output-format json overrides.

• Streamed response text is sourced from assistant message events.
• For legacy JSON output, the reply text comes from the CLI JSON response field.
• When the CLI leaves usage empty, usage defaults to stats.
• OpenClaw normalizes stats.cached into cacheRead.
• If stats.input is absent, OpenClaw derives input tokens from stats.input_tokens - stats.cached.

Environment and daemon setup

When the Gateway runs as a daemon (launchd/systemd), confirm that GEMINI_API_KEY is accessible to that process, for instance by placing it in ~/.openclaw/.env or supplying it through env.shellEnv.

Related

• Model selection, Picking providers, model references, and failover logic.

• Image generation, Shared parameters for image tools and provider choice.

• Video generation, Shared parameters for video tools and provider choice.

• Music generation, Shared parameters for music tools and provider choice.