How to Use Gemini With OpenClaw

Ways to connect Gemini to OpenClaw

Set up Gemini with an AI Studio API key

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"

openclaw models auth login --provider google

openclaw models list --provider google
openclaw models set google/gemini-3.1-pro-preview
openclaw models status --probe

Use Gemini through Vertex AI

If your gateway already runs on Google Cloud, use the google-vertex provider. It signs in with Google Cloud Application Default Credentials instead of an AI Studio key.

gcloud auth application-default login   # skip on a VM with a service account
openclaw models list --provider google-vertex

Vertex has its own fixed model list, separate from AI Studio's live list, so pick a model from the command above. See OpenClaw's provider docs for Vertex details.

Run Gemini through the Gemini CLI

This option runs Gemini turns through Google's own gemini program, but still signs in with your AI Studio key. Do the API-key setup above first.

# Homebrew
brew install gemini-cli

# or npm
npm 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" },
        },
      },
    },
  },
}

Choose a Gemini model

These model names appear in the OpenClaw docs. Your list may include newer ones, so always check openclaw models list --provider google.

Gemini feature builder

Your API key stays in ~/.openclaw/.env as GEMINI_API_KEY. It isn't part of this config.

Images, video, music and voice

Example: two-voice speech with Gemini 3.8 TTS.

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        model: "gemini-3.8-flash-tts",
        speakerVoice: "Kore",
        speakers: [
          { speaker: "Puck", voice: "Puck", style: "bright" },
          { speaker: "Kore", voice: "Kore", style: "whispered" },
        ],
      },
    },
  },
}

Voice notes are converted to Opus with ffmpeg, so install it on the gateway machine. Want the assistant in a call? See the Discord guide.

Web search with Google Search grounding

OpenClaw's gemini web-search provider answers with live Google Search results and citations. It reuses your GEMINI_API_KEY, or you can set a separate key:

openclaw configure --section web

{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza...",        // optional
            model: "gemini-3.6-flash", // default
          },
        },
      },
    },
  },
}

Key order: the dedicated webSearch.apiKey first, then GEMINI_API_KEY, then models.providers.google.apiKey.

Thinking with Gemini

/think adaptive   # let Google decide how much to think
/think high       # think harder
/think off        # Gemma 4: keeps thinking disabled

• Gemini 3 and 3.1 use Google's thinkingLevel. OpenClaw converts its own thinking settings for you.
• /think adaptive keeps Google's dynamic thinking. Gemini 2.5 gets Google's "dynamic" setting.
• Gemini 2.5 Pro only works with thinking on. OpenClaw removes any "thinking off" value before sending.

Key rotation and context caching

Hitting rate limits? Give OpenClaw several Gemini keys. It tries the next one when a key is rate limited.

1. OPENCLAW_LIVE_GEMINI_KEYA single override
2. GEMINI_API_KEYSSeveral keys, separated by commas
3. GEMINI_API_KEYThe standard key
4. GEMINI_API_KEY_1, GEMINI_API_KEY_2…Numbered keys, with GOOGLE_API_KEY as a final fallback

Reusing a large prompt? Point OpenClaw at a Gemini context cache you created:

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

The optional stateless Interactions route (api: "google-interactions") doesn't support cachedContent. More on backups: model setup and fallbacks.

Fix common Gemini problems

More fixes: troubleshooting guide.

Gemini and OpenClaw questions