Summary

loadModelCatalog() caches the resolved catalog at the module level for the lifetime of the gateway process. The Telegram /model picker calls loadModelCatalog({ config: cfg }) without useCache: false, so newly added models under models.providers.* (or agents.defaults.models) never appear in the Telegram inline keyboard until the gateway restarts — even though the same models are present in the active config, in the per-agent agents/<id>/agent/models.json cache, and in openclaw models list.

Only a gateway restart clears the in-memory modelCatalogPromise. There is no config-change hook, no TTL, and no fallthrough for the Telegram picker path.

Environment

• OpenClaw: 2026.4.15 (041266a)
• Runtime: Node 22.22.2
• OS: Linux (Ubuntu aarch64), systemd user service openclaw-gateway.service
• Channel: Telegram
• Config mode: models.mode: "merge" with a custom OpenAI-compatible proxy under models.providers.litellm (private deployment — irrelevant to the bug)

Reproduction

1. Start the gateway with a config that includes provider foo with models [A, B], and agents.defaults.models containing foo/A, foo/B.
2. In Telegram, /model → inline keyboard shows foo/A, foo/B. ✅
3. Stop editing in Telegram. Edit openclaw.json: add model C under models.providers.foo.models[] and add foo/C to agents.defaults.models.
4. Do not restart the gateway. Confirm the config is loaded (new file mtime, gateway process start time earlier than edit).
5. CLI: openclaw models list --json → shows foo/C with available: true, missing: false. ✅ (CLI spawns a fresh process → fresh cache)
6. In Telegram, /model → keyboard still shows foo/A, foo/B only. ❌ foo/C never appears.
7. systemctl --user restart openclaw-gateway → /model now shows foo/C. ✅

Root cause (from dist source, 2026.4.15)

dist/model-catalog-CdCqmHkW.js:11-38

let modelCatalogPromise = null;  // module-level, lives for the process

async function loadModelCatalog(params) {
  if (params?.useCache === false) modelCatalogPromise = null;
  if (modelCatalogPromise) return modelCatalogPromise;
  modelCatalogPromise = (async () => { /* build catalog */ })();
  return modelCatalogPromise;
}

The cache is a single module-level promise with no invalidation tied to config reload, file watchers, meta.lastTouchedAt diffs, or config hashes. Only explicit useCache: false or a test helper clears it.

Callers diverge

Grep results in dist/:

The Telegram picker is the only consumer hitting the unbounded cache. Other UI paths already opt out by passing useCache: false, confirming the intent was "Telegram picker is the odd one out" rather than "caching is safe here."

Call chain (verified in dist/)

1. Telegram /model callback → bot-*.js → telegramDeps.buildModelsProviderData(runtimeCfg, sessionState.agentId)
2. → commands-models-*.js → await loadModelCatalog({ config: cfg }) — no useCache: false
3. → model-catalog-*.js returns the cached promise from process start

Why agents.defaults.models workaround does NOT save you

It's tempting to say "just add the raw ref to agents.defaults.models, because addRawModelRef(raw) in buildAllowedModelSet adds those keys even if they aren't in the catalog." That works for dynamically added aliases, but only at first load — once modelCatalogPromise is filled, loadModelCatalog ignores the new config entirely on subsequent calls from the Telegram picker. The allowlist key and the catalog are merged after the cache is consulted.

Proposed fixes (any one is enough)

1. Config-hash invalidation in loadModelCatalog. Keep the promise keyed by hash(cfg.models) + hash(cfg.agents?.defaults?.models). When it changes, rebuild.
2. Pass useCache: false from buildModelsProviderData. One-line fix that matches how model-picker-*.js and auth-choice-*.js already behave. Catalog build is not that hot on interactive /model presses.
3. Invalidate on config reload events. The gateway already re-reads config in some paths (e.g. clobber recovery) — wire that to resetModelCatalogCacheForTest-equivalent.

Option 2 is the smallest and most consistent with existing callers. Option 1 is the most robust.

Impact

Any user who edits models.providers.* or agents.defaults.models while the gateway is running sees a confusing divergence:

• ✅ openclaw models list --json → new model present
• ✅ ~/.openclaw/agents/<id>/agent/models.json → new model present
• ✅ Other model picker UIs → new model present
• ❌ Telegram /model → new model missing

The standard debugging reflex ("maybe the config didn't save / maybe the cache file didn't write") doesn't find anything, because the stale data is purely in-memory.

The only fix is openclaw gateway restart, which isn't documented as a required step for model changes.

Workaround for affected users

systemctl --user restart openclaw-gateway
# or
openclaw gateway restart

Related

• #42854 "Model picker shows stale Gemini preview alias" — similar shape (stale picker), likely different root cause (alias registry) but worth cross-linking.

Happy to PR option 2 if maintainers confirm direction.