Best possible solution:

Land the narrow resolver diagnostic with regression coverage once real behavior proof shows the reported one-block provider setup now points operators to the missing provider model registration.

Do we have a high-confidence way to reproduce the issue?

Yes. The linked issue gives a concrete config and CLI sequence, and current source inspection shows the same path falls through to the generic Unknown model when the model is absent from models.providers and discovery.

Is this the best way to solve the issue?

Yes. A targeted diagnostic in the model-resolution error path is narrower and safer than auto-mirroring config, and it matches the existing split between allowlist/default params and provider registration.

What I checked:

• Current main error path: Current main normalizes the requested provider/model, checks configured provider models and discovery/runtime sources, then builds the generic Unknown model: provider/model error; there is no current-main check for a matching agents.defaults.models entry missing from models.providers before the PR. (src/agents/pi-embedded-runner/model.ts:1225, 4c1e6ba2f03b)
• Config contract docs: The docs distinguish agents.defaults.models as allowlist/aliases/provider params and models.providers as the custom provider/model registration surface, which supports treating the reported one-block setup as a diagnostic gap rather than a new registration behavior. Public docs: docs/concepts/models.md. (docs/concepts/models.md:91, 4c1e6ba2f03b)
• PR diff: The patch adds findConfiguredAgentModelEntry, buildMissingProviderModelRegistrationHint, wires that hint into buildUnknownModelError, and adds a focused unit test for microsoft-foundry/Kimi-K2.6-1 configured only in agents.defaults.models. (src/agents/pi-embedded-runner/model.ts:488, 54dacaac0871)
• Linked issue evidence: The linked issue describes a concrete OpenClaw 2026.5.7 repro where agents.defaults.models["microsoft-foundry/Kimi-K2.6-1"] exists, models.providers["microsoft-foundry"].models is null, and openclaw infer model run --gateway returns the generic Unknown model; adding the provider model list makes dispatch succeed.
• Real behavior proof gate: The PR body lists a unit-test command and git diff --check, but the head SHA's check runs include two failing Real behavior proof checks; normal CI is supplemental and does not replace after-fix real setup proof for an external PR. (54dacaac0871)
• Area history: Current local blame attributes the relevant helper/error-builder area to Peter Steinberger, while remote path history shows recent model resolver work by steipete and pashpashpash plus the Microsoft Foundry provider introduction by haxudev. (src/agents/pi-embedded-runner/model.ts:449, 5e332e1d58d7)

Likely related people:

• steipete: Local blame on the current helper/error-builder area and remote commit history show recent model-resolution and test work in the affected files. (role: recent model resolver contributor; confidence: high; commits: 5e332e1d58d7, 355ea947f5af, 6e67a6374bdb; files: src/agents/pi-embedded-runner/model.ts, src/agents/pi-embedded-runner/model.test.ts)
• pashpashpash: Recent merged work changed OpenAI/Codex model routing and auth behavior in the same resolver surface that this diagnostic uses. (role: adjacent runtime policy contributor; confidence: medium; commits: 1c3399010815, 3a901b5e9539; files: src/agents/pi-embedded-runner/model.ts, src/agents/pi-embedded-runner/model.test.ts)
• haxudev: The linked reproduction uses Microsoft Foundry, and remote history attributes the provider's initial implementation to this contributor. (role: Foundry provider introducer; confidence: medium; commits: a16dd967da51; files: extensions/microsoft-foundry/provider.ts)

Remaining risk / open question:

• The PR still lacks contributor-supplied after-fix real behavior proof from a gateway or openclaw infer model run setup showing the new diagnostic.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4c1e6ba2f03b.