OpenClaw

OpenClaw "Embedded agent failed before reply: Unknown model: provider/model"

Last checked

The error

Embedded agent failed before reply: Unknown model: anthropic/claude-example-1. Run `openclaw models list --refresh --provider anthropic` to inspect this provider's model choices, then retry with a model supported by your account.

Printed in the Gateway log. The provider and model in your message will differ; some providers add their own hint instead of the models list one.

OpenClaw could not resolve the model id it was asked to use, so the agent stopped before sending anything. The id is missing from the provider's catalog: it is mistyped, retired, not available on your account, or the provider's catalog did not load. Run openclaw models list --refresh --provider <provider>, pick a valid id, and set it with openclaw models set <provider/model>. Then check agents.defaults.model.fallbacks for the same stale id.

Why it happens

Every model reference is provider/model. Before a turn starts, OpenClaw looks that pair up in the provider's model catalog. If nothing matches, it throws Unknown model and treats it as a model_not_found failure.

  1. The id is wrong or retired: a typo, an old dated id, or a model the provider has shut down still sits in agents.defaults.model.primary, a fallbacks list, or an agent's own model setting.
  2. The provider's catalog did not load. After the 2026.9.5 upgrade, minimax-portal lost its catalog and every turn failed with Unknown model: minimax-portal/MiniMax-M3 (issue #152804).
  3. Your installed release does not know the model yet. A newly launched model may need an OpenClaw update before it appears in the catalog.
  4. A custom or local provider is missing the model under models.providers.<provider>.models, or the id there is not the bare provider-local id.
  5. A legacy provider id such as openai-codex is still in config. The error then tells you to run openclaw doctor --fix to migrate it.

The fix

  1. 1 Copy the exact provider/model from the error line in openclaw logs --follow.
  2. 2 List what the provider really offers: openclaw models list --refresh --provider <provider>. Use openclaw models list --all if you are unsure of the provider id.
  3. 3 Set a valid default: openclaw models set <provider/model>. This updates agents.defaults.model.primary.
  4. 4 Check fallbacks: openclaw models fallbacks list, then openclaw models fallbacks remove <bad-model> and add a valid one.
  5. 5 Run openclaw doctor. It flags configured model references that are not in the local catalog and migrates known legacy ones with --fix.
  6. 6 Restart the Gateway with openclaw gateway restart and send a test message.
openclaw models list --refresh --provider <provider>

Where the model id is set

The default lives at agents.defaults.model.primary in ~/.openclaw/openclaw.json, with fallbacks at agents.defaults.model.fallbacks. Heartbeats, subagents, compaction and individual agents can each have their own model setting, so a stale id in any of them produces the same error for that path only. openclaw models status shows the resolved default and fallbacks.

openclaw models status
openclaw config get agents.defaults.model --json

Still failing?

  • If models list shows the model but runs still fail, restart the Gateway so the running process reloads its catalog.
  • If the id is valid but your account cannot use it, check provider auth with openclaw models status and re-authenticate.
  • If only one agent fails, check that agent's own model setting and any per-session /model override in that chat.

Related errors

Full guideOpenClaw Model Routing: Cut API Costs 65% With One Fix

Hit a different error?

Paste any agent error and get the cause and fix in seconds.

Open the decoder

Frequently asked questions

Will OpenClaw fall back to another model automatically?

Yes, if a valid model is configured in agents.defaults.model.fallbacks. model_not_found is a failover reason. If the fallbacks contain the same stale id, or are empty, the turn fails.

The model works with curl but OpenClaw says Unknown model. Why?

OpenClaw resolves the id against its own catalog first. For custom or local servers, add the model under models.providers..models with the bare id the server expects, then select it with the provider prefix.

Do I need to edit openclaw.json by hand?

No. openclaw models set and openclaw models fallbacks add or remove write the same keys and avoid JSON5 typos.

Stop firefighting agent errors

Decoding errors one at a time is the manual version of what BetterClaw automates. Run your agents on a no-code AI agent platform with managed models, retries and config validation built in.

Deploy Your Agent — Start FreeBook a Demo

Free plan available · Pro $49/mo · BYOK · 7-day money-back guarantee