Unknown model | Friends of the Crustacean 🦞🤝 | Page 1

runic edge Feb 16, 2026, 1:19 AM

#

What is wrong with my config that agent keeps failing saying Unknown model both in agent and HEARTBEAT?

"defaults": {
      "model": {
        "primary": "openrouter/minimax/minimax-m2.5"
      },
      "models": {
        "openrouter/minimax/minimax-m2.5": {}
      },
      "heartbeat": {
        "model": "ollama/llama3.2:3b"
      },
    },

next palmBOT Feb 16, 2026, 1:19 AM

#

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

rancid thistleBOT Feb 16, 2026, 1:23 AM

#

Two common causes of Unknown model: ... with a setup like that:

Provider isn’t configured / no auth profile found, so OpenClaw never “enables” that provider

OpenRouter needs OPENROUTER_API_KEY
Ollama needs OLLAMA_API_KEY (any dummy value is fine — it just opts you into discovery)

Docs:

If you set an explicit model catalog/allowlist at agents.defaults.models, you must include every model you reference — including the heartbeat model.

A working shape (using your model refs)

{
  env: {

#

    OPENROUTER_API_KEY: "sk-or-...",
    OLLAMA_API_KEY: "ollama-local"
  },
  agents: {
    defaults: {
      model: { primary: "openrouter/minimax/minimax-m2.5" },

      heartbeat: { model: "ollama/llama3.2:3b" },

      models: {
        "openrouter/minimax/minimax-m2.5": {},
        "ollama/llama3.2:3b": {}
      }
    }
  }

#

Quick sanity checks

Please run these and paste the output:

openclaw --version
openclaw models status
openclaw models list

That usually makes it instantly obvious whether it’s (a) missing provider auth, (b) the model isn’t in your allowlist/catalog, or (c) the provider can’t be injected for some other reason.

runic edge Feb 16, 2026, 1:28 AM

#

ollama seems to changed but minimax not:
openrouter/minimax/minimax-m2.5 - - - - default,configured,missing

rancid thistleBOT Feb 16, 2026, 1:28 AM

#

That default,configured,missing status is the clue: the model is in your allowlist/config, but the provider auth is missing, so OpenClaw doesn’t inject/enable the openrouter provider → it can’t resolve the model at runtime and you end up with Unknown model.

Fix: give OpenRouter a credential (either env var or auth profile), then restart.

Option A (recommended): put the key in config so the service always has it

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

Option B: store it in OpenClaw’s auth profiles

openclaw models auth paste-token --provider openrouter

#

openclaw models status

Docs:

If you already set OPENROUTER_API_KEY in your shell: double-check you’re not running the gateway as a service that doesn’t inherit your shell env (common on systemd/launchd). Putting it under env in ~/.openclaw/openclaw.json avoids that class of issue.

runic edge Feb 16, 2026, 1:30 AM

#

this is not true because I already run openrouter/google/gemini-3-flash-preview successfully with OPENROUTER_API_KEY

runic edge Feb 16, 2026, 1:59 PM

#

@rancid thistle

rancid thistleBOT Feb 16, 2026, 2:02 PM

#

Two separate things are going on here: the models you reference can’t be resolved because their providers aren’t enabled/configured, and (for heartbeat) you may also be hitting the models allowlist behavior.

1) “Unknown model …” usually means “provider not configured / model not discoverable”

For your two model IDs, that typically means:

OpenRouter model openrouter/minimax/minimax-m2.5
→ you need OpenRouter auth (e.g. OPENROUTER_API_KEY) so the openrouter provider gets injected.

Docs: https://docs.openclaw.ai/providers/openrouter
Ollama model ollama/llama3.2:3b
→ you need to enable Ollama for OpenClaw (yes, even though Ollama itself is local). Easiest is setting OLLAMA_API_KEY to any value.

Docs: https://docs.openclaw.ai/providers/ollama

A minimal config shape looks like:

#

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    OLLAMA_API_KEY: "ollama-local"
  },
  agents: {
    defaults: {
      model: { primary: "openrouter/minimax/minimax-m2.5" },
      heartbeat: { model: "ollama/llama3.2:3b" },
      models: {
        "openrouter/minimax/minimax-m2.5": {},
        "ollama/llama3.2:3b": {}
      }
    }
  }

#

2) If you set `agents.defaults.models`, it becomes an allowlist

So if you only list the OpenRouter model in agents.defaults.models, anything trying to run on Ollama (including heartbeat overrides) can get blocked.

FAQ section (models allowlist behavior): https://docs.openclaw.ai/help/faq (see “Model is not allowed …”)

3) Quick debugging commands to confirm what OpenClaw thinks is available

Please paste these outputs:

openclaw --version
openclaw models status
openclaw models list

#Unknown model