Skip to main content

​
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

1

Get your API key

Create an API key at openrouter.ai/keys.
2

Run onboarding

3

(Optional) Switch to a specific model

Onboarding defaults to openrouter/auto. Pick a concrete model later:

​
Config example

​
Model references

Model refs follow the pattern openrouter/<provider>/<model>. For the full list of available providers and models, see /concepts/model-providers.

​
Authentication and headers

OpenRouter uses a Bearer token with your API key under the hood. On real OpenRouter requests (https://openrouter.ai/api/v1), Velaclaw also adds OpenRouter’s documented app-attribution headers:
If you repoint the OpenRouter provider at some other proxy or base URL, Velaclaw does not inject those OpenRouter-specific headers or Anthropic cache markers.

​
Advanced notes

On verified OpenRouter routes, Anthropic model refs keep the OpenRouter-specific Anthropic cache_control markers that Velaclaw uses for better prompt-cache reuse on system/developer prompt blocks.
On supported non-auto routes, Velaclaw maps the selected thinking level to OpenRouter proxy reasoning payloads. Unsupported model hints and openrouter/auto skip that reasoning injection.
OpenRouter still runs through the proxy-style OpenAI-compatible path, so native OpenAI-only request shaping such as serviceTier, Responses store, OpenAI reasoning-compat payloads, and prompt-cache hints is not forwarded.
Gemini-backed OpenRouter refs stay on the proxy-Gemini path: Velaclaw keeps Gemini thought-signature sanitation there, but does not enable native Gemini replay validation or bootstrap rewrites.
If you pass OpenRouter provider routing under model params, Velaclaw forwards it as OpenRouter routing metadata before the shared stream wrappers run.

Model selection

Choosing providers, model refs, and failover behavior.

Configuration reference

Full config reference for agents, models, and providers.