Google Gemini Provider Setup and Configuration

The Google plugin gives you Gemini models via Google AI Studio, along with image generation, media understanding (image, audio, video), text-to-speech, and web search through 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 using Google Cloud Application Default Credentials
• Optional runtime: agentRuntime.id: "google-gemini-cli" executes an explicitly configured model via the local Gemini CLI

Getting started

A Google AI Studio API key covers most installations. Reach for google-vertex when the Gateway already operates inside a managed Google Cloud environment.

AI Studio API key

Recommended for: standard Gemini API access.

Get an API key

Get a free key from Google AI Studio.

Run onboarding

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

You can also 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-4-argon" },
    },
  },
}

Verify the model is available

openclaw models list --provider google

Tip

Both GEMINI_API_KEY and GOOGLE_API_KEY work. Whichever one you already have configured is fine.

Once an API key is configured, OpenClaw pulls Google AI Studio's text-model catalog from the Gemini models.list API. That means supported Gemini text models show up in openclaw models list --provider google without an OpenClaw release being required. When a refresh fails, the failure is reported and the last successful inventory stays in place, or the bundled models if no refresh has succeeded yet. A successful response containing no models clears the discovered set. Vertex relies on its own separate static catalog.

Vertex AI (ADC)

Recommended for: Gateway instances hosted in Google Cloud (GCE, GKE, Cloud Run), or workstations that have already authenticated via gcloud Application Default Credentials.

Authenticate with gcloud ADC

From a workstation, execute:

gcloud auth application-default login

When a Google Cloud VM has a service account attached, credentials come from the metadata server, so no file is necessary.

Set project and location

The gateway service environment needs both of these:

export GOOGLE_CLOUD_PROJECT="my-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

The project can also be supplied as GCLOUD_PROJECT. If no project is given, runs stop with Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT or pass project in options. When the location is missing, the error reads Vertex AI requires a location. Set GOOGLE_CLOUD_LOCATION or pass location in options.

Credential: automatic discovery or manual sentinel

Provided a recognized ADC file exists (generated by gcloud auth application-default login) and the project and location variables are set, OpenClaw finds google-vertex on its own, nothing has to be stored.

You only need manual storage for metadata-only credentials (say, a GCE VM with an attached service account and no ADC file on disk), or to pick the ADC path explicitly. A sentinel value, not a real key, selects the ADC path, store exactly gcp-vertex-credentials:

openclaw models auth paste-api-key --provider google-vertex
# paste exactly: gcp-vertex-credentials

Warning

Any other stored value goes into the x-goog-api-key header rather than being treated as ADC credentials. Never paste an OAuth access token from gcloud auth print-access-token: that is not an API key, and it can trigger an authentication error like 401 UNAUTHENTICATED.

List the Vertex catalog

openclaw models list --refresh --all --provider google-vertex

--all lists models beyond the ones you configured. When the local catalog has not been loaded yet, --refresh fills it in; it does not query a live Vertex model inventory, nor does it confirm that ADC can obtain a token.

Tip

Vertex keeps a separate static model catalog; new Gemini variants show up there with each OpenClaw release instead of through the live refresh that the AI Studio key path uses.

Gemini CLI runtime

Advanced use only: execute a standard google/* model through an installed Gemini CLI, while authentication stays on the supported AI Studio API-key path.

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

Configure Google AI Studio

Finish the API-key setup described in the first tab. Before the CLI runtime can be selected, OpenClaw needs a usable google API-key profile.

Install Gemini CLI

The local gemini command has to be reachable on PATH.

# Homebrew
brew install gemini-cli

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

Homebrew installs and global npm installs are both supported by OpenClaw, common Windows/npm layouts included.

Select the CLI runtime

Retain the standard Google model ref and opt that model into the CLI runtime:

{
  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: google/*

The CLI backend registered by the bundled Google plugin is google-gemini-cli. For its argv, JSONL dialect, session and compaction behavior, and the settings that every registered backend shares, see CLI backends.

Existing valid Gemini CLI OAuth profiles still execute for compatibility, but OpenClaw cannot create or repair them. Should one break, swap it for a Google AI Studio API-key profile.

google-gemini-cli/* refs stay as legacy compatibility aliases. New configs ought to use google/* model refs together with the explicit runtime selection described above.

Note

google/gemini-3-pro-preview was retired on 2026-03-09; use google/gemini-4-argon instead. Re-running Gemini API key setup (openclaw onboard --auth-choice gemini-api-key or openclaw models auth login --provider google) updates the configured primary model to google/gemini-4-argon.

Gemini 4 Argon

The default Google model is google/gemini-4-argon, which offers a 1,048,576-token context window and up to 65,536 output tokens. Its shorthand is google/gemini-4; that same model ID and shorthand also apply to google-vertex.

Text, image, audio, video, and PDF inputs are accepted by Gemini 4 Argon, along with function calling, structured outputs, and search grounding. Only implicit context caching is available: explicit cachedContents handles and the Live API are not supported. See Google's model documentation.

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

Capabilities

A generation limit was reached by responses marked MAX_TOKENS or CONTINUATION. OpenClaw keeps their partial content and reports a length-limited result. Rather than turning into an executable tool-use turn, function calls inside that partial response stay incomplete.

When a compatible proxy sends data: [DONE], the managed Gemini and Vertex transports stop reading, release the response body, and ignore any later frames. A successful result still requires a valid candidate finish reason. Quota errors on the first frame take part in API-key rotation. For Gemini's first-response retry, usage metadata, response IDs, and empty or unspecified finish states are not counted as generated output and do not disable the existing retry deadline.

Web search

Gemini Google Search grounding powers the bundled gemini web-search provider. Set up a dedicated search key under plugins.entries.google.config.webSearch, or have it reuse models.providers.google.apiKey once GEMINI_API_KEY is done:

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

Credentials are tried in this order: dedicated webSearch.apiKey first, then GEMINI_API_KEY, then models.providers.google.apiKey. webSearch.baseUrl is optional and serves operator proxies or compatible Gemini API endpoints; if you leave it out, Gemini web search falls back to models.providers.google.baseUrl. Provider-specific tool behavior is covered in Gemini search.

Tip

Rather than thinkingBudget, Gemini 3 and Gemini 4 models use thinkingLevel. OpenClaw maps these models and the gemini-*-latest alias reasoning controls to thinkingLevel, so default and low-latency runs never send disabled thinkingBudget values.

Google's dynamic thinking semantics are kept by /think adaptive instead of a fixed OpenClaw level being chosen. Gemini 3 and Gemini 4 leave out a fixed thinkingLevel so Google can pick the level; Gemini 2.5 sends Google's dynamic sentinel thinkingBudget: -1.

low, medium, and high are supported by Gemini 4 Argon. OpenClaw maps minimal and off to low, since thinking cannot be fully disabled on this model.

Thinking mode is supported by Gemma 4 models (for example gemma-4-26b-a4b-it). For Gemma 4, OpenClaw rewrites thinkingBudget to a supported Google thinkingLevel. If thinking is set to off, thinking stays disabled rather than being mapped to MINIMAL.

Gemini 2.5 Pro runs only in thinking mode and rejects an explicit thinkingBudget: 0. When an explicit maxTokens is given, OpenClaw applies its minimum thinking budget of 128 while thinking is off. If no explicit cap is given, OpenClaw keeps omitting the rejected zero budget.

Thinking is counted by Google inside its output-token limit. For Gemini API and Vertex requests that set a fixed numeric thinking budget, OpenClaw adds that budget to the caller's maxTokens, capped at the model's output limit. Flash with thinking off leaves the caller's cap unchanged. Thinking levels, adaptive/automatic thinking, and Interactions requests leave the caller's maxTokens cap unchanged. Caps that were omitted stay omitted.

Image generation

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

• google/gemini-3-pro-image is supported as well
• Generation: a maximum of 4 images per request
• Edit mode: available, accepting up to 5 input images
• Geometry options: size, aspectRatio, and resolution

Setting Google as 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 registered by the bundled google plugin as well, exposed through the shared video_generate tool.

• Video model used by default: google/veo-3.1-fast-generate-preview
• Modes available: text-to-video, image-to-video, and single-video reference flows
• aspectRatio (16:9, 9:16) and resolution (720P, 1080P) are supported; Veo does not currently produce audio output
• Allowed durations: 4, 6, or 8 seconds (any other value snaps to the closest permitted one)

Making Google your 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

Music generation is also registered by the bundled google plugin, through the shared music_generate tool.

• Music model used by default: google/lyria-3-clip-preview
• google/lyria-3-pro-preview is supported too
• Prompt controls: lyrics and instrumental
• Output: mp3 unless changed, with wav additionally on google/lyria-3-pro-preview
• Reference inputs: a maximum of 10 images
• Runs backed by a session detach via the shared task/status flow, action: "status" included

Making Google your 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

Gemini API TTS powers the bundled google speech provider. gemini-3.1-flash-tts-preview remains the default model. To opt in to Gemini 3.8, set model to gemini-3.8-flash-tts; for the faster, lower-cost variant use gemini-3.8-flash-lite-tts. Both gemini-2.5-flash-preview-tts and gemini-2.5-pro-preview-tts stay available.

• Voice used by default: Kore
• Auth options: tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY, or GOOGLE_API_KEY
• Output formats: WAV for regular TTS attachments, Opus for voice-note targets, PCM for Talk/telephony
• Voice-note output: Google PCM gets wrapped as WAV, then transcoded to 48 kHz Opus using ffmpeg

When a TTS response succeeds but is malformed or oversized, it is reported without another Google synthesis request being submitted automatically. One automatic retry is kept for transient network failures, HTTP 5xx responses, and responses carrying no audio.

Gemini 3.8 TTS is routed by OpenClaw through the Interactions API (POST /v1beta/interactions) using store: false. 3.8 is documented by Google on generateContent as well; Interactions reflects OpenClaw's routing choice rather than a model requirement. OpenClaw requests headerless 24 kHz PCM (audio/l16) and wraps that PCM locally itself. audioProfile and personaPrompt go out as speech_metadata.style, speakerName as the structured speaker label, and none of these are spoken in the transcript. Short 3.8 vocal tags are written with angle brackets, for example <laugh> or <short pause>; sustained delivery, whispering for instance, belongs in audioProfile.

Provide exactly two { speaker, voice, style? } entries in speakers to enable a dialogue. A turn starts only on lines that begin with one of those two names plus a colon (Puck: Hello and Puck:Hello are both accepted), and that name is never spoken. All remaining lines are spoken within the current turn, including plain colon-prefixed prose like Budget: 10 dollars and any label you did not configure, such as Alice: Hi. Text appearing before the first label is spoken by the first speaker rather than discarded. When no configured labels are present, the transcript takes the single-voice path. Multi-speaker dialogue needs 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 continue to rely on generateContent. Those models behave as before: audioProfile gets prepended to the transcript, and expressive tags are written in square brackets, for example [whispers]. If an gemini-3.8-*-tts id is unknown, it is rejected rather than forwarded to generateContent.

When you need spoken conversations with the lowest latency, choose the Google realtime voice provider, which is backed by the Gemini Live API, rather than batch TTS.

To make Google your 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" },
        ],
      },
    },
  },
}

Style control in Gemini API TTS works through natural-language prompting. For a delivery style you want to reuse, set audioProfile. With Gemini 3.8, that style becomes 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 if the performance calls for a named speaker; 3.8 passes it as the structured speech_metadata.speaker label, never as style text, and the voice you selected remains the single configured voice.

Expressive square-bracket audio tags, such as [whispers] or [laughs], are accepted in the text by Gemini 3.1 and 2.5 preview TTS. Gemini 3.8 instead relies on angle-bracket vocal tags, for example <laugh>. If you want tags sent to TTS but kept out of the visible chat reply, wrap them in 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]]

Note

This provider accepts a Google Cloud Console API key that is restricted to the Gemini API. It does not use the separate Cloud Text-to-Speech API path.

Realtime voice

The bundled google plugin registers a realtime voice provider that is backed by the Gemini Live API, serving backend audio bridges including Voice Call and Google Meet.

Google's prebuilt voices appear in the voice catalogs of Talk and Discord. While a Talk or Discord call is active, talk_voice lets you pick a different voice. OpenClaw reconnects using that voice and keeps both the conversation and any unfinished agent work; defaults saved for voice stay as they are. 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",
              },
            },
          },
        },
      },
    },
  },
}

Note

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

Note

Conversational text reaches Gemini 3.1 Live through realtime input, and the model uses sequential function calling. For this model, OpenClaw omits the older NON_BLOCKING, function response scheduling, and affective-dialog fields. thinkingLevel is preferred; positive thinkingBudget values you configure are mapped to the nearest supported level, whereas -1 keeps Google's default. See the Gemini Live capability comparison.

Note

Gemini 3.8 Live (gemini-3.8-live) retains the async function-calling contract and turns down any thinking config, so OpenClaw supplies none for it. Gemini 3.8 Live Extended Thinking (gemini-3.8-live-extended-thinking) mandates NON_BLOCKING tools, refuses function response scheduling, and gives up on a call once an interim response arrives, so for each agent consult OpenClaw sends a single final result, with no "working" interim. Reasoning depth is set through thinkingLevel (low, medium, or high; minimal maps to low), or through a positive thinkingBudget that gets mapped to the closest level. Spoken filler gets its own utterance boundary as long as the interaction stays in progress; OpenClaw finalizes that transcript and audio, yet keeps the response active until Google reports the interaction as idle. With this model, an explicit stop or barge-in halts generation via a short client-content turn that informs the model it was interrupted (an empty turn causes it to resume). Cancelling the current generation works reliably, but the silence that follows is best effort: the model may still resume or begin another response, so a stop should be read as "stop this reply", not as a promise of silence. Interruption on other Gemini Live models happens only through server-side voice activity detection. Consult the Gemini 3.8 Live thinking guide.

Note

Google Live browser sessions are supported by Control UI Talk through constrained one-use tokens. For Video Talk, bounded JPEG frames go straight from the browser to Google Live, capped at the provider's maximum of one frame per second. Whether that camera stream is active is reported by the describe_view function. Camera frames never pass through the Gateway. Backend-only realtime voice providers may also run over the generic Gateway relay transport, which leaves provider credentials on the Gateway.

To verify live as a maintainer, run OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. OpenAI backend/WebRTC paths are covered by the smoke as well; the Google leg mints the same constrained Live API token shape that Control UI Talk uses, opens the browser WebSocket endpoint, sends the initial setup payload along with a JPEG frame, and checks a text response plus an describe_view function roundtrip. A synthesized PCM24 speech-to-response audio roundtrip is also performed on the OpenAI path; pass --openai-audio-cycles 3 for a brief repeated lifecycle soak.

Advanced configuration

Gemini Interactions API (stateless)

As an opt-in alternative to the default google-generative-ai transport, Gemini Interactions is available. Register a provider with api: "google-interactions" and pick models by that provider ID:

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

No state is kept by this transport: OpenClaw sends store: false, keeps no server-side interaction ID, and replays whatever conversation context is needed on every request. Explicit Gemini cachedContent handles are unsupported on this route; for that feature, use google-generative-ai.

Interrupted text replies follow the usual transient-error retry and failover policy. A request fails on malformed streaming JSON rather than silently dropping content. Malformed completed tool-call arguments are still rejected.

Direct Gemini cache reuse

For direct Gemini API runs (api: "google-generative-ai"), a configured cachedContent handle is passed by OpenClaw through to supported Gemini models. Gemini 4 Argon supports implicit caching only; an explicit cache handle must not be configured for it.

• Set per-model or global params using either cachedContent or legacy cached_content
• A more specific scope (model-level over global) always takes precedence. Where both keys are set in the same scope, cached_content wins. To avoid surprises, use just one key per scope.
• Example value: cachedContents/prebuilt-context
• Gemini cache-hit usage is normalized from upstream cachedContentTokenCount into OpenClaw cacheRead

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

Gemini CLI usage notes

The optional google-gemini-cli runtime defaults to Gemini CLI stream-json output and normalizes usage from the final stats payload. Legacy --output-format json overrides continue to use the JSON parser.

• Streamed reply text is taken from assistant message events.
• With legacy JSON output, reply text is taken from the CLI JSON response field.
• Usage falls back to stats whenever the CLI leaves usage empty.
• stats.cached is normalized into OpenClaw cacheRead.
• When 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 reachable by that process (for instance, in ~/.openclaw/.env or through env.shellEnv).

Related

• Model selection, Picking providers, model refs, and failover behavior.

• Image generation, Provider selection and shared image tool parameters.

• Video generation, Provider selection and shared video tool parameters.

• Music generation, Provider selection and shared music tool parameters.

• CLI backends, Runtime details and setup for the Gemini CLI backend.

• Voice call plugin, Audio bridge that consumes the Gemini Live realtime voice provider.