Bug type

Behavior bug — misleading/incomplete error remediation guidance.

Summary

The model_not_found / "Unknown model" remediation message — the one added to surface the missing models.providers[<id>].models[] requirement (#80089, PRs #80098/#80104) — tells you to add a config snippet that does not work. Following it verbatim fails twice:

1. The suggested snippet { "id": "<model>" } fails schema validation because name is also required (ModelDefinitionSchema: id: z.string().min(1), name: z.string().min(1)).
2. Even after adding name, for any provider whose transport baseUrl is not supplied out-of-band (env var / bundled catalog), the entry silently misroutes to the OpenAI default endpoint and dispatches the provider's API key to platform.openai.com → confusing 401 Incorrect API key. (This is the credential-misroute tracked in bug(models): Missing google provider config silently routes Gemini requests to OpenAI #85042.)

So the message that is supposed to teach the fix leads the user straight into a schema error and then a security-adjacent misroute.

Environment

• OpenClaw v2026.5.28, gateway on Linux (OrbStack VM)
• Provider opencode (OpenCode Zen), key via OPENCODE_API_KEY

Steps to reproduce

1. Reference a provider model that exists at the provider but isn't in OpenClaw's bundled/discovered catalog, e.g. opencode/claude-opus-4-8 (OpenCode Zen serves it: GET https://opencode.ai/zen/v1/models lists it). Add it to agents.defaults.model.fallbacks.
2. Trigger a run that resolves to it. You get:

   Unknown model: opencode/claude-opus-4-8. Found agents.defaults.models["opencode/claude-opus-4-8"],
   but no matching models.providers["opencode"].models[] entry.
   Add { "id": "claude-opus-4-8" } to models.providers["opencode"].models[] to register this provider model.
   

3. Follow the message exactly — add { "id": "claude-opus-4-8" }:

   Invalid config: models.providers.opencode.models.0.name: Invalid input
   

4. Add the required name ({ "id": "claude-opus-4-8", "name": "Claude Opus 4.8" }), push, restart, run:

   OpenAI API error (401): Incorrect API key provided: sk-wk***fI1x.
   You can find your API key at https://platform.openai.com/account/api-keys
   

   The opencode key is dispatched to platform.openai.com.

Expected

The remediation message should produce a working config when followed verbatim. Concretely:

• Include the required name field in the suggested snippet.
• When the target provider has no out-of-band baseUrl, the snippet should also include api + baseUrl (or the message should explicitly note they are required), so the entry routes to the correct provider endpoint instead of silently falling back to the OpenAI adapter.
• Ideally link to the provider/model config docs.

Working config (for reference)

"models": { "providers": { "opencode": { "models": [
  { "id": "claude-opus-4-8", "name": "Claude Opus 4.8",
    "api": "openai-completions", "baseUrl": "https://opencode.ai/zen/v1" }
] } } }

With api + baseUrl present the request reaches Zen and succeeds.

Related

• [Bug]: 'Unknown model' error hides the missing models.providers[id].models[] block when only agents.defaults.models is set #80089 — the issue that requested surfacing this guidance (the message originates from its fix, fix: explain missing provider model registration #80098/fix(model): hint at missing models.providers block in Unknown model error #80104). This report is that the surfaced message is incomplete.
• bug(models): Missing google provider config silently routes Gemini requests to OpenAI #85042 — the silent credential-to-OpenAI misroute that step 4 above lands on (live opencode repro posted there).