Google (Gemini)

The Google plugin provides access to Gemini models through Google AI Studio, plus image generation, media understanding (image/audio/video), and web search via Gemini Grounding.

Provider: google
Auth: GEMINI_API_KEY or GOOGLE_API_KEY
API: Google Gemini API

Quick start

Set the API key:

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

Set a default model:

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

Non-interactive example

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

Capabilities

Capability	Supported
Chat completions	Yes
Image generation	Yes
Music generation	Yes
Image understanding	Yes
Audio transcription	Yes
Video understanding	Yes
Web search (Grounding)	Yes
Thinking/reasoning	Yes (Gemini 3.1+)

Direct Gemini cache reuse

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

Configure per-model or global params with either cachedContent or legacy cached_content
If both are present, cachedContent wins
Example value: cachedContents/prebuilt-context
Gemini cache-hit usage is normalized into OpenClaw cacheRead from upstream cachedContentTokenCount

Example:

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

Image generation

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

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

Image generation, media understanding, and Gemini Grounding all stay on the google provider id.

To use Google as the default image provider:

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

See Image Generation for the shared tool parameters, provider selection, and failover behavior.

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, resolution, and audio
Current duration clamp: 4 to 8 seconds

To use Google as the default video provider:

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

See Video Generation for the shared tool parameters, provider selection, and failover behavior.

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

See Music Generation for the shared tool parameters, provider selection, and failover behavior.

Environment note

If the Gateway runs as a daemon (launchd/systemd), make sure GEMINI_API_KEY is available to that process (for example, in ~/.openclaw/.env or via env.shellEnv).

4.4 KiB Raw Blame History