OpenRouter not working.

[finite junco]

OpenRouter models not working - "Unknown model" error

I'm running OpenClaw 2026.2.9 and can't get OpenRouter models to load. Getting "Unknown model" errors even with the example from docs.

What I've tried:

• Added OPENROUTER_API_KEY to config env section (per docs)
• Tested formats: z-ai/glm-5, openrouter/z-ai/glm-5, openrouter/anthropic/claude-sonnet-4-5
• All fail with "Unknown model: ..." error
• OpenRouter profile exists in auth.profiles
• API key is valid (confirmed credits on OpenRouter account)
Direct Anthropic models work fine. Is there a setup step I'm missing for OpenRouter support?

[south sage]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[autumn estuary]

“Unknown model: …” in OpenClaw usually means the model ref can’t be resolved from your active models catalog (as opposed to an auth failure like “No API key found…”).

For OpenRouter specifically, the two common gotchas are:

1) You’re using a model ref that isn’t in your configured model catalog/allowlist

If you have agents.defaults.models set, it acts as the catalog/allowlist. In that case you must include the OpenRouter model in that map (even if it’s also your primary):

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
      models: {
        "openrouter/anthropic/claude-sonnet-4-5": {},
      },

    },
  },
}

Docs: https://docs.openclaw.ai/help/faq#how-do-i-add-models-from-other-providers-like-openrouter-or-zai
Provider page: https://docs.openclaw.ai/providers/openrouter

2) Your config replaced the built-in provider catalog (models.mode: "replace")

If you have something like:

models: { mode: "replace", providers: { ... } }

…then you’ve overridden the built-in “pi-ai catalog” providers (which include openrouter). Fix is usually: remove that override, or switch to:

models: { mode: "merge" }

(or explicitly add OpenRouter back via models.providers, but “merge” is typically what people want).

---

Quick “tell me which one it is” checks

Can you paste the output of these (redact keys), plus the relevant config blocks?

openclaw models status
openclaw models list --plain | rg '^openrouter/' || true

And also paste (only these parts) from your openclaw.json:

• agents.defaults.model
• agents.defaults.models (if present)
• models (if present)
• env (just confirm OPENROUTER_API_KEY is there)

Once I see whether OpenRouter is present in models list, we’ll know immediately if it’s an allowlist/catalog issue vs. provider catalog being replaced.

[atomic edge]

I actually have the exact same error, but only for ONE model, and that is MiniMax M2.5. Here are my results from the commands:
🦞 OpenClaw 2026.2.9 (33c75cb) — Meta wishes they shipped this fast.

Config : ~/.openclaw/openclaw.json
Agent dir : ~/.openclaw/agents/main/agent
Default : openrouter/minimax/minimax-m2.5
Fallbacks (4) : openrouter/moonshotai/kimi-k2.5, openrouter/anthropic/claude-sonnet-4.5, openrouter/anthropic/claude-3.5-haiku, openrouter/arcee-ai/trinity-large-preview:free
Image model : -
Image fallbacks (0): -
Aliases (1) : OpenRouter -> openrouter/auto
Configured models (6): openrouter/auto, openrouter/anthropic/claude-sonnet-4.5, openrouter/anthropic/claude-3.5-haiku, openrouter/moonshotai/kimi-k2.5, openrouter/minimax/minimax-m2.5, openrouter/arcee-ai/trinity-large-preview:free

And:
"openclaw models list --plain | rg '^openrouter/' || true
openrouter/minimax/minimax-m2.5
openrouter/moonshotai/kimi-k2.5
openrouter/anthropic/claude-sonnet-4.5
openrouter/anthropic/claude-3.5-haiku
openrouter/arcee-ai/trinity-large-preview:free
openrouter/auto
"

[autumn estuary]

That output is the key detail: your config references openrouter/minimax/minimax-m2.5, but OpenClaw still has to be able to resolve that model from its local models registry/catalog. If the model isn’t in the shipped catalog yet, you’ll get exactly:

Unknown model: openrouter/minimax/minimax-m2.5

…and it can happen for one brand‑new OpenRouter model while older ones work.

Quick verification

Run:

openclaw models list --all --provider openrouter --plain | rg 'minimax|minimax-m2\\.5' || true

• If minimax/minimax-m2.5 does not appear there, OpenClaw 2026.2.9 simply doesn’t know that model yet (catalog lag vs OpenRouter’s rapidly changing list).

Workarounds

A) Use a model that is in the catalog (for now), e.g. keep kimi-k2.5 / Sonnet as primary.

B) Add it as a custom provider model (forces it into the resolver)
In ~/.openclaw/openclaw.json:

{
env: { OPENROUTER_API_KEY: "sk-or-..." },

models: {
mode: "merge",
providers: {
openrouter: {
baseUrl: "https://openrouter.ai/api/v1",
apiKey: "${OPENROUTER_API_KEY}",
api: "openai-completions",
models: [
{ id: "minimax/minimax-m2.5", name: "MiniMax M2.5 (OpenRouter)" },

],
},
},
},
}

Then keep using openrouter/minimax/minimax-m2.5 as your model ref.

If you paste the output of that models list --all ... command, I can confirm in one glance whether this is “catalog missing model” vs something else.

[atomic edge]

openclaw models list --all --provider openrouter --plain | rg 'minimax|minimax-m2\.5' || trueue
openrouter/minimax/minimax-m1
openrouter/minimax/minimax-m2
openrouter/minimax/minimax-m2.1

So i guess openclaw doesnt now about the new model released today on openrouter 🙁

[autumn estuary]

Yep — that confirms it. In 2026.2.9 the shipped model catalog only knows:

• openrouter/minimax/minimax-m1
• openrouter/minimax/minimax-m2
• openrouter/minimax/minimax-m2.1

So openrouter/minimax/minimax-m2.5 will fail with Unknown model until OpenClaw’s catalog gets updated (usually next release / running from source main after the catalog bump).

If you want to use it right now (manual override)

You can register it as a custom provider entry and point your agent at that provider:

{
env: { OPENROUTER_API_KEY: "sk-or-..." },

// add a new provider id so you don't override the built-in openrouter catalog

models: {
mode: "merge",
providers: {
"openrouter-manual": {
baseUrl: "https://openrouter.ai/api/v1",
apiKey: "${OPENROUTER_API_KEY}",
api: "openai-completions",
models: [
{
id: "minimax/minimax-m2.5",
name: "MiniMax M2.5 (OpenRouter)",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
},

],
},
},
},

agents: {
defaults: {
model: { primary: "openrouter-manual/minimax/minimax-m2.5" },
models: {
"openrouter-manual/minimax/minimax-m2.5": {},
},
},
},
}