OpenClaw Gemini API Key: The Exact Setup Steps That Work

Gemini Flash costs a fraction of Claude or GPT-4o per token — and for high-volume agent tasks that don't require deep reasoning, the quality difference is negligible. Three teams we work with run their classification, summarization, and routing agents entirely on Gemini and reserve Claude for complex tasks. The setup takes 8 minutes. Here is exactly how to do it without hitting the three mistakes that waste an hour.

Getting Your Key from Google AI Studio

Go to aistudio.google.com. Sign in with your Google account. Click "Get API key" in the left sidebar. Create a new API key and select the project you want to associate it with — or create a new project if this is a fresh setup.

Copy the key immediately. Store it somewhere safe — Google AI Studio shows the full key on creation, but subsequent views show only the last few characters. If you lose it, you generate a new one.

Setting the Environment Variable

The variable name is non-negotiable: GEMINI_API_KEY. OpenClaw's gemini provider block reads this exact string. Using GOOGLE_API_KEY, GOOGLE_AI_KEY, or GEMINI_KEY all produce authentication failures with unhelpful error messages.

# Linux / macOS — add to ~/.bashrc or ~/.zshrc for persistence
export GEMINI_API_KEY="AIza-your-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY="AIza-your-key-here"

# .env file (recommended for project-level config)
GEMINI_API_KEY=AIza-your-key-here

Gemini API keys start with AIza. If your key doesn't start with this prefix, you're either using the wrong key type or copied it incorrectly from Google AI Studio.

The openclaw.yaml Configuration

providers:
  gemini:
    api_key: "${GEMINI_API_KEY}"
    default_model: gemini-2.0-flash
    models:
      - id: gemini-2.0-flash
        context_window: 1048576
        supports_vision: true
        cost_tier: economy
      - id: gemini-2.0-pro-exp
        context_window: 2097152
        supports_vision: true
        cost_tier: premium

agents:
  content-classifier:
    provider: gemini
    model: gemini-2.0-flash
    description: "Classifies and routes incoming content"

  deep-analyzer:
    provider: gemini
    model: gemini-2.0-pro-exp
    description: "Complex analysis requiring larger context"

The context window on gemini-2.0-flash is 1M tokens — that's larger than most other providers and genuinely useful for agents processing long documents. Gemini-2.0-pro-exp supports 2M tokens, which is the largest context window available through OpenClaw as of early 2025.

Free Tier Limits and When to Upgrade

Gemini's free tier enforces 15 requests per minute and 1 million tokens per day. Those numbers look generous for a single agent, but they collapse quickly when you run concurrent tasks. Three agents firing simultaneously means each gets 5 requests per minute — roughly one request every 12 seconds. That's too slow for real-time workflows.

Upgrading to pay-as-you-go unlocks 360 RPM. The cost for gemini-2.0-flash is low enough that production workloads are significantly cheaper than Claude or GPT-4o for equivalent task volumes.

Model Name Strings — Get These Exact

OpenClaw's gemini provider matches model strings exactly. These are the two models you'll use and their correct strings:

• gemini-2.0-flash — fast, low cost, 1M context. Default for most agent tasks.
• gemini-2.0-pro-exp — higher quality, 2M context, experimental. For complex reasoning.

Old strings like "gemini-pro" and "gemini-pro-vision" reference deprecated models. They return a 404 from Google's API. Always use the versioned strings listed above.

Testing the Connection

# Test the Gemini provider configuration
openclaw doctor --provider gemini

# Test a specific model
openclaw test-model gemini-2.0-flash --provider gemini --prompt "Hello"

# Check rate limit status
openclaw quota --provider gemini

The doctor command verifies your API key is valid, the model strings resolve, and the provider block is correctly configured. Run it before deploying any agent that uses Gemini — a passing doctor check prevents the most common failure modes.

The 3 Mistakes That Break Gemini Setup

Mistake 1: Using the wrong environment variable name. This is the most common failure. GOOGLE_API_KEY, GOOGLE_AI_KEY, and GEMINI_KEY all fail silently — OpenClaw doesn't find the key and sends unauthenticated requests. The result is a generic 401 error that doesn't tell you the variable name is wrong. Use exactly GEMINI_API_KEY.

Mistake 2: Setting the variable after starting OpenClaw. OpenClaw reads environment variables once at process startup. If you export GEMINI_API_KEY in the same terminal session after OpenClaw is already running, the process doesn't pick up the change. Restart OpenClaw after setting any new environment variable.

Sound familiar? This one wastes the most time because the fix isn't obvious from the error message.

Mistake 3: Using an incorrect model string. "gemini-pro" was the correct string for the first-generation Gemini model but it's deprecated. "gemini-flash" without the version number returns a 404. Always use the full versioned string: gemini-2.0-flash or gemini-2.0-pro-exp.

Frequently Asked Questions

Where do I get a Gemini API key for OpenClaw?

Get your Gemini API key from Google AI Studio at aistudio.google.com — not Google Cloud Console. Click Get API Key, create a new key for your project, and copy it immediately. Set it as GEMINI_API_KEY in your environment before editing openclaw.yaml.

What is the correct environment variable name for Gemini in OpenClaw?

The correct variable name is GEMINI_API_KEY. OpenClaw's gemini provider block reads this specific variable at startup. GOOGLE_API_KEY and GOOGLE_AI_KEY are not recognized by OpenClaw's provider registry and result in authentication failures on every request.

What are Gemini's free tier rate limits with OpenClaw?

Gemini's free tier allows 15 requests per minute and 1 million tokens per day on gemini-2.0-flash. For agent workloads with multiple concurrent tasks, you'll hit the 15 RPM limit quickly. Upgrade to pay-as-you-go (360 RPM) or implement request queuing if your agents run more than a few tasks simultaneously.

Which Gemini model string should I use in openclaw.yaml?

Use gemini-2.0-flash for speed and cost efficiency — it's the best default for most agent tasks. Use gemini-2.0-pro-exp for complex reasoning tasks requiring a larger model. Both strings are exact — OpenClaw's provider registry matches on the full string including version number.

How do I test my Gemini connection in OpenClaw?

Run openclaw doctor --provider gemini after configuration. A successful check shows your model list and confirms the API key is valid. If you get 'API key not valid', the GEMINI_API_KEY variable is either not set, set incorrectly, or OpenClaw was started before the variable was exported to the environment.

What are the 3 most common Gemini setup mistakes in OpenClaw?

The three most common mistakes are: using GOOGLE_API_KEY instead of GEMINI_API_KEY, setting the variable after starting OpenClaw (it reads env vars at startup only), and using an incorrect model string like 'gemini-pro' instead of 'gemini-2.0-flash'. All three produce error messages that don't point to the actual cause.