Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

When registering a new model with a provider plugin (e.g., microsoft-foundry) by setting only agents.defaults.models["<provider>/<id>"], dispatch fails with Error: Unknown model: <provider>/<id> even though the plugin is loaded and env vars are set. The actual gap — that models.providers["<provider>"].models[] must also list the model — is not surfaced in the error message and is not documented.

Steps to reproduce

# Plugin loaded
$ openclaw plugins list --json | jq -r '.[] | select(.name|test("microsoft-foundry")) | "\(.name) \(.version) \(.status)"'
@openclaw/microsoft-foundry 2026.5.7 loaded

# Env vars set
$ openclaw config get env.MICROSOFT_FOUNDRY_API_KEY --json   # (redacted) present
$ openclaw config get env.MICROSOFT_FOUNDRY_BASE_URL --json
"https://<resource>.services.ai.azure.com/openai/v1"

# Set ONLY the agents.defaults.models block (intuitive — that's where the agent picks fallbacks from)
$ openclaw config set 'agents.defaults.models["microsoft-foundry/Kimi-K2.6-1"]' \
  '{"contextWindow":262144,"maxOutputTokens":16384,"capabilities":["chatCompletion"]}' \
  --strict-json
$ openclaw gateway restart && sleep 30

# Try to use it
$ openclaw infer model run --model microsoft-foundry/Kimi-K2.6-1 --gateway --prompt "ping"
Error: Unknown model: microsoft-foundry/Kimi-K2.6-1.

After also adding the second config block, dispatch succeeds:

$ openclaw config set 'models.providers["microsoft-foundry"].models' \
  '[{"id":"Kimi-K2.6-1","contextWindow":262144,"maxOutputTokens":16384,"capabilities":["chatCompletion"]}]' \
  --strict-json
$ openclaw gateway restart && sleep 30
$ openclaw infer model run --model microsoft-foundry/Kimi-K2.6-1 --gateway --prompt "ping"
[response]

Expected behavior

Either:

1. The error message should point at the actual gap. Suggested wording: "Unknown model 'microsoft-foundry/Kimi-K2.6-1'. Found in agents.defaults.models but not in models.providers['microsoft-foundry'].models[]. Both blocks are required to register a model with a provider plugin."

2. Or the config-set call should auto-mirror to the providers block when only one half is supplied, with a notice on the CLI: "Note: also added microsoft-foundry/Kimi-K2.6-1 to models.providers.microsoft-foundry.models[] for consistency."

3. Or openclaw doctor should flag the inconsistency at health-check time.

Actual behavior

The CLI returns Error: Unknown model: <provider>/<id> with no hint about the missing config block. Operators read the error as "the model id is wrong" and search the wrong path (model id typos, plugin install issues, env var problems). In this incident, ~30 minutes was spent before discovering the second block requirement was simply not documented.

OpenClaw version

2026.5.7 (eeef486)

Operating system

Ubuntu 24.04

Install method

npm global at /usr/local, system Node v22.22.2 (apt, held)

Model

microsoft-foundry/Kimi-K2.6-1 (and several others — same behavior with gpt-5.4-mini, DeepSeek-V4-Flash, DeepSeek-V3.2)

Provider / routing chain

openclaw -> microsoft-foundry (api_key) -> Azure AI Foundry openai-completions surface

Additional provider/model setup details

@openclaw/[email protected] plugin installed via openclaw plugins install. Env vars MICROSOFT_FOUNDRY_API_KEY + MICROSOFT_FOUNDRY_BASE_URL set in ~/.openclaw/.env and reloaded via gateway restart. After both config blocks are populated and gateway restarted, six different microsoft-foundry models registered cleanly and dispatch correctly.

Logs, screenshots, and evidence

# Plugin loaded, env vars present, only agents.defaults.models set:
$ openclaw infer model run --model microsoft-foundry/Kimi-K2.6-1 --gateway --prompt "ping"
Error: Unknown model: microsoft-foundry/Kimi-K2.6-1.

# Config inspection at the failing state:
$ openclaw config get 'agents.defaults.models["microsoft-foundry/Kimi-K2.6-1"]' --json
{ "contextWindow": 262144, "maxOutputTokens": 16384, "capabilities": ["chatCompletion"] }

$ openclaw config get 'models.providers["microsoft-foundry"].models' --json
null   # ← the gap

# After also setting models.providers, dispatch works.

Impact and severity

• Affected: anyone adding a new provider plugin (microsoft-foundry, openrouter, any custom provider) — this happens on first registration.
• Severity: low (workaround is "set both blocks"), but discoverability is poor.
• Frequency: once per new-provider-onboarding event. Easy to hit; hard to debug.
• Consequence: ~30 min lost per incident; on a multi-host fleet where each host registers its own provider catalog, this cost compounds.

Additional information

Suggested permanent fix (smallest blast radius): improve the dispatch-time error message to name the missing block. The "auto-mirror at config-set time" alternative is more invasive and might surprise operators who intentionally split the two blocks. Documentation: the relevant docs page (concepts/models or similar) should include a worked example for registering a new provider/model that exercises both blocks.

This issue is also adjacent to the more general "Unknown model" search results (#58289 non-main agent, #66017 image custom provider, #45240 LiteLLM, #64799 volcengine) — those each describe different scenarios where the same error message hides different root causes. A general improvement to the "Unknown model" error message that names the failing resolution step would help all of those cases.