Using Google Gemini with OpenClaw

Prerequisites

• ✓An existing OpenClaw installation with the CLI available so you can run `openclaw onboard` and `openclaw models auth` commands.
• ✓A Google Gemini API key from Google AI Studio so you can set `GEMINI_API_KEY` or `GOOGLE_API_KEY` for the `google` provider.
• ✓Access to install local tools if you want OAuth: ability to install the `gemini` CLI via Homebrew (`brew install gemini-cli`) or npm (`npm install -g @google/gemini-cli`).
• ✓Permission to edit your OpenClaw agent config (for example the file where you set `agents.defaults.model`, `imageGenerationModel`, `videoGenerationModel`, and `musicGenerationModel`).

Steps

1. 1

   Set your Gemini API key with the OpenClaw onboarding flow

   Start by registering your Gemini API key with OpenClaw so the `google` provider can talk to the Google Gemini API. This command walks you through an auth choice dedicated to Gemini and stores the key where the gateway can read it.

   Run it in the same environment where your OpenClaw gateway or dev tools execute.

   bashCopy

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

2. 2

   Configure a default Gemini chat model for your agents

   Next, set a default model so your agents automatically use Gemini for chat completions and reasoning. 1-pro-preview` model, which supports thinking/reasoning.

   Add this block to your OpenClaw config file in the appropriate format for your setup.

   jsonCopy

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

3. 3

   Automate setup with a non-interactive onboarding command

   If you script environments or CI, use the non-interactive onboarding variant to inject the Gemini API key without prompts. This command configures OpenClaw in local mode, selects the Gemini auth choice, and passes the key from the `GEMINI_API_KEY` environment variable.

   It’s useful when you want reproducible setups or container builds.

   bashCopy

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

4. 4

   Enable direct Gemini cache reuse for faster repeated calls

   To reuse Gemini cached content across calls, configure `cachedContent` for the specific Google model you use. OpenClaw passes this handle through to the Google Generative AI API and normalizes cache hits into its own usage metrics.

   This is handy when you have a large prebuilt context you want to share across runs.

   jsonCopy

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

5. 5

   Set Google as the default image generation provider

   If you want OpenClaw’s image-generation tool to hit Gemini by default, configure the `imageGenerationModel` to the bundled Google image model. 1-flash-image-preview`, which supports up to 4 generated images and edit mode with multiple input images.

   Add this to the same config file where you defined your default chat model.

   jsonCopy

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

6. 6

   Configure Google as the default video generation backend

   To route video generation through Gemini’s Veo models, set the default `videoGenerationModel` to the Google plugin’s video model. This enables text-to-video, image-to-video, and reference-video flows with duration clamped between 4 and 8 seconds.

   Use this when your agents call the shared `video_generate` tool.

   jsonCopy

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

7. 7

   Wire up Google as the default music generation provider

   For music generation, point the shared `music_generate` tool at Google’s Lyria models. This config uses `google/lyria-3-clip-preview` as the default, which supports lyrics and instrumental controls and image references.

   It’s a good baseline if you want your agents to create short music clips via Gemini.

   jsonCopy

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

8. 8

   Install the Gemini CLI for OAuth-based google-gemini-cli provider

   If you prefer OAuth instead of API keys, install the `gemini` CLI so OpenClaw can use the `google-gemini-cli` provider. The docs support both Homebrew and global npm installs, and OpenClaw works with common Windows/npm layouts.

   Pick one of these commands based on your environment.

   bashCopy

   brew install gemini-cli
   npm install -g @google/gemini-cli

9. 9

   Log in with the google-gemini-cli OAuth provider and set it as default

   Once the `gemini` CLI is installed, run the OpenClaw models auth command to start the PKCE OAuth flow. This logs you into Gemini via the CLI and marks `google-gemini-cli` as the default provider for model calls.

   Use this when you want to avoid managing raw API keys and are comfortable with the unofficial integration.

   bashCopy

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

Configuration

Troubleshooting

brew install gemini-cli
npm install -g @google/gemini-cli

Frequently asked questions