• Primary Symptom: Selecting a specific model from the web UI dropdown results in a different model being executed.
• Secondary Symptom: The model selection persists visually but the API response comes from an unintended model provider.

CLI Verification Example

When the issue is active, direct API calls may reveal model mismatch:

# API request targeting specific model
curl -X POST http://localhost:8080/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Model: mimo-v2.5-pro" \
  -d '{"messages":[{"role":"user","content":"test"}]}'

# Expected: Response metadata shows "model": "mimo-v2.5-pro"
# Actual: Response metadata shows different model (e.g., "deepseek-v4-flash")

Web UI Indicators

• Dropdown displays the correct model name after selection
• No JavaScript console errors in browser DevTools
• Request payload sent to backend contains model field with correct value
• Response model field differs from request

Log Evidence Pattern

# Backend logs may show routing decision override
[2026-05-XX HH:MM:SS] WARN  [Router] Model override detected:
    Requested: mimo-v2.5-pro
    Routed to: deepseek-v4-flash
    Reason: Default model fallback active

Architectural Analysis

The regression in v2026.5.7 indicates a breakdown in the model selection pipeline between the frontend web UI and the backend routing layer. Based on the regression context and affected models (mimo-v2.5-pro, deepseek-v4-flash), the following root causes are most probable:

1. Frontend-Backend Contract Violation

In v2026.5.7, the API endpoint for model selection may have changed its parameter naming convention or request body schema:

• Before (v2026.5.6): POST /api/v1/generate with {"selected_model": "mimo-v2.5-pro"}
• After (v2026.5.7): Endpoint changed to POST /api/v1/chat/completions with {"model": "mimo-v2.5-pro"}

If the frontend was not updated to match the new schema, the backend ignores the model parameter and falls back to a default.

2. Configuration Override Logic Regression

The openclaw.yaml configuration loader may have introduced a new override priority in v2026.5.7:

# New priority order introduced in 2026.5.7 (incorrect precedence)
priority_order:
  - system_default_config    # NOW HAS HIGHEST PRIORITY
  - environment_variable     # Moved down
  - user_requested_model     # NOW HAS LOWEST PRIORITY
  - explicit_config_file

This would cause system_default_config to always override user-specified model selections.

3. Model Registry Cache Invalidation Failure

The model registry may not properly reflect newly added models after the v2026.5.7 upgrade:

# models.json registry state after upgrade
{
  "models": [
    {"id": "deepseek-v4-flash", "enabled": true, "provider": "openai"},
    {"id": "mimo-v2.5-pro", "enabled": false}  // <-- stale disabled state
  ]
}

The web UI reads from the registry and may display enabled models only, creating a disconnect between UI options and actual execution targets.

4. Request Header Parsing Change

The backend router may have changed from reading X-Model headers to requiring explicit model in the JSON body:

# Old request format (still sent by web UI)
POST /api/v1/chat/completions
X-Model: mimo-v2.5-pro
{"messages": [...]}

# Backend now expects (2026.5.7)
POST /api/v1/chat/completions
{"model": "mimo-v2.5-pro", "messages": [...]}

Method 1: Configuration Override Fix

If the issue is caused by configuration precedence, adjust the openclaw.yaml to ensure user selections take priority:

# /etc/openclaw/openclaw.yaml or ~/.openclaw/config.yaml
# BEFORE (v2026.5.7 default - problematic)
model_selection:
  priority: [system_default, environment, user_requested]
  fallback_to_default: true

# AFTER (corrected configuration)
model_selection:
  priority: [user_requested, environment, system_default]
  fallback_to_default: false

Method 2: Restart with Registry Reset

# Step 1: Stop the OpenClaw service
sudo systemctl stop openclaw

# Step 2: Clear the model registry cache
sudo rm -rf /var/lib/openclaw/cache/model_registry.json
sudo rm -rf ~/.openclaw/cache/model_registry.json

# Step 3: Verify the model configuration file
cat ~/.openclaw/models.yaml

Ensure the models are properly listed and enabled:

# ~/.openclaw/models.yaml
models:
  - id: mimo-v2.5-pro
    enabled: true
    provider: openai
    api_base: https://api.example.com/v1

  - id: deepseek-v4-flash
    enabled: true
    provider: openai
    api_base: https://api.deepseek.com/v1

# Step 4: Restart the service
sudo systemctl start openclaw

# Step 5: Verify model registration
curl http://localhost:8080/api/v1/models

Method 3: Downgrade to Previous Stable Version

# If immediate fix is critical, revert to v2026.5.6
sudo apt install openclaw=2026.5.6
sudo systemctl restart openclaw

Method 4: Web UI Cache Clear

# Clear browser-side cache
# 1. Open browser DevTools (F12)
# 2. Right-click on Refresh button
# 3. Select "Empty Cache and Hard Reload"
# 4. Or manually clear via DevTools > Application > Storage > Clear site data

Test 1: Direct API Model Specification

# Verify model selection works via API
curl -X POST http://localhost:8080/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mimo-v2.5-pro",
    "messages": [{"role": "user", "content": "test"}],
    "max_tokens": 10
  }' | jq '.model'

# Expected output: "mimo-v2.5-pro"
# If fix is working: will return "mimo-v2.5-pro"

Test 2: Web UI Model Selection Test

# 1. Open OpenClaw web UI in browser
# 2. Select "mimo-v2.5-pro" from model dropdown
# 3. Open DevTools > Network tab
# 4. Send a test request
# 5. Verify the request payload contains correct model
# 6. Verify the response model matches selection

Test 3: Backend Routing Logs

# Check routing decisions in logs
sudo journalctl -u openclaw -f | grep -E "(Model|routing|selected)"

# Should see: "Model selection accepted: mimo-v2.5-pro"
# Should NOT see: "Overriding model to: deepseek-v4-flash"

Test 4: Registry Synchronization

# Verify all expected models are registered
curl -s http://localhost:8080/api/v1/models | jq '.data[].id'

# Expected output should include:
# - mimo-v2.5-pro
# - deepseek-v4-flash
# - any other configured models

Test 5: End-to-End Multi-Model Test

# Script to test multiple model selections
for model in "mimo-v2.5-pro" "deepseek-v4-flash"; do
  response=$(curl -s -X POST http://localhost:8080/api/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d "{\"model\": \"$model\", \"messages\": [{\"role\": \"user\", \"content\": \"test\"}], \"max_tokens\": 5}")
  
  returned_model=$(echo "$response" | jq -r '.model')
  
  if [ "$returned_model" = "$model" ]; then
    echo "✓ PASS: $model selection honored"
  else
    echo "✗ FAIL: Requested $model, got $returned_model"
  fi
done

Environment-Specific Traps

• Docker Installation: Configuration files in containers may be ephemeral. Always mount ~/.openclaw as a volume:

  # Incorrect - config lost on restart
  docker run openclaw/openclaw:latest
  Correct - persistent configuration
  docker run -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest

• Reverse Proxy Configuration: If using nginx/Caddy, ensure headers are forwarded:

  # nginx.conf - required headers
  location /api/ {
      proxy_pass http://localhost:8080;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_pass_request_body on;
  }

• Systemd Service Environment: The service may run with different environment variables:

  # Check actual service environment
  sudo systemctl show openclaw | grep Environment

Configuration Mistakes

• YAML Indentation: OpenClaw config is YAML-sensitive; use spaces (not tabs)
• Model ID Casing: Model IDs are case-sensitive (MIMO-v2.5-pro ≠ mimo-v2.5-pro)
• Stale Config Caching: Changes to openclaw.yaml may require service restart
• Multiple Config Files: Check for conflicting configs in /etc/openclaw/ and ~/.openclaw/

Upgrade-Related Issues

• Incomplete Migration: v2026.5.7 may have introduced schema changes that weren't migrated automatically
• Breaking Changes in Config Format: Review CHANGELOG.md for v2026.5.7 breaking changes

Windows-Specific Considerations

# On Windows (PowerShell), use these equivalent commands
# Config location: $env:USERPROFILE\.openclaw\config.yaml
# Cache location: $env:LOCALAPPDATA\openclaw\cache\

• MODEL_NOT_FOUND — Model specified in request does not exist in the model registry. May occur if the model was not properly registered after v2026.5.7 upgrade.
• MODEL_DISABLED — Model exists but is marked as disabled in models.yaml. The web UI may still display the model if frontend reads from a cached state.
• INVALID_MODEL_SELECTION — Request contains a model parameter in an unsupported format or location (e.g., header-only when body is required).
• ROUTING_FALLBACK_ACTIVE — Internal log/warning indicating the routing layer fell back to a default model. Check configuration priority settings.
• PROVIDER_UNAVAILABLE — The provider for the selected model is unreachable. Ensure API keys and endpoints are configured correctly.
• Historical Issue: #1423 — Similar model selection bug in v2025.11.2 where environment variables overrode UI selections. Fixed in v2025.12.1.
• Historical Issue: #1891 — Model dropdown not updating after provider configuration change. Related to frontend state caching.

Diagnostic Commands Reference

# Full system diagnostics
openclaw doctor

# View current configuration
openclaw config show

# List available models
openclaw models list

# Test specific model
openclaw test --model mimo-v2.5-pro