# OpenClaw 🦞

> Learn how to configure OpenClaw to use OpenRouter for AI agents across multiple messaging platforms.

## What is OpenClaw?

[OpenClaw](https://github.com/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:

```bash
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:

```bash
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

<Warning>
  **Advanced users only:** The following manual configuration is for users who need to edit their config file directly. For most users, we recommend using the setup wizard above.
</Warning>

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](https://openrouter.ai)
2. Navigate to your [API Keys page](https://openrouter.ai/keys)
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`:

```json
{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5"
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.5": {}
      }
    }
  }
}
```

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

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

<Note>
  That's it! OpenClaw has built-in support for OpenRouter. You don't need to configure `models.providers` - just set your API key and reference models with the `openrouter/<author>/<slug>` format.
</Note>

### Step 3: Choose Your Model

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

**Anthropic Claude:**

```json
"model": {
  "primary": "openrouter/anthropic/claude-sonnet-4.5"
},
"models": {
  "openrouter/anthropic/claude-sonnet-4.5": {}
}
```

**Google Gemini:**

```json
"model": {
  "primary": "openrouter/google/gemini-pro-1.5"
},
"models": {
  "openrouter/google/gemini-pro-1.5": {}
}
```

**DeepSeek:**

```json
"model": {
  "primary": "openrouter/deepseek/deepseek-chat"
},
"models": {
  "openrouter/deepseek/deepseek-chat": {}
}
```

**Moonshot Kimi:**

```json
"model": {
  "primary": "openrouter/moonshotai/kimi-k2.5"
},
"models": {
  "openrouter/moonshotai/kimi-k2.5": {}
}
```

Browse all available models at [openrouter.ai/models](https://openrouter.ai/models).

### Step 4: Start OpenClaw

After updating your configuration, start or restart OpenClaw:

```bash
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. For example:

* `openrouter/anthropic/claude-sonnet-4.5`
* `openrouter/google/gemini-pro-1.5`
* `openrouter/moonshotai/kimi-k2.5`
* `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](https://openrouter.ai/models).

## Multiple Models with Fallbacks

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

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5",
        "fallbacks": [
          "openrouter/anthropic/claude-haiku-3.5"
        ]
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.5": {},
        "openrouter/anthropic/claude-haiku-3.5": {}
      }
    }
  }
}
```

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:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/auto"
      },
      "models": {
        "openrouter/openrouter/auto": {}
      }
    }
  }
}
```

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

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/auto",
        "fallbacks": [
          "openrouter/anthropic/claude-haiku-3.5"
        ]
      },
      "models": {
        "openrouter/openrouter/auto": {},
        "openrouter/anthropic/claude-haiku-3.5": {}
      }
    }
  }
}
```

Learn more about how Auto Model works at [openrouter.ai/models/openrouter/auto](https://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`:

```json
{
  "auth": {
    "profiles": {
      "openrouter:default": {
        "provider": "openrouter",
        "mode": "api_key"
      }
    }
  }
}
```

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

```bash
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](https://openrouter.ai/activity)
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](https://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](https://openrouter.ai/models)
2. Use the format `openrouter/<author>/<slug>` (e.g., `openrouter/anthropic/claude-sonnet-4.5`)
3. Add the model to `agents.defaults.models` in your config

## Advanced Configuration

### Per-Channel Models

Configure different models for different messaging channels:

```json
{
  "telegram": {
    "agents": {
      "defaults": {
        "model": {
          "primary": "openrouter/anthropic/claude-haiku-3.5"
        }
      }
    }
  },
  "discord": {
    "agents": {
      "defaults": {
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4.5"
        }
      }
    }
  }
}
```

## Resources

* [OpenClaw Documentation](https://docs.openclaw.ai)
* [OpenClaw OpenRouter Provider Guide](https://docs.openclaw.ai/providers/openrouter)
* [OpenClaw GitHub](https://github.com/openclaw/openclaw)
* [OpenRouter Models](https://openrouter.ai/models)
* [OpenRouter Activity Dashboard](https://openrouter.ai/activity)
* [OpenRouter API Documentation](https://openrouter.ai/docs/api)