How to Set Up OpenClaw with Google Gemini: Complete Configuration Guide (2026)

Why Use Gemini with OpenClaw?

Before diving into configuration, it's worth understanding why Gemini stands out as an OpenClaw backend in 2026. The reasons go beyond just pricing.

### The Cost Advantage Is Real

Gemini 3 Flash costs $0.50 per million input tokens and $3.00 per million output tokens. For context, that's roughly **4x cheaper** than Claude Sonnet on input and **5x cheaper** on output. If your OpenClaw agent handles 50 conversations a day averaging 2,000 tokens each, you're looking at approximately $0.30/month on Gemini 3 Flash versus $1.50/month on Claude Sonnet — and that's before factoring in Gemini's free tier.

Gemini 3 Pro, Google's flagship model, costs $2–4 per million input tokens and $12–18 per million output tokens (context-tiered pricing). That's still competitive with Claude Opus and GPT-5.1 while offering a 1-million-token context window.

### The Free Tier Actually Works

Unlike most "free tiers" that are useless for real work, Google's Gemini API free tier gives you:

• **Gemini 3 Flash:** 15 requests per minute, up to 1,000 requests per day
• **Gemini 3 Pro:** 5 requests per minute, up to 100 requests per day
• **Gemini 3 Flash Lite:** 30 requests per minute, up to 1,500 requests per day

Gemini 3 Flash Performance

For a personal OpenClaw agent that handles a handful of conversations throughout the day, the free tier is legitimately sufficient. You can run your AI agent for $0/month on model costs — the only expense is your server. If you're already hosting on a cheap VPS, your total cost can be under $5/month for an always-on AI assistant.

Gemini 3 Flash isn't just cheap — it's genuinely good. According to Google's benchmarks and independent testing from Artificial Analysis, Gemini 3 Flash outperforms Gemini 2.5 Pro on most benchmarks while being 3x faster. It handles:

• **Tool calling:** Excellent structured output and function calling, which matters for OpenClaw's skill system
• **Long context:** 1M token context window (same as Pro)
• **Multimodal:** Native image, audio, and video understanding
• **Code generation:** Strong performance on HumanEval and SWE-bench
• **Multilingual:** Broad language support for international users

Gemini Model Comparison for OpenClaw

For most OpenClaw use cases — email triage, calendar management, web research, smart home control — Gemini 3 Flash is more than capable. You only need Gemini 3 Pro or Claude for complex reasoning, long-form writing, or tasks requiring deep analysis.

Here's how the available Gemini models stack up for OpenClaw usage:

• Gemini 3 Flash — Input: $0.50/1M tokens — Output: $3.00/1M tokens — 1M context — 15 RPM free — Best for daily tasks, automations, quick responses
• Gemini 3 Flash Lite — Input: $0.25/1M tokens — Output: $1.50/1M tokens — 1M context — 30 RPM free — Best for high-volume, simple tasks
• Gemini 3 Pro — Input: $2.00–$4.00/1M tokens — Output: $12.00–$18.00/1M tokens — 1M context — 5 RPM free — Best for complex reasoning, analysis, long-form writing
• Gemini 3 Pro (>200K context) — Input: $4.00/1M tokens — Output: $18.00/1M tokens — 1M context — 5 RPM free — Best for processing large documents

Method 1: Direct Gemini API Key (Recommended)

**Recommendation for most users:** Start with Gemini 3 Flash as your primary model. It handles 90% of OpenClaw tasks beautifully. Use multi-model routing to fall back to Gemini 3 Pro for complex tasks if needed.

This is the simplest and most common way to use OpenClaw with Gemini. You get a free API key from Google AI Studio and configure it directly.

### Step 1: Get Your Gemini API Key

1. Go to Google AI Studio (aistudio.google.com/apikey) 2. Sign in with your Google account 3. Click "Create API Key" 4. Select or create a Google Cloud project (if prompted) 5. Copy the generated key — it starts with `AIza...`

**Tip:** Use a dedicated Google account for your OpenClaw agent. This keeps your personal account clean and avoids any risk if you hit rate limits.

### Step 2: Configure OpenClaw

You have two options: the interactive onboarding wizard or manual configuration.

**Option A: Interactive Onboarding (Easiest)**

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

{
  // Set your API key
  env: {
    GEMINI_API_KEY: "AIzaSy..."
  },

  // Configure the model
  agents: {
    defaults: {
      model: {
        primary: "google/gemini-3-flash-preview"
      }
    }
  }
}

Verify and Set Up Key Rotation

The wizard will prompt you to paste your API key and select your preferred Gemini model. It handles all the configuration file updates automatically.

**Option B: Manual Configuration**

Edit your `openclaw.json` (or use `openclaw config edit`):

### Step 3: Verify the Connection

You should see the Google models listed with a checkmark next to them. Test with a quick message:

openclaw models list

openclaw chat "What model are you running on?"

{
  env: {
    GEMINI_API_KEY: "AIzaSy...primary",
    GEMINI_API_KEY_1: "AIzaSy...backup1",
    GEMINI_API_KEY_2: "AIzaSy...backup2"
  }
}

{
  env: {
    GEMINI_API_KEYS: "AIzaSy...key1,AIzaSy...key2,AIzaSy...key3"
  }
}

API Key Rotation Priority

The agent should respond and identify itself as running on Gemini.

### Step 4: Set Up API Key Rotation (Optional but Recommended)

If you're worried about rate limits — especially on the free tier — you can configure multiple API keys for automatic rotation. OpenClaw will cycle through them when it hits a 429 (rate limit) response.

Or use the comma-separated format:

OpenClaw also accepts `GOOGLE_API_KEY` as a fallback, and you can use `OPENCLAW_LIVE_GEMINI_KEY` for a single high-priority override key.

**Key rotation priority order:**

• `OPENCLAW_LIVE_GEMINI_KEY` (highest — hot-swap without restart)
• `GEMINI_API_KEYS` (comma/semicolon list)
• `GEMINI_API_KEY` (primary)
• `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, etc. (numbered)
• `GOOGLE_API_KEY` (fallback)

Method 2: Google Vertex AI (Enterprise)

**Important:** Key rotation only triggers on rate-limit errors (429, "quota exceeded", "resource exhausted"). Other errors fail immediately without trying the next key.

For teams or enterprise users who want Google Cloud's SLA, VPC security, and compliance certifications, Vertex AI is the way to go.

### Prerequisites

• A Google Cloud project with billing enabled
• The Vertex AI API enabled
• Application Default Credentials (ADC) configured

# Set up Application Default Credentials
gcloud auth application-default login

# Or use a service account
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

{
  agents: {
    defaults: {
      model: {
        primary: "google-vertex/gemini-3-pro-preview"
      }
    }
  }
}

Method 3: Via OpenRouter (Multi-Provider)

Vertex AI pricing is identical to the direct API but without a free tier. The tradeoff is enterprise-grade SLAs, data residency controls, and integration with Google Cloud's security infrastructure.

If you want to access Gemini alongside Claude, GPT, and other models through a single API key, OpenRouter is an excellent option. This is especially useful for multi-model routing setups.

OpenRouter adds a small markup to model pricing but gives you the flexibility to switch between providers without changing API keys. It also provides unified billing and usage tracking across all models.

**When to use OpenRouter for Gemini:**

• You already use OpenRouter for other models
• You want unified billing across providers
• You need the `openrouter/auto` smart routing feature
• You're comparing models and want easy switching

{
  env: {
    OPENROUTER_API_KEY: "sk-or-..."
  },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/google/gemini-3-flash-preview"
      }
    }
  }
}

When to Use Direct API vs OpenRouter

**When to use the direct API:**

• You want the lowest possible cost
• You need the Gemini free tier
• You want API key rotation with multiple Google keys
• You need the latest Gemini model versions immediately

Method 4: Antigravity OAuth (Free, Unofficial)

Antigravity OAuth lets you use Gemini through Google's own authentication flow, similar to how Gemini CLI works. This can provide access without managing API keys, but comes with caveats.

**Caution:** Antigravity and Gemini CLI OAuth in OpenClaw are **unofficial integrations**. Some users have reported Google account restrictions after using third-party clients. Review Google's terms of service and consider using a non-critical account.

# Enable the plugin
openclaw plugins enable google-antigravity-auth

# Login via OAuth
openclaw models auth login --provider google-antigravity --set-default

Method 5: Gemini CLI OAuth (Free, Unofficial)

Similar to Antigravity but uses the Gemini CLI authentication flow:

You don't need to paste a client ID or secret — the CLI login flow stores tokens in auth profiles on the gateway host. This method can work well for personal use but carries the same unofficial-integration risks.

# Enable the plugin
openclaw plugins enable google-gemini-cli-auth

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

Multi-Model Routing: Gemini + Claude

One of OpenClaw's most powerful features is the ability to route different tasks to different models. A popular setup is using Gemini 3 Flash for everyday tasks (cheap and fast) while routing complex reasoning to Claude or Gemini 3 Pro.

This setup means your agent uses the ultra-cheap Flash model for most interactions and only switches to Pro when deep reasoning is needed. You can also mix providers:

For detailed model routing strategies and per-task model overrides, see our Best AI Model for OpenClaw comparison guide.

{
  agents: {
    defaults: {
      model: {
        primary: "google/gemini-3-flash-preview",
        // Use for complex tasks, long analysis
        thinking: "google/gemini-3-pro-preview"
      }
    }
  }
}

{
  agents: {
    defaults: {
      model: {
        primary: "google/gemini-3-flash-preview",
        thinking: "anthropic/claude-opus-4-6"
      }
    }
  }
}

Optimizing Gemini Performance in OpenClaw

### System Prompt Best Practices for Gemini

Gemini models respond well to structured, concise system prompts. If you've been using Claude-optimized prompts in your SOUL.md, you might want to adjust:

• **Be more explicit about output format.** Gemini benefits from clear formatting instructions (JSON, markdown, bullet points).
• **Use fewer nested instructions.** Gemini handles flat, sequential instructions better than deeply nested conditional logic.
• **Leverage grounding.** Gemini has native Google Search grounding — your agent can cite recent information without needing a separate web search skill.

Token Cost Optimization

Even with Gemini's low pricing, optimizing token usage matters at scale:

• **Use Gemini 3 Flash Lite** for simple acknowledgments, confirmations, and routing decisions
• **Set max token limits** to prevent runaway responses
• **Use cron jobs with Gemini Flash** for periodic background tasks — at $0.50/1M input tokens, scheduling hourly email checks costs pennies per month
• **Configure heartbeat models** to use Flash Lite — heartbeat polls are simple and don't need a frontier model

Context Window Management

Gemini's 1M token context window is massive, but loading it fully is expensive. OpenClaw's memory system handles this automatically, but you can fine-tune:

For most personal assistant use cases, 128K tokens of context is more than enough. You're paying for what you load, so there's no reason to use the full 1M window unless you're processing very large documents.

{
  agents: {
    defaults: {
      // Limit context to control costs
      contextWindow: 128000,  // Use 128K of the available 1M
    }
  }
}

Real-World Cost Comparison

Let's compare what a typical OpenClaw user would spend per month across different model configurations:

• Light (20 msgs/day, ~2K tokens each) — Gemini 3 Flash: **$0.08** — Gemini 3 Pro: $0.85 — Claude Sonnet: $0.36 — Claude Opus: $1.80
• Moderate (50 msgs/day, ~3K tokens) — Gemini 3 Flash: **$0.30** — Gemini 3 Pro: $3.20 — Claude Sonnet: $1.35 — Claude Opus: $6.75
• Heavy (100 msgs/day, ~5K tokens) — Gemini 3 Flash: **$1.00** — Gemini 3 Pro: $10.60 — Claude Sonnet: $4.50 — Claude Opus: $22.50
• Power user + automations — Gemini 3 Flash: **$3.50** — Gemini 3 Pro: $37.00 — Claude Sonnet: $15.75 — Claude Opus: $78.75

Connecting Gemini to Your Channels

*Estimates assume average 60% input / 40% output token split. Actual costs vary by conversation style.*

The bottom line: Gemini 3 Flash makes OpenClaw incredibly affordable. Even heavy users rarely exceed $3–4/month on model costs. Combined with a $5/month VPS, you can run a full AI agent for under $10/month total.

Once Gemini is configured as your model provider, it works seamlessly with all OpenClaw channels:

• **Telegram:** The most popular channel — instant messaging with your Gemini-powered agent
• **Discord:** Set up server bots or DM-based agents
• **WhatsApp:** Personal messaging with your AI via WhatsApp Web bridge

Troubleshooting Common Issues

The channel configuration is completely independent of the model provider. You configure Gemini as the brain, then connect whatever messaging channels you prefer. No additional setup needed on the Gemini side.

### "GEMINI_API_KEY is not set"

**Symptom:** OpenClaw starts but fails with an authentication error.

**Fix:** Make sure your key is in the `env` section of `openclaw.json`, not at the top level:

Then restart: `openclaw gateway restart`

### Rate Limit Errors (429)

**Symptom:** Responses fail intermittently with "resource exhausted" or "quota exceeded."

**Fixes:**

• **Switch to paid tier** — even $1 of billing removes most free-tier restrictions
• **Set up API key rotation** (see Method 1, Step 4 above)
• **Use Flash Lite** for lightweight tasks to spread load
• **Reduce heartbeat frequency** — check if your heartbeat configuration is polling too aggressively

// Wrong
{
  GEMINI_API_KEY: "AIzaSy..."
}

// Correct
{
  env: {
    GEMINI_API_KEY: "AIzaSy..."
  }
}

More Troubleshooting

### Model Not Found

**Symptom:** "Model google/gemini-3-pro not found" or similar.

**Fix:** Use the full preview model name. Currently, Gemini 3 models use the `-preview` suffix. Check available models with `openclaw models list | grep google`.

### Gemini Returns Empty or Truncated Responses

**Symptom:** The agent responds with blank messages or cuts off mid-sentence.

**Fixes:**

• **Check safety filters** — Gemini has stricter content filtering than some providers. Your SOUL.md might trigger safety blocks if it contains explicit language.
• **Increase max tokens** — Gemini may default to shorter outputs than expected.
• **Check for tool calling issues** — ensure your skills are returning valid structured data. Gemini is strict about malformed function call responses.

Performance and Context Troubleshooting

### Slow Responses Compared to Claude

**Symptom:** Gemini takes noticeably longer to respond than Claude did.

**Fixes:**

• **Use Flash instead of Pro** — Flash is 3x faster
• **Check your region** — Gemini API latency varies by server location. A VPS closer to Google's data centers (US, Europe, Asia) helps
• **Verify you're not on the free tier** — free tier has lower throughput limits

Context Window Errors with Large Files

**Symptom:** Errors when processing large documents or long conversation histories.

**Fix:** While Gemini supports 1M tokens, the free tier may have lower effective limits. If you're processing large PDFs or long email threads:

{
  agents: {
    defaults: {
      // Limit context to prevent overflows
      contextWindow: 200000
    }
  }
}

Migrating from Claude or GPT to Gemini

If you're switching your existing OpenClaw setup from another provider to Gemini, here's what to know:

### What Changes

• **Model reference format:** Change `anthropic/claude-sonnet-4-5` to `google/gemini-3-flash-preview`
• **API key variable:** Change `ANTHROPIC_API_KEY` to `GEMINI_API_KEY`
• **Response style:** Gemini tends to be more concise than Claude. If you want longer responses, adjust your SOUL.md with explicit length instructions.

What Stays the Same

When migrating from Claude or GPT to Gemini, most of your setup remains unchanged:

• All your skills work identically — they're model-agnostic
• Memory system (MEMORY.md, daily notes) works the same
• Channel configurations (Telegram, Discord, etc.) don't change
• Cron jobs, heartbeats, and automations continue working
• Your SOUL.md personality and behavior configuration carries over

Migration Checklist

Follow these steps to migrate your OpenClaw setup to Gemini:

• Get Gemini API key from Google AI Studio
• Update `openclaw.json` with new key and model
• Test with `openclaw chat` to verify responses
• Review SOUL.md — adjust if Gemini interprets personality prompts differently
• Monitor costs for 24 hours to confirm pricing expectations
• Set up API key rotation if using free tier
• (Optional) Configure multi-model routing to keep Claude for specific tasks

Advanced: Gemini-Specific Features in OpenClaw

### Google Search Grounding

Gemini models have native integration with Google Search, which means your OpenClaw agent can ground its responses in real-time web data without needing a separate search skill. This is particularly useful for current events and news summaries, price lookups and product research, fact-checking and verification, and weather and travel information.

### Native Multimodal Input

Gemini 3 processes images, audio, and video natively. When users send photos to your OpenClaw agent via Telegram or WhatsApp, Gemini handles them without needing a separate vision model configuration.

### Structured Output and JSON Mode

Gemini 3 excels at structured output — returning valid JSON, following schemas, and handling complex tool-calling patterns. This makes it particularly effective for OpenClaw's skill system, where the agent needs to call tools with precisely formatted parameters.

Conclusion

Setting up OpenClaw with Gemini is one of the best ways to run a capable AI agent without breaking the bank. Gemini 3 Flash delivers genuinely impressive performance at $0.50 per million input tokens — or completely free if you stay within the generous rate limits. The direct API key setup takes under five minutes, and OpenClaw's built-in key rotation handles rate limit resilience automatically. For most users, the winning configuration is Gemini 3 Flash as your primary model with optional Gemini 3 Pro or Claude as a thinking/reasoning fallback. This gives you the best of all worlds: fast, cheap everyday interactions and powerful reasoning when you need it. If you haven't deployed OpenClaw yet, start with our beginner's setup guide. Already running? Just update your `openclaw.json` with a Gemini API key and you're good to go — your existing skills, memory, and channel configurations work identically.

Frequently asked questions