#9064: fix: validate model references against catalog in config.set/patch/apply
gateway
stale
Cluster:
Wizard Enhancements and Config Fixes
## Problem
Fixes #8551
When setting config via `config.set`, `config.patch`, or `config.apply`, invalid model names are accepted silently. The gateway restarts successfully but fails at runtime when trying to use the model.
Example:
```bash
openclaw gateway config.patch --raw '{"agents":{"defaults":{"model":"anthropic/claude-sonnet-4-5-20250514"}}}'
```
The gateway accepts this but fails later because `claude-sonnet-4-5-20250514` doesn't exist.
## Solution
Add model validation against the catalog for all config modification endpoints:
- `config.set`
- `config.patch`
- `config.apply`
When an unknown model is specified, return an error with helpful suggestions:
```
invalid model reference: agents.defaults.model.primary: Unknown model "anthropic/claude-sonnet-4-5-20250514" (did you mean: anthropic/claude-sonnet-4-5?)
```
## Implementation
New file `config-model-validation.ts`:
- `extractModelRefs()` - walks config and extracts model references from known locations
- `validateConfigModels()` - checks refs against catalog, returns issues with suggestions
- `findSuggestions()` - finds similar models from same provider for helpful hints
Validates models in:
- `agents.defaults.model.primary/fallbacks`
- `agents.defaults.imageModel.primary/fallbacks`
- `agents.list[].model.primary/fallbacks`
## Error Handling
If model catalog fails to load (e.g., network issue), validation is skipped rather than blocking config changes. This ensures the feature is additive and doesn't break existing workflows.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Adds model-reference validation to the gateway config mutation endpoints (`config.set`, `config.patch`, `config.apply`) by loading the model catalog and rejecting configs whose agent model fields don’t exist in the catalog. The new `src/gateway/server-methods/config-model-validation.ts` extracts known model reference locations under `agents.defaults.*` and `agents.list[].model.*`, checks them against catalog entries, and returns structured issues plus “did you mean” suggestions. `config.ts` now runs this validation after schema/plugin validation and before persisting the config, returning `INVALID_REQUEST` with issue details when unknown models are found.
<h3>Confidence Score: 3/5</h3>
- This PR is likely safe but has correctness gaps in validation coverage and reliability.
- Core validation logic is straightforward and integrated consistently into the three config mutation handlers, but it currently skips validating unqualified model IDs (if supported by config) and silently bypasses validation whenever catalog loading throws, which can reintroduce the original failure mode. Fixing these would make behavior more deterministic and aligned with the PR’s intent.
- src/gateway/server-methods/config-model-validation.ts, src/gateway/server-methods/config.ts
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#20567: fix: validate model IDs against catalog before saving to config
by baja87 · 2026-02-19
82.7%
#19020: bugfix(gateway): Handle invalid model provider API config gracefully\…
by funkyjonx · 2026-02-17
80.2%
#17021: fix(agents): read models from gateway config first
by Limitless2023 · 2026-02-15
79.9%
#9163: Fix: Save Anthropic setup token to config file
by vishaltandale00 · 2026-02-04
79.8%
#21638: fix(models): surface models.json validation errors instead of faili...
by aldoeliacim · 2026-02-20
79.5%
#16988: fix: always regenerate models.json from gateway config
by MisterGuy420 · 2026-02-15
79.1%
#10608: fix(agents): honor spawn model override in gateway and session spaw...
by 1kuna · 2026-02-06
78.0%
#11107: fix(models): auto-allow selected model on sessions.patch
by Mokoby · 2026-02-07
78.0%
#13376: fix: pass model directly to agent for sub-agent runs
by jrbobbyhansen-pixel · 2026-02-10
77.1%
#18988: feat(config): add support for config warnings and improve validation
by saurav470 · 2026-02-17
77.0%