#13857: fix: warn when local agent models.json silently overrides central config
commands
agents
stale
Cluster:
Wizard Enhancements and Config Fixes
## Summary
Adds detection and warnings for per-agent `models.json` files in `~/.openclaw/agents/<id>/agent/` that silently shadow the central `openclaw.json` model configuration.
## Problem
`ensureOpenClawModelsJson` writes a local `models.json` to each agent dir on startup. These files accumulate stale provider/model entries that override central config. When users change models via `gateway config.patch`, the change appears to succeed but the local file wins — with no warning anywhere.
This caused significant debugging time in a multi-agent setup (all agents showing wrong models after multiple config.patch calls). The only fix was manually `rm`-ing each agent's `models.json`.
Related: #13854
## Changes
1. **New utility** `src/agents/models-config-overrides.ts`:
- `detectLocalModelOverrides(cfg)` — scans all configured agent dirs for `models.json` files and returns metadata (agent id, path, provider keys)
2. **Security audit** (`src/security/audit.ts`):
- Adds a `warn` severity finding for each agent with a local `models.json` override
- Includes remediation: remove the file or use `agents.list[].model` in central config
3. **Status --all** (`src/commands/status-all.ts` + `report-lines.ts`):
- Surfaces override warnings in the Agents section
- Shows affected file paths and a one-liner fix command
## Example output
```
⚠️ Local model overrides detected (these silently shadow openclaw.json):
→ Agent "my-agent" has local models.json with providers: xai, local
~/.openclaw/agents/my-agent/agent/models.json
Fix: Remove these files so agents inherit from openclaw.json, or use agents.list[].model in central config.
Run: find ~/.openclaw/agents/ -name models.json -delete
```
Security audit:
```
WARN Agent "my-agent" has local models.json override
~/.openclaw/agents/my-agent/agent/models.json contains providers [xai, local] that silently shadow the central openclaw.json...
Fix: Remove the local override: rm "~/.openclaw/agents/my-agent/agent/models.json"
```
## Testing
- Verified with multiple agents — all had stale local `models.json` files
- After removing local files, agents correctly inherit central config
- Warning only appears when local overrides exist; clean installs show nothing
Closes #13854
Most Similar PRs
#20954: feat: per-agent model allowlist
by coletebou · 2026-02-19
70.5%
#17021: fix(agents): read models from gateway config first
by Limitless2023 · 2026-02-15
70.3%
#13940: fix: suppress low context window warning for explicitly configured ...
by tsukhani · 2026-02-11
69.5%
#16988: fix: always regenerate models.json from gateway config
by MisterGuy420 · 2026-02-15
68.3%
#13376: fix: pass model directly to agent for sub-agent runs
by jrbobbyhansen-pixel · 2026-02-10
68.0%
#9583: fix(models): allow models in agents.defaults.models even if not in ...
by hotzen100 · 2026-02-05
66.9%
#11562: Fix #10883: Enforce subagent model configuration
by divol89 · 2026-02-08
66.2%
#21963: fix(cli): models fallbacks add now includes primary model in allowlist
by ashiabbott · 2026-02-20
66.1%
#15756: [Security]: strip provider apiKey from models.json before prompt se...
by SecBear · 2026-02-13
65.9%
#9064: fix: validate model references against catalog in config.set/patch/...
by joetomasone · 2026-02-04
65.7%