Guide
Model Fallbacks: Dashboard vs Config File
The model picker on your dashboard and the fallback chain in your config file are two separate settings, which is why they can look out of sync. The picker sets the primary model and nothing else. The fallback chain — the list your agent walks when the primary fails — lives in the config file, and changing the model can clear it. This page covers both Hermes Agent and OpenClaw.
The short version
The dashboard picker writes one value: the primary model. There is no fallback control in it. Set the chain in the config file, and re-check it after any model change or provider-key change — on OpenClaw a dashboard model change always clears it, and on Hermes it clears whenever the switch moves the bot onto a different provider route.
What each setting actually controls
| Dashboard model picker | Fallback chain | |
|---|---|---|
| Sets | Primary model only | Ordered list of backups |
| Lives in | Your account, pushed to the bot | The bot's config file |
| Hermes key | model.default | fallback_providers |
| OpenClaw key | agents.defaults.model.primary | agents.defaults.model.fallbacks |
| Triggers on | Every model change | Primary failure only |
A fallback is not a router. It is tried only when the primary call actually fails — a rate limit, a provider outage, an auth or credit error. A healthy primary means the rest of the chain is never touched, so a fallback list is not a way to spread traffic across models.
Hermes Agent: fallback_providers
Hermes takes a top-level fallback_providers list, where each entry names the provider in its own key and the model bare. It is not the same shape as OpenClaw's, so do not copy one into the other:
# /opt/data/config.yaml (managed) or ~/.hermes/config.yaml (self-hosted)
model:
default: claude-sonnet-4.6
provider: anthropic
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4.6
- provider: openrouter
model: minimax/minimax-m2.7From a terminal, hermes fallback list and hermes fallback add read and edit the same list. Hermes reads its config at boot, so a hand edit needs hermes gateway restart before it takes effect.
OpenClaw: agents.defaults.model.fallbacks
OpenClaw takes a flat array of provider/model strings under the default model:
// ~/.openclaw/openclaw.json (self-hosted) or /app/openclaw.json (managed)
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4.6",
"fallbacks": [
"openrouter/anthropic/claude-sonnet-4.6",
"openrouter/minimax/minimax-m2.7"
]
}
}
}
}OpenClaw hot-reloads model config, so an edit here applies without a restart.
Editing the config without a terminal
You do not need SSH or the gateway terminal for either framework. On the instance card in your dashboard, open Files and pick the config file — config.yaml on Hermes, openclaw.json on OpenClaw. The chain is at the top level on Hermes and under the default model on OpenClaw. Saving writes it straight to the bot.
When the chain gets cleared
This is the part that surprises people, and it is deliberate rather than a bug: a stale fallback entry is worse than none, because it silently sends your turns to a provider or a key you did not intend to use.
| Action | Hermes Agent | OpenClaw |
|---|---|---|
| Change model from the dashboard, same provider route | Chain kept | Chain cleared |
| Change model onto or off a provider you supplied a key for | Chain cleared | Chain cleared |
| Add or remove a provider API key | Can clear it | Can clear it |
| Edit the config file directly | Kept as written | Kept as written |
One exception worth knowing on Hermes: if you registered your own provider inside Hermes, a chain you hand-wrote around it is treated as yours and is left alone. The clearing rule applies to routes the platform wrote, not to your own configuration.
Practical habit: treat the chain as something to re-check after any model or key change rather than set-and-forget. The Files editor makes that a ten-second look.
Choosing a chain that actually helps
- Different provider, not just a different model. A chain whose entries all sit behind one provider fails together in exactly the outage you wrote it for.
- Check the keys. Every entry needs a provider the bot can actually authenticate to, or the fallback fails the same way the primary did.
- Keep it short. Two entries covers rate limits and a provider outage. A long chain mostly adds latency to a request that was going to fail anyway.
FAQ
Can I set the fallback chain from the dashboard?
Not from the model picker — that sets the primary only. You can edit the chain from the dashboard through the Files editor on the instance card, which reaches the same config file the terminal does.
Does this work the same on Hermes Agent and OpenClaw?
The idea is the same and the key names are not. Hermes uses a top-level fallback_providers list of provider/model pairs; OpenClaw uses a fallbacks array of provider/model strings under agents.defaults.model. The clearing behaviour also differs: OpenClaw clears on every dashboard model change, Hermes only when the route changes.
Why did my fallback list disappear?
Almost always a model change or a provider-key change made between when you set it and when you looked. Re-add it after the change and it will stick until the next one.
Does a fallback split my traffic across models?
No. The chain is failover, not load balancing — entries are tried in order and only after the primary call fails.
Running either framework on managed hosting? Hermes Agent hosting and OpenClaw hosting both include the Files editor and the model picker described here. See also OpenClaw multi-model routing and Hermes Agent BYOK.