#OpenClaw Troubleshooting Guides

This directory contains practical troubleshooting guides for common OpenClaw runtime issues. Each guide is organized by symptom rather than module, making it easier to diagnose problems based on what you observe.

#Available Guides

#WebSocket Connection Failures

Diagnose and resolve WebSocket connection issues including immediate disconnects, handshake timeouts, and premature closures. Based on the gateway server connection handling logic.

Common symptoms:

• Client disconnects immediately after connecting
• "handshake timeout" errors in logs
• "closed before connect" warnings

#Compaction/Summarization Failures

Troubleshoot conversation summarization issues when agent conversations grow too large. Covers the progressive fallback system and context window handling.

Common symptoms:

• "Full summarization failed" errors
• Context window exceeded messages
• Agent stops responding with long conversations

#Session Transcript Corruption

Fix corrupted session transcripts with orphaned or duplicate tool results. Explains the automatic repair system and how to diagnose tool_use pairing issues.

Common symptoms:

• "unexpected tool_use_id found" API errors
• Agent stops responding after tool calls
• Duplicate tool results in transcript

#Embeddings Provider Failures

Resolve memory search issues caused by embedding provider failures. Covers the fallback chain and graceful degradation to FTS-only mode.

Common symptoms:

• "No API key found for provider" errors
• Memory search returns only text matches
• Missing vector search results

#Config Validation Errors

Debug configuration validation failures that prevent OpenClaw from starting. Includes plugin config schema mismatches and duplicate agent directory issues.

Common symptoms:

• OpenClaw fails to start
• Zod schema validation errors
• Plugin config mismatch warnings

#Guide Structure

Each guide follows a consistent structure:

1. Symptoms: Observable behaviors and error messages
2. Root Causes: Technical reasons from source code
3. Recovery Mechanisms: Automatic and manual recovery steps
4. Diagnosis Steps: Practical debugging workflow
5. Flowcharts: Visual representations of recovery logic

#Related Documentation

• Architecture Overview: System design and component interactions
• Agent System (planned): Agent lifecycle and communication patterns
• Configuration Reference: Configuration schema and options