Google (Gemini)

The Google plugin provides access to Gemini models through Google AI Studio, plus image generation, media understanding (image/audio/video), text-to-speech, and web search via 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" runs an explicitly configured model through the local Gemini CLI

Getting started

For most installations, use a Google AI Studio API key. Use google-vertex when the Gateway already runs inside a managed Google Cloud environment.

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

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

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

openclaw models list --provider google

# Homebrewbrew install gemini-cli # or npmnpm install -g @google/gemini-cli

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

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 precedence is dedicated webSearch.apiKey, then GEMINI_API_KEY, then models.providers.google.apiKey. webSearch.baseUrl is optional and exists for operator proxies or compatible Gemini API endpoints; when omitted, Gemini web search reuses models.providers.google.baseUrl. See Gemini search for the provider-specific tool behavior.

Image generation

The bundled google image-generation provider defaults to google/gemini-3.1-flash-image.

• 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 use Google as the default image provider:

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

Video generation

The bundled 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); audio output is not supported by Veo today
• Supported durations: 4, 6, or 8 seconds (other values snap to the nearest allowed value)

To use Google as the default video provider:

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

Music generation

The bundled 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 use Google as the default music provider:

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

Text-to-speech

The bundled google speech provider uses 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

Google's batch Gemini TTS path returns generated audio in the completed generateContent response. For lowest-latency spoken conversations, use the Google realtime voice provider backed by the Gemini Live API instead of batch TTS.

To use 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.",      },    },  },}

Gemini API TTS uses natural-language prompting for style control. Set audioProfile to prepend a reusable style prompt before the spoken text. Set speakerName when your prompt text refers to a named speaker.

Gemini API TTS also accepts expressive square-bracket audio tags in the text, such as [whispers] or [laughs]. To keep tags out of the visible chat reply while sending them to TTS, put them inside a [[tts:text]]...[[/tts:text]] block:

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

Realtime voice

The bundled google plugin registers a realtime voice provider backed by the Gemini Live API for backend audio bridges such as Voice Call and Google Meet.

Example Voice Call realtime config:

{  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",              },            },          },        },      },    },  },}

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/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

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

Related