openclaw - 💡(How to fix) Fix Model registry name matching is load-bearing — silent fallback to picker selection on registry miss (2026.5.12)

TL;DR

Model registry name matching in OpenClaw is load-bearing but completely opaque. A single-character difference (4.6 vs 4-5) caused 13+ hours of multi-turn chat failures with no actionable logs. The runtime silently fell through to picker selection when the registry missed, emitting no traces. This issue requests INFO-level resolution logging, startup warnings for stale picker entries, and documentation of the picker-overrides-config behavior.

Symptoms

1. Multi-turn conversations fail with "model not found" or HTTP 500, while single-turn works
2. Config-vs-actual model mismatch: openclaw.json specifies claude-sonnet-4.6 but runtime calls claude-sonnet-4-5 (or fails entirely)
3. HTTP 500 with no explanation: Direct curl to provider succeeds; OpenClaw call to same model returns 500
4. Stale picker entries silently take precedence over openclaw.json model configuration (inferred from behavior — see Evidence)
5. Zero debuggability: journalctl -u openclaw | grep -E "model|resolved|registry" returns nothing

Root Cause

Exact-String Registry Matching

OpenClaw performs exact-string matching against the model registry. The following are treated as different models:

The . vs - difference is not normalized. No fuzzy matching, no alias resolution, no "did you mean" suggestion.

Silent Picker Fallthrough

When the registry misses, OpenClaw silently falls through to the interactive picker (the model selection UI). If the picker has stale entries (e.g., minimax/minimax-2.5 which no longer exists), the runtime attempts to route to an invalid model. This produces:

• "model not found" errors
• HTTP 500 from upstream
• Multi-turn protocol failures (websocket 1002)

No log is emitted during this fallthrough. The user sees only the final error, not the resolution chain.

Stale Picker Entries

The picker retains entries even after:

• Models are removed from the provider
• Provider configuration changes
• API keys are rotated

These stale entries appear to override the explicit primary model in openclaw.json (inferred from behavior; source confirmation requested).

Evidence

Trajectory File Excerpt (Actual)

From ~/.openclaw/agents/main/sessions/2a3784ae-80d9-4051-8cc6-b8a2ead91d0b.trajectory.jsonl:

{
  "provider": "openrouter",
  "modelId": "minimax/minimax-2.5",
  "modelApi": "openai-completions",
  ...
  "errorMessage": "400 minimax/minimax-2.5 is not a valid model ID"
}

What this shows:

• Runtime called minimax/minimax-2.5 (a stale picker entry, no longer in registry)
• OpenRouter returned 400 "not a valid model ID"
• This happened during a Telegram chat session where the configured model was moonshot/kimi-k2.6
• The picker entry minimax/minimax-2.5 was selected instead of the configured primary

Config Example (Broken)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6",
        "fallbacks": ["anthropic/claude-sonnet-4-5"]
      }
    }
  }
}

Fix Applied

1. Deselected stale picker entries (minimax/minimax-2.5)
2. Changed config to exact registry name: anthropic/claude-sonnet-4-5
3. Multi-turn chat immediately restored

Debugging Time

• 13+ hours across May 15-16
• Multiple false leads (gateway protocol mismatch, CLI version mismatch, auth issues)
• Root cause identified only by cross-referencing config, registry, and picker state manually

Requested Fixes

1. INFO-Level Resolution Traces

Emit model resolution at INFO level (not DEBUG):

[model-resolver] Requested: openrouter/anthropic/claude-sonnet-4.6
[model-resolver] Provider: openrouter → resolved
[model-resolver] Model lookup: claude-sonnet-4.6 → NOT FOUND
[model-resolver] Registry candidates: [claude-sonnet-4-5, claude-sonnet-4, claude-3-5-sonnet]
[model-resolver] Fallback chain: [anthropic/claude-sonnet-4-5]
[model-resolver] Selected: anthropic/claude-sonnet-4-5

2. Startup Warning for Unresolved Picker Entries

On gateway start, warn if picker entries don't resolve to registry models:

[warn] Picker entry "minimax/minimax-2.5" does not match any model in registry
[warn] Run `openclaw models list` to update picker selections

3. Document Picker-Overrides-Config Behavior

Add to docs: "The interactive picker selection appears to take precedence over openclaw.json model configuration (behavior inferred; source confirmation requested). To force config-only mode, run openclaw picker reset."

4. Optional Fail-Loud Mode

Add config option:

{
  "models": {
    "resolution": {
      "mode": "strict",
      "onMiss": "error",
      "fuzzyMatch": false
    }
  }
}

In strict mode, registry miss = immediate error with resolution trace, no picker fallthrough.

Cross-References

• #80972 — Related upstream filing from same reporter: heartbeat routing bug (distinct bug, same product)
• #82150 — Different bug in similar territory: OpenRouter/DeepSeek tool-call replay (fixed in 2026.5.14-beta.1)
• #82177 — Different bug in similar territory: Telegram active-memory hanging on invalid chat ids (fixed in 2026.5.14-beta.1)
• #76877 — Different bug in similar territory: LLM idle watchdog timeouts (fixed in 2026.5.12-beta.6)

Note: This issue is related but distinct from the above. Those fixes addressed specific provider/chat bugs; this issue addresses resolution observability and picker precedence.

Environment

• OpenClaw Version: 2026.5.12 stable
• OS: Ubuntu 24.04 on WSL2
• Channels: Telegram, webchat, WhatsApp
• Primary Model: moonshot/kimi-k2.6 (via OpenRouter)
• Fallback Model: anthropic/claude-sonnet-4-5 (direct)
• Bootstrap Config: bootstrapMaxChars: 30000, bootstrapTotalMaxChars: 50000

Full Investigation Report

The sanitized report (12KB) contains detailed analysis of auth architecture, registry behavior, bootstrap truncation, and provider differences. Available on request — not linked here because the file is not in the OpenClaw repo.

Key sections:

• Q1: Where Did Anthropic Auth Come From? (auth-profiles.json analysis)
• Q2: Why Did Model Name Matching Matter? (registry exact-match behavior)
• Q3: Why Did kimi-k2.6 Fail When Registry Entry Is Correct? (HTTP 500 mystery)
• Q4: Runtime Difference Anthropic-Direct vs OpenRouter-Proxied
• Synthesis: What Made Anthropic-Direct Work
• Recommendations for Upstream (4 priority levels)
• Open Questions (4 items)