model-troubleshooter

Automatically diagnose and fix model-related errors in OpenClaw/AutoClaw including API issues, timeouts, config errors, and gateway problems.

Model Troubleshooter Skill

PURPOSE

OpenClaw/AutoClaw mein model-related issues ko automatically identify aur permanently resolve karega.

TRIGGERS

Use when user mentions:

• "model error", "JSON parsing error", "API error"
• "model not working", "model timeout", "connection failed"
• "Unexpected end of JSON", "model switched", "bad model response"
• Model configuration issues
• API authentication failures

DIAGNOSIS FLOW

Step 1: Collect Context

# Check current model
/whoami

# Check gateway logs
Get-Content "C:\Users\IDL\.openclaw-autoclaw\logs\gateway.log" -Tail 50

# Check config
openclaw config.get models

Step 2: Identify Issue Type

Error Pattern	Likely Cause	Fix
"Unexpected end of JSON"	Incomplete streaming chunks	Restart gateway + enable chunk validation
"401 Unauthorized"	API key expired/wrong	Update openclaw.json with fresh key
"429 Too Many Requests"	Rate limit hit	Switch model or implement retry logic
"timeout"	Model too slow	Switch to faster model (GLM-5-Turbo)
"connection refused"	Network/endpoint down	Check provider status + failover model
"model not found"	Invalid model ID	Validate model exists in config

Step 3: Apply Fixes

Fix A: Gateway Restart (Quick Fix)

# Trigger graceful restart
openclaw gateway restart

Fix B: Model Switch (Permanent Fix)

If current model consistently fails:

1. Check available models: openclaw config.get models.providers
2. Switch to reliable fallback:

   {
     "agents": {
       "defaults": {
         "model": {
           "primary": "zai/zai_glm-5-turbo"
         }
       }
     }
   }
   

3. Apply config: openclaw config.patch

Fix C: API Key Refresh

1. Get fresh API key from provider
2. Update in openclaw.json:

   {
     "models": {
       "providers": {
         "custom_xxx": {
           "apiKey": "NEW_KEY_HERE"
         }
       }
     }
   }
   

Fix D: Streaming Chunk Validation

Add retry logic to handle incomplete chunks:

• Enable agents.defaults.compaction.reserveTokensFloor: 40000
• Set timeout: agents.defaults.timeoutSeconds: 1800

Step 4: Verify Fix

# Test model response
openclaw sessions.list --limit 1

# Confirm no errors in next 5 minutes
Get-Content "C:\Users\IDL\.openclaw-autoclaw\logs\gateway.log" -Tail 100 | Select-String -Pattern "error" -CaseSensitive:$false

AVAILABLE MODELS (Ranked by Reliability)

Tier 1: Most Reliable

• zai/zai_glm-5-turbo - Fast, stable
• zai/zai_glm-5.1 - Balanced performance
• minimaxai/minimax-m2.7 - Good for complex tasks

Tier 2: Medium Reliability

• qwen/qwen3.5-122b-a10b - Powerful but occasional timeouts
• deepseek-ai/deepseek-v4-pro - Good reasoning, rate limits

Tier 3: Less Reliable

• poolside/laguna-m.1:free - Free but unstable
• openrouter/owl-alpha - Variable performance

COMMON FIXES IN ORDER

1. Gateway Restart -> Fixes 60% of transient errors
2. Model Switch -> Fixes provider-specific issues
3. API Key Refresh -> Fixes auth errors
4. Timeout Increase -> Fixes slow response errors
5. Compaction Adjustments -> Fixes context overflow

RESPONSE TEMPLATE

When model issue detected:

[MODEL ISSUE DETECTED]

Error: [specific error message]
Model: [current model]
Root Cause: [diagnosis]

Fix Applied:
- [action taken]
- Status: [success/fail]

Recommendation: [future prevention tip]

Want me to switch to a more reliable model?
- GLM-5-Turbo (fast/stable)
- GLM-5.1 (balanced)
- MINIMAX M2.7 (complex tasks)

RED LINES

• Never expose API keys in logs/messages
• Always confirm before switching providers
• Don't disable safety checks during troubleshooting
• Preserve user's preferred model if possible

RELATED SKILLS

• gateway config management
• sessions_spawn for isolated testing
• exec for CLI operations