Use OpenRouter with OpenHands - OpenHands Docs

Use OpenRouter when you have an OpenRouter API key and want to access a model from its model catalog.

Configure Agent Canvas

Open Settings > LLM.
In the Basic tab, select OpenRouter as the provider.
Select a model, enter your OpenRouter API key, and save the profile.
Start a new conversation and send a short message to verify the model responds.

If the model is not in the selector, use the Advanced tab and enter its model ID with the openrouter/ prefix. For example, OpenRouter model ID anthropic/claude-3.5-sonnet becomes:

openrouter/anthropic/claude-3.5-sonnet

Copy the current model ID from the OpenRouter model catalog. Model availability and IDs can change, so do not rely on a previously saved identifier without checking it.

Fix Common Problems

Problem	Check	Next step
Model is not found	The exact OpenRouter model ID	Copy the ID from the model catalog and add the `openrouter/` prefix in `Advanced`.
Authentication fails	The API key	Create or copy an active OpenRouter API key, then save the profile again.
The model is unavailable	The selected model in the catalog	Choose an available model or check your OpenRouter account and model access.
The model does not complete agent tasks reliably	Model context and tool-use support	Choose a more capable model that supports the features required for your task.

For the broader configuration decision and local/proxy recovery paths, see Configure a Model. For LiteLLM’s provider behavior, see LiteLLM’s OpenRouter documentation.