How to Set Up OpenRouter Free Models with OpenClaw

Mar 18, 2026

I was in the middle of an important OpenClaw session when it happened again:

Error: Rate limit exceeded for Gemini 2.5 Flash
Please wait before retrying...

My workflow completely derailed. The agent stopped mid-task, and I was stuck waiting for the rate limit to reset. This was the third time today. I needed a solution that wouldn’t require paying for API access or switching to a completely different setup.

After some searching on Reddit and testing different approaches, I found that OpenRouter aggregates multiple free AI models and provides access through a single API endpoint. More importantly, their rate limits are often better than direct API access.

The Problem: Direct API Rate Limits

When using OpenClaw with direct API access (like Gemini through GSuite), you’re subject to that provider’s specific rate limits. These limits can be surprisingly strict:

Gemini 2.5 Flash: Frequently rate-limited during extended agent sessions
Retry waiting periods: 10-60 seconds per error
Cumulative downtime: Hours lost per day on productive days

The issue compounds when you’re running complex multi-step agent tasks that require many API calls in sequence.

Discovery: OpenRouter as a Solution

OpenRouter works differently. Instead of accessing a single provider’s API, you access OpenRouter’s API, which routes your requests to various model providers. For free models, this means:

Aggregated free models: One endpoint (openrouter/free) routes to all available free models
Better rate limits: OpenRouter has higher aggregate limits than individual providers
Automatic fallback: If one model is rate-limited, requests route to another

I was skeptical at first. Would free models actually work for agent tasks? Would the quality be acceptable? Let me walk you through what I discovered.

Step 1: Create OpenRouter Account

First, I needed an OpenRouter account:

Visit OpenRouter
Sign up (I used GitHub SSO for convenience)
Navigate to Keys section in settings
Generate a new API key

Important decision point: I initially planned to stay completely free, but after reading Reddit discussions, I decided to add $10 credit. Here’s why:

$10 deposit raises your rate limits significantly and gives access to better models like healer-alpha and hunter-alpha that are optimized for agent tasks.

This is a one-time deposit, not a subscription. Your balance doesn’t expire, and you only use it if you choose paid models.

Step 2: Understand OpenRouter Model Selection

This is where I made my first mistake. OpenRouter has several “special” endpoints, and choosing the wrong one can cost you money.

The Models I Tested

Model Endpoint	My Experience	Best For
`openrouter/free`	Routes to all free models automatically. Worked well for general tasks.	General use, automatic routing
`openrouter/healer-alpha`	Specialized for code fixes. Good for debugging sessions.	Code corrections, fixes
`openrouter/hunter-alpha`	Designed for agent tasks. This became my go-to for OpenClaw.	OpenClaw tasks, coding agents
`openrouter/kimi-2.5`	Solid performance on agent tasks, better reasoning.	Complex OpenClaw operations

The Mistake: `openrouter/auto`

I initially tried openrouter/auto, thinking it would intelligently select the best model. It does—but it also uses paid models by default. Within minutes, I had charges on my account.

# AVOID THIS - it charges your balance
model: openrouter/auto

Lesson learned: Stick to the specific free model endpoints or use openrouter/free for automatic routing among free options only.

Step 3: Configure OpenClaw

Now for the actual setup. I needed to configure OpenClaw to use OpenRouter instead of direct API access.

Configuration File Setup

I created a configuration file for OpenClaw:

# OpenRouter Configuration for OpenClaw
api:
  provider: openrouter
  base_url: https://openrouter.ai/api/v1
  api_key: ${OPENROUTER_API_KEY}

model:
  primary: openrouter/free
  fallback:
    - openrouter/kimi-2.5
    - openrouter/hunter-alpha

The key here is the fallback list. If openrouter/free is rate-limited or having issues, OpenClaw automatically tries the next model in the list.

Environment Variable Setup

I set up my environment variables to keep the API key secure:

OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENROUTER_DEFAULT_MODEL=openrouter/free

Then I added this to my shell profile:

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
export OPENROUTER_DEFAULT_MODEL="openrouter/free"

Step 4: Test and Troubleshoot

After setup, I ran several test sessions to see which configurations worked best.

What Worked

For simple tasks (file operations, basic coding):

openrouter/free handled these well
No rate limit issues across multiple hours of use

For complex agent tasks (multi-file refactoring, debugging):

openrouter/hunter-alpha performed best
openrouter/kimi-2.5 was also reliable
Occasionally needed to switch models mid-session

What Didn’t Work

Model refusals: Some free models occasionally refused to modify the environment or execute commands:

Model refused: Cannot modify environment files for safety reasons

Solution: Switch to hunter-alpha or kimi-2.5 for tasks requiring environment modifications.

Rate limiting on Gemini: Even through OpenRouter, Gemini models can still hit rate limits during intensive sessions. The difference is OpenRouter routes to other models automatically.

Step 5: Optimize for Different Use Cases

After weeks of testing, I developed a pattern for different task types:

For Coding and Development

model:
  primary: openrouter/hunter-alpha
  fallback:
    - openrouter/kimi-2.5
    - openrouter/free

For General Tasks

model:
  primary: openrouter/free
  fallback:
    - openrouter/healer-alpha

For Debugging Sessions

model:
  primary: openrouter/healer-alpha
  fallback:
    - openrouter/hunter-alpha

Key Insights from Reddit Discussions

During my research, I found several Reddit threads with valuable insights:

On Rate Limits:

“OpenRouter sometimes has better rate limits for Gemini 2.5 Flash than direct GSuite access. They have special agreements with providers.” - Reddit user

On Model Performance:

“Kimi 2.5 via OpenRouter works well for agent tasks. Better reasoning than many other free options.” - Reddit user

On the $10 Deposit:

“It’s worth adding $10 just for the raised limits. You don’t have to use paid models—the limits apply to free models too.” - Reddit user

Performance Comparison

After using this setup for several weeks, here’s my comparison:

Metric	Direct Gemini API	OpenRouter Free	OpenRouter + $10
Rate limit errors/day	5-10	1-2	0-1
Avg wait time per error	30-60s	10-20s	5-10s
Model quality	High	Variable	High
Setup complexity	Low	Medium	Medium

The improvement in rate limit errors alone made the switch worthwhile for me.

Common Issues and Solutions

Issue 1: Model Refuses Commands

Symptoms: Model declines to modify files or execute commands Solution: Switch to hunter-alpha or kimi-2.5 which are optimized for agent tasks

Issue 2: Still Getting Rate Limited

Symptoms: Rate limit errors even with OpenRouter Solution:

Add $10 credit to raise limits
Configure multiple fallback models
Rotate between free model endpoints

Issue 3: Unexpected Charges

Symptoms: Balance decreasing unexpectedly Solution: Check you’re not using openrouter/auto, which switches to paid models automatically

Issue 4: Quality Issues with Free Models

Symptoms: Poor code generation, misunderstands instructions Solution: Use hunter-alpha for coding tasks, healer-alpha for debugging

Final Thoughts

Switching to OpenRouter for OpenClaw significantly improved my workflow. The rate limit issues that plagued my Gemini usage are now rare occurrences. The $10 deposit was worth it for the improved limits alone.

The key takeaways from my experience:

Use openrouter/free for all free models aggregated in one endpoint
Add $10 credit to raise limits—it’s one-time, not a subscription
hunter-alpha and kimi-2.5 work best for OpenClaw agent tasks
Avoid openrouter/auto to prevent unexpected charges

If you’re hitting rate limits with direct API access, OpenRouter provides a practical alternative without requiring a paid subscription. The quality varies by model, but with proper configuration, you can maintain productive agent sessions without constant interruptions.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!