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
• Default model: google/gemini-4-argon
• 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 --accept-risk --skip-health \  --mode local \  --auth-choice gemini-api-key \  --gemini-api-key "$GEMINI_API_KEY"

{  agents: {    defaults: {      model: { primary: "google/gemini-4-argon" },    },  },}

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

Gemini 4 Argon

google/gemini-4-argon is the default Google model, with a 1,048,576-token context window and up to 65,536 output tokens. google/gemini-4 is its shorthand; the same model ID and shorthand are available for google-vertex.

Gemini 4 Argon supports text, image, audio, video, and PDF inputs, function calling, structured outputs, and search grounding. It uses implicit context caching only: explicit cachedContents handles and the Live API are not supported. See Google's model documentation.

The bundled catalog also includes the stable google/gemini-3.8-flash, with a 1,048,576-token context window and up to 65,536 output tokens. The built-in gemini-flash alias selects this model; gemini-flash-lite selects google/gemini-3.5-flash-lite.

Capabilities

Responses marked MAX_TOKENS or CONTINUATION reached a generation limit. OpenClaw preserves their partial content and reports a length-limited result. Function calls in that partial response remain incomplete instead of becoming an executable tool-use turn.

The managed Gemini and Vertex transports stop reading when a compatible proxy sends data: [DONE], release the response body, and ignore later frames. A valid candidate finish reason is still required for a successful result. First-frame quota errors participate in API-key rotation. For Gemini's first-response retry, usage metadata, response IDs, and empty or unspecified finish states do not count as generated output or disable the existing retry deadline.

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-3.6-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: {      mediaModels: {        image: {          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: {      mediaModels: {        video: {          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: {      mediaModels: {        music: {          primary: "google/lyria-3-clip-preview",        },      },    },  },}

Text-to-speech

The bundled google speech provider uses Gemini API TTS. The default model stays gemini-3.1-flash-tts-preview. Set model to gemini-3.8-flash-tts to opt in to Gemini 3.8, or gemini-3.8-flash-lite-tts for the faster, lower-cost variant. gemini-2.5-flash-preview-tts and gemini-2.5-pro-preview-tts remain available.

• 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

Malformed or oversized successful TTS responses are reported without automatically submitting another Google synthesis request. Transient network failures, HTTP 5xx responses, and responses with no audio retain one automatic retry.

OpenClaw sends Gemini 3.8 TTS through the Interactions API (POST /v1beta/interactions) with store: false. Google also documents 3.8 on generateContent; Interactions is OpenClaw's routing choice, not a model requirement. OpenClaw asks for headerless 24 kHz PCM (audio/l16) and still wraps that PCM locally. audioProfile and personaPrompt are sent as speech_metadata.style, speakerName as the structured speaker label, and none of them are spoken as part of the transcript. Momentary 3.8 vocal tags use angle brackets, such as <laugh> or <short pause>; sustained delivery such as whispering belongs in audioProfile.

Set speakers to exactly two { speaker, voice, style? } entries to cast a dialogue. Only lines that start with one of those two names followed by a colon begin a turn (Puck: Hello and Puck:Hello both count), and the name is not spoken. Every other line is spoken as part of the current turn, including ordinary colon-prefixed prose such as Budget: 10 dollars and any unconfigured label such as Alice: Hi. Words before the first label are spoken by that first speaker, not dropped. A transcript with no configured labels stays on the single-voice path. Multi-speaker dialogue requires gemini-3.8-flash-tts or gemini-3.8-flash-lite-tts.

Puck: Headphones on. <laugh> We opened it.Kore: It is waiting at the maintainer gate.

Gemini 3.1 and 2.5 preview TTS still use generateContent. Those models keep the older behavior: audioProfile is prepended to the transcript, and expressive tags use square brackets such as [whispers]. An unknown gemini-3.8-*-tts id is rejected instead of being sent to generateContent.

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.8-flash-tts",        speakerVoice: "Kore",        audioProfile: "Speak professionally with a calm tone.",        speakers: [          { speaker: "Puck", voice: "Puck", style: "bright" },          { speaker: "Kore", voice: "Kore", style: "whispered" },        ],      },    },  },}

Gemini API TTS uses natural-language prompting for style control. Set audioProfile for a reusable delivery style. On Gemini 3.8 that style is speech_metadata.style and is not read aloud. On Gemini 3.1 and 2.5 preview models it is still prepended to the spoken text. Set speakerName when the performance needs a named speaker; 3.8 sends it as the structured speech_metadata.speaker label, never as style text, and the selected voice stays the single configured voice.

Gemini 3.1 and 2.5 preview TTS accept expressive square-bracket audio tags in the text, such as [whispers] or [laughs]. Gemini 3.8 uses angle-bracket vocal tags such as <laugh> instead. 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]]<laugh> Here is the spoken version. <short pause> Enjoy.[[/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.

Talk and Discord expose Google's prebuilt voices in their voice catalogs. During an active Talk or Discord call, use talk_voice to select a new voice. OpenClaw reconnects with that voice while preserving the conversation and unfinished agent work; saved voice defaults stay unchanged. See Discord voice changes.

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

{  models: {    mode: "merge",    providers: {      google: {        baseUrl: "https://generativelanguage.googleapis.com/v1beta",        api: "google-generative-ai",        models: [          {            id: "gemini-3.8-flash",            name: "Gemini Flash",            api: "google-generative-ai",            reasoning: true,            input: ["text", "image"],            contextWindow: 1048576,            maxTokens: 65536,          },        ],      },    },  },  agents: {    defaults: { model: { primary: "google/gemini-3.8-flash" } },  },}

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

Related