---
title: "OpenRouter Provider"
type: entity
tags: [provider, model-switching, foundational, well-established, beginner]
created: 2026-06-10
updated: 2026-06-10
sources: ["raw/docs-integrations-providers.md", "raw/docs-user-guide-features-provider-routing.md", "raw/docs-user-guide-features-credential-pools.md", "raw/docs-reference-environment-variables.md", "raw/docs-getting-started-installation.md", "raw/release-v0.9.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md"]
confidence: high
hermes_version: "v0.15.0"
---

## Overview

**OpenRouter** is the most-recommended single key for Hermes: an aggregator that fronts hundreds of models (Anthropic, Google, Meta, DeepSeek, …) behind one OpenAI-compatible API. Provider id: `openrouter`. One `OPENROUTER_API_KEY` unlocks the main model *and* — importantly — the default auxiliary model path: vision, web summarization, and MoA tools default to Gemini Flash **via OpenRouter**, so an OpenRouter key "enables these tools automatically" even when your primary provider is Nous Portal, Codex, or a custom endpoint. It is also the only provider with sub-provider routing controls ([[concepts/model-switching]] covers the broader switching machinery).

## Characteristics

- **Setup:** `OPENROUTER_API_KEY` in `~/.hermes/.env` (keys look like `sk-or-v1-...`); `OPENROUTER_BASE_URL` overrides the endpoint
- **Model id format:** `vendor/model`, e.g. `anthropic/claude-sonnet-4`, `meta-llama/llama-3.1-70b-instruct`; with an explicit provider prefix on the CLI: `openrouter/meta-llama/llama-3.1-70b-instruct`
- **Variant tags:** `:free`, `:extended`, `:fast` suffixes are preserved across `/model` switches (added in [[entities/version-v0.9.0]])
- **Provider routing** (OpenRouter only): `provider_routing` in `config.yaml` — `sort` (`price` / `throughput` / `latency`), `only`, `ignore`, `order`, `require_parameters`, `data_collection` (`allow`/`deny`) — passed via `extra_body.provider` on every call
- **Catalog:** live catalog refresh (v0.9.0); pulled from a remote manifest since [[entities/version-v0.12.0]]
- **Response caching:** explicit cache control on supporting models ([[entities/version-v0.13.0]]); 1-hour cross-session Claude prompt cache also applies on OpenRouter ([[entities/version-v0.14.0]])
- **Pareto Code router:** `min_coding_score` knob routes to the cheapest model meeting your coding-quality bar (v0.14.0)
- **Sticky routing:** session_id passed in `extra_body` for in-session provider stickiness ([[entities/version-v0.15.0]])
- **Credential pools:** multiple OpenRouter keys rotate on 429/402/401 (`hermes auth add openrouter`)

## How to Use

```bash
# Set the key (auto-saves to ~/.hermes/.env)
hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

# Pick a model interactively
hermes model

# Or per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
```

Permanent config in `~/.hermes/config.yaml`:

```yaml
model:
  provider: openrouter
  default: anthropic/claude-sonnet-4

provider_routing:
  sort: "price"            # cheapest sub-provider first
  ignore: ["Together"]     # never route to these
  require_parameters: true # only sub-providers supporting all params (tools, temperature, ...)
  data_collection: "deny"
```

Add a second key to the pool:

```bash
hermes auth add openrouter --api-key sk-or-v1-your-second-key
```

Switch mid-session: `/model openrouter:claude-sonnet-4`. Aggregator-aware resolution keeps you on OpenRouter when the requested model is reachable through it.

## Related Entities

- [[entities/provider-nous-portal]] — the other aggregator-style choice; common fallback pairing in either direction
- [[entities/provider-anthropic]], [[entities/provider-google-ai-studio]] — direct connections to models also reachable via OpenRouter (note: `provider_routing` has no effect on direct connections)
- [[entities/provider-ollama-local]] — local last-resort fallback in a typical chain
- [[entities/version-v0.9.0]] — variant tags; [[entities/version-v0.14.0]] — Pareto Code router; [[entities/version-v0.15.0]] — sticky routing
- [[concepts/model-switching]] — credential pools, fallback chains, `/model`
- [[concepts/auxiliary-models]] — OpenRouter is the default auxiliary path
- [[concepts/configuration-reference]] — `provider_routing` lives in `config.yaml`