OpenClaw 🦞

What is OpenClaw?

OpenClaw (formerly Moltbot, formerly Clawdbot) is an open-source AI agent platform that brings conversational AI to multiple messaging channels including Telegram, Discord, Slack, Signal, iMessage, and WhatsApp. It supports multiple LLM providers and allows you to run AI agents that can interact across all these platforms.

Setup

Recommended: Use the OpenClaw Setup Wizard

The easiest way to configure OpenClaw with OpenRouter is using the built-in setup wizard:

$
openclaw onboard

The wizard will guide you through:

1. Choosing OpenRouter as your provider
2. Entering your API key
3. Selecting your preferred model
4. Configuring messaging channels

This is the recommended approach for new users and ensures everything is configured correctly.

Quick Start (CLI)

If you already have your OpenRouter API key and want to skip the wizard, use this one-line command:

$
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

This automatically configures OpenClaw to use OpenRouter with the recommended model (openrouter/auto).

Manual Configuration

If you need to manually edit your OpenClaw configuration file, follow these steps:

Step 1: Get Your OpenRouter API Key

1. Sign up or log in at OpenRouter
2. Navigate to your API Keys page
3. Create a new API key
4. Copy your key (starts with sk-or-...)

Step 2: Set Your API Key

Add your OpenRouter API key to your ~/.openclaw/openclaw.json:

1
{
2
  "env": {
3
    "OPENROUTER_API_KEY": "sk-or-..."
4
  },
5
  "agents": {
6
    "defaults": {
7
      "model": {
8
        "primary": "openrouter/~anthropic/claude-sonnet-latest"
9
      },
10
      "models": {
11
        "openrouter/~anthropic/claude-sonnet-latest": {}
12
      }
13
    }
14
  }
15
}

Or set it as an environment variable in your shell profile:

$
export OPENROUTER_API_KEY="sk-or-..."

Step 3: Choose Your Model

Update the primary model and add it to the models list. Here are some popular options:

Anthropic Claude:

1
"model": {
2
  "primary": "openrouter/~anthropic/claude-sonnet-latest"
3
},
4
"models": {
5
  "openrouter/~anthropic/claude-sonnet-latest": {}
6
}

Google Gemini:

1
"model": {
2
  "primary": "openrouter/~google/gemini-pro-latest"
3
},
4
"models": {
5
  "openrouter/~google/gemini-pro-latest": {}
6
}

DeepSeek:

1
"model": {
2
  "primary": "openrouter/deepseek/deepseek-chat"
3
},
4
"models": {
5
  "openrouter/deepseek/deepseek-chat": {}
6
}

Moonshot Kimi:

1
"model": {
2
  "primary": "openrouter/~moonshotai/kimi-latest"
3
},
4
"models": {
5
  "openrouter/~moonshotai/kimi-latest": {}
6
}

Browse all available models at openrouter.ai/models.

Step 4: Start OpenClaw

After updating your configuration, start or restart OpenClaw:

$
openclaw gateway run

Your agents will now use OpenRouter to route requests to your chosen model.

Model Format

OpenClaw uses the format openrouter/<author>/<slug> for OpenRouter models (prefix the author with ~ to track the latest version in a family). For example:

• openrouter/~anthropic/claude-sonnet-latest
• openrouter/~google/gemini-pro-latest
• openrouter/~moonshotai/kimi-latest
• openrouter/openrouter/auto (Auto router that picks the most cost effective model for your prompt)

You can find the exact format for each model on the OpenRouter models page.

Multiple Models with Fallbacks

OpenClaw supports model fallbacks. If the primary model is unavailable, it will try the fallback models in order:

1
{
2
  "agents": {
3
    "defaults": {
4
      "model": {
5
        "primary": "openrouter/~anthropic/claude-sonnet-latest",
6
        "fallbacks": [
7
          "openrouter/~anthropic/claude-haiku-latest"
8
        ]
9
      },
10
      "models": {
11
        "openrouter/~anthropic/claude-sonnet-latest": {},
12
        "openrouter/~anthropic/claude-haiku-latest": {}
13
      }
14
    }
15
  }
16
}

This provides an additional layer of reliability on top of OpenRouter’s provider-level failover.

Using Auto Model for Cost Optimization

OpenClaw agents perform many different types of actions, from simple heartbeat processing to complex reasoning tasks. Using a powerful model for every action wastes money on tasks that don’t require advanced capabilities.

The OpenRouter Auto Model (openrouter/openrouter/auto) automatically selects the most cost-effective model based on your prompt. This is ideal for OpenClaw because it routes simple tasks like heartbeats and status checks to cheaper models while using more capable models only when needed for complex interactions.

To configure Auto Model as your primary model:

1
{
2
  "agents": {
3
    "defaults": {
4
      "model": {
5
        "primary": "openrouter/openrouter/auto"
6
      },
7
      "models": {
8
        "openrouter/openrouter/auto": {}
9
      }
10
    }
11
  }
12
}

You can also combine Auto Model with fallbacks for maximum reliability:

1
{
2
  "agents": {
3
    "defaults": {
4
      "model": {
5
        "primary": "openrouter/openrouter/auto",
6
        "fallbacks": [
7
          "openrouter/~anthropic/claude-haiku-latest"
8
        ]
9
      },
10
      "models": {
11
        "openrouter/openrouter/auto": {},
12
        "openrouter/~anthropic/claude-haiku-latest": {}
13
      }
14
    }
15
  }
16
}

Learn more about how Auto Model works at openrouter.ai/models/openrouter/auto.

Using Auth Profiles

For more secure credential management, you can use OpenClaw’s auth profiles instead of environment variables. This is automatically configured when you use the openclaw onboard command.

To manually create an auth profile, add this to your openclaw.json:

1
{
2
  "auth": {
3
    "profiles": {
4
      "openrouter:default": {
5
        "provider": "openrouter",
6
        "mode": "api_key"
7
      }
8
    }
9
  }
10
}

Then use the OpenClaw CLI to set the key in your system keychain:

$
openclaw auth set openrouter:default --key "$OPENROUTER_API_KEY"

This keeps your API key out of your config file and stores it securely in your system keychain.

Monitoring Usage

Track your OpenClaw usage in real-time:

1. Visit the OpenRouter Activity Dashboard
2. See requests, costs, and token usage across all your OpenClaw agents
3. Filter by model, time range, or other criteria
4. Export usage data for billing or analysis

Common Errors

”No API key found for provider ‘openrouter’”

OpenClaw can’t find your OpenRouter API key.

Fix:

1. Ensure the OPENROUTER_API_KEY environment variable is set: echo $OPENROUTER_API_KEY
2. Or verify your auth profile exists: openclaw auth list
3. Run the onboard command: openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

Authentication errors (401/403)

If you see authentication errors:

Fix:

1. Verify your API key is valid at openrouter.ai/keys
2. Check that you have sufficient credits in your account
3. Ensure your key hasn’t expired or been revoked

Model not working

If a specific model isn’t working:

Fix:

1. Verify the model ID is correct on the OpenRouter models page
2. Use the format openrouter/<author>/<slug>, optionally prefixing the author with ~ for the latest version in a family (e.g., openrouter/~anthropic/claude-sonnet-latest)
3. Add the model to agents.defaults.models in your config

Advanced Configuration

Per-Channel Models

Configure different models for different messaging channels:

1
{
2
  "telegram": {
3
    "agents": {
4
      "defaults": {
5
        "model": {
6
          "primary": "openrouter/~anthropic/claude-haiku-latest"
7
        }
8
      }
9
    }
10
  },
11
  "discord": {
12
    "agents": {
13
      "defaults": {
14
        "model": {
15
          "primary": "openrouter/~anthropic/claude-sonnet-latest"
16
        }
17
      }
18
    }
19
  }
20
}

Resources

• OpenClaw Documentation
• OpenClaw OpenRouter Provider Guide
• OpenClaw GitHub
• OpenRouter Models
• OpenRouter Activity Dashboard
• OpenRouter API Documentation