16 KiB
summary, read_when, title
| summary | read_when | title | |||||
|---|---|---|---|---|---|---|---|
| Use OpenRouter's unified API to access many models in OpenClaw |
|
OpenRouter |
OpenRouter provides a unified API that routes requests to many models behind a single endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
Getting started
```bash openclaw onboard --auth-choice openrouter-oauth ``` OpenClaw opens OpenRouter's browser sign-in flow, exchanges the PKCE
code for an OpenRouter API key, and stores that key in the default
OpenRouter auth profile. On remote/headless hosts, OpenClaw prints the
sign-in URL and asks you to paste the redirect URL after signing in.
</Step>
<Step title="(Optional) Switch to a specific model">
Onboarding defaults to `openrouter/auto`. Pick a concrete model later:
```bash
openclaw models set openrouter/<provider>/<model>
```
</Step>
</Steps>
```bash
openclaw models set openrouter/<provider>/<model>
```
</Step>
</Steps>
Config example
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
model: { primary: "openrouter/auto" },
},
},
}
Model references
Model refs follow the pattern `openrouter//`. For the full list of available providers and models, see [/concepts/model-providers](/concepts/model-providers).Bundled fallback examples:
| Model ref | Notes |
|---|---|
openrouter/auto |
OpenRouter automatic routing |
openrouter/openrouter/fusion |
OpenRouter Fusion router |
openrouter/moonshotai/kimi-k2.6 |
Kimi K2.6 via MoonshotAI |
openrouter/moonshotai/kimi-k2.5 |
Kimi K2.5 via MoonshotAI |
Image generation
OpenRouter can also back the image_generate tool. Use an OpenRouter image model under agents.defaults.imageGenerationModel:
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
imageGenerationModel: {
primary: "openrouter/google/gemini-3.1-flash-image-preview",
timeoutMs: 180_000,
},
},
},
}
OpenClaw sends image requests to OpenRouter's chat completions image API with modalities: ["image", "text"]. Gemini image models receive supported aspectRatio and resolution hints through OpenRouter's image_config. Use agents.defaults.imageGenerationModel.timeoutMs for slower OpenRouter image models; the image_generate tool's per-call timeoutMs parameter still wins.
Video generation
OpenRouter can also back the video_generate tool through its asynchronous /videos API. Use an OpenRouter video model under agents.defaults.videoGenerationModel:
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
videoGenerationModel: {
primary: "openrouter/google/veo-3.1-fast",
},
},
},
}
OpenClaw submits text-to-video and image-to-video jobs to OpenRouter, polls
the returned polling_url, and downloads the completed video from
OpenRouter's unsigned_urls or the documented job content endpoint.
Reference images are sent as first/last frame images by default; images
tagged with reference_image are sent as OpenRouter input references. The
bundled google/veo-3.1-fast default advertises the currently supported 4/6/8
second durations, 720P/1080P resolutions, and 16:9/9:16 aspect
ratios. Video-to-video is not registered for OpenRouter because the upstream
video generation API currently accepts text and image references.
Music generation
OpenRouter can also back the music_generate tool through chat completions
audio output. Use an OpenRouter audio model under
agents.defaults.musicGenerationModel:
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
musicGenerationModel: {
primary: "openrouter/google/lyria-3-pro-preview",
timeoutMs: 180_000,
},
},
},
}
The bundled OpenRouter music provider defaults to
google/lyria-3-pro-preview and also exposes
google/lyria-3-clip-preview. OpenClaw sends modalities: ["text", "audio"], enables streaming, collects the streamed audio chunks, and saves
the result as generated media for channel delivery. Reference images are
accepted for Lyria models through the shared music_generate image=...
parameter.
Text-to-speech
OpenRouter can also be used as a TTS provider through its OpenAI-compatible
/audio/speech endpoint.
{
messages: {
tts: {
auto: "always",
provider: "openrouter",
providers: {
openrouter: {
model: "hexgrad/kokoro-82m",
speakerVoice: "af_alloy",
responseFormat: "mp3",
},
},
},
},
}
If messages.tts.providers.openrouter.apiKey is omitted, TTS reuses
models.providers.openrouter.apiKey, then OPENROUTER_API_KEY.
Speech-to-text (inbound audio)
OpenRouter can transcribe inbound voice/audio attachments through the shared
tools.media.audio path using its STT endpoint (/audio/transcriptions).
This applies to any channel plugin that forwards inbound voice/audio into
media understanding preflight.
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],
},
},
},
}
OpenClaw sends OpenRouter STT requests as JSON with base64 audio under
input_audio (OpenRouter STT contract), not as multipart OpenAI form uploads.
Fusion router
Use OpenRouter Fusion when you want one OpenClaw model ref to ask several
OpenRouter models in parallel, have OpenRouter judge their answers, and return a
single final response through the normal OpenRouter provider endpoint. Because
the upstream model slug is openrouter/fusion, the OpenClaw model ref includes
both the OpenClaw provider prefix and the upstream OpenRouter namespace:
openclaw models set openrouter/openrouter/fusion
Configure Fusion's panel and judge through the model's params.extraBody. Those
fields are forwarded into the OpenRouter chat-completions request body. Fusion
works with either OpenRouter OAuth onboarding or API-key onboarding; if you use
OAuth, omit the env.OPENROUTER_API_KEY line from the example below.
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
model: { primary: "openrouter/openrouter/fusion" },
models: {
"openrouter/openrouter/fusion": {
params: {
extraBody: {
plugins: [
{
id: "fusion",
analysis_models: [
"google/gemini-3.5-flash",
"moonshotai/kimi-k2.6",
"deepseek/deepseek-v4-pro",
],
model: "google/gemini-3.5-flash",
},
],
},
},
},
},
},
},
}
The analysis_models list is the parallel panel, and model inside the Fusion
plugin config is the judge model. Do not set top-level tool_choice to
"required" in normal OpenClaw agent/chat turns to try to force Fusion;
OpenClaw turns may include OpenClaw tool definitions, and a top-level required
tool choice can require one of those tools instead of the Fusion router. When
this Fusion plugin config is present, OpenClaw also adds a sanitized
system-prompt note with the configured analysis models and judge model so the
agent can answer questions about its current Fusion panel. Other extraBody
fields are not copied into the prompt.
Fusion is slower by design. OpenRouter may send the same OpenClaw prompt to multiple analysis models and then run a final judge/synthesis step, so latency is usually higher than a direct single-model request. Use Fusion for deliberate, high-quality answers or escalation paths, not as the default for latency-sensitive chat. For faster responses, keep the panel small and choose faster analysis and judge models.
Test the configured ref with a one-shot local model call:
openclaw infer model run --local \
--model openrouter/openrouter/fusion \
--prompt "Reply with exactly: FUSION_OK" \
--json
Authentication and headers
OpenRouter uses a Bearer token with your API key under the hood. OpenRouter
OAuth is a PKCE login flow that issues an OpenRouter API key, so OpenClaw stores
the result as the same openrouter:default API-key auth profile used by the
manual API-key setup path.
For an existing install, sign in or rotate the stored OpenRouter key without rerunning full onboarding:
openclaw models auth login --provider openrouter --method oauth
Use openclaw models auth login --provider openrouter --method api-key when
you want to paste a key you created manually at OpenRouter.
On real OpenRouter requests (https://openrouter.ai/api/v1), OpenClaw also adds
OpenRouter's documented app-attribution headers:
| Header | Value |
|---|---|
HTTP-Referer |
https://openclaw.ai |
X-OpenRouter-Title |
OpenClaw |
X-OpenRouter-Categories |
cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent |
Advanced configuration
OpenRouter response caching is opt-in. Enable it per OpenRouter model with model params:```json5
{
agents: {
defaults: {
models: {
"openrouter/auto": {
params: {
responseCache: true,
responseCacheTtlSeconds: 300,
},
},
},
},
},
}
```
OpenClaw sends `X-OpenRouter-Cache: true` and, when configured,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` forces a refresh for
the current request and stores the replacement response. Snake_case aliases
(`response_cache`, `response_cache_ttl_seconds`, and
`response_cache_clear`) are also accepted.
This is separate from provider prompt caching and from OpenRouter's
Anthropic `cache_control` markers. It is only applied on verified
`openrouter.ai` routes, not custom proxy base URLs.
```json5
{
models: {
providers: {
openrouter: {
params: {
provider: {
sort: "latency",
require_parameters: true,
data_collection: "deny",
},
},
},
},
},
}
```
OpenClaw forwards that object to OpenRouter as the request `provider`
payload. Use OpenRouter's documented snake_case fields, including `sort`,
`only`, `ignore`, `order`, `allow_fallbacks`, `require_parameters`,
`data_collection`, `quantizations`, `max_price`, `preferred_max_latency`,
`preferred_min_throughput`, `zdr`, and `enforce_distillable_text`.
Per-model params still override the provider-wide routing object:
```json5
{
agents: {
defaults: {
models: {
"openrouter/anthropic/claude-sonnet-4-6": {
params: {
provider: {
order: ["anthropic"],
allow_fallbacks: false,
},
},
},
},
},
},
}
```
This only applies on OpenRouter chat-completions routes. Direct Anthropic,
Google, OpenAI, or custom provider routes ignore OpenRouter routing params.