Basic Information
| Item | Details |
|---|
| Product Name | OpenClaw Troubleshooting Guide |
| Product Type | Troubleshooting and Problem-Solving Guide |
| Applicable Version | v2026.3.x |
| Support Channels | GitHub Issues, Discord, Stack Overflow, Reddit |
| Relation to OpenClaw | Operations and Diagnostic Reference |
Product Overview
The OpenClaw Troubleshooting Guide compiles diagnostics and solutions for common issues, helping users quickly identify and resolve problems. The guide covers common issues in installation, configuration, runtime, integration, security, and more.
Installation Issues
Node.js Version Incompatibility
| Issue | Solution |
|---|
| Node.js version too low | Upgrade to the minimum required version |
| npm installation failure | Clear cache and retry: npm cache clean --force |
| Dependency conflict | Delete node_modules and reinstall |
| Permission issues | Avoid using sudo for global package installation |
Docker Deployment Issues
| Issue | Solution |
|---|
| Container startup failure | Check port usage and environment variables |
| Insufficient memory | Increase Docker memory limit |
| Network issues | Check Docker network configuration |
| Data persistence | Properly configure volume mounts |
Configuration Issues
LLM Connection
| Issue | Solution |
|---|
| Invalid API key | Verify key format and permissions |
| Connection timeout | Check network and proxy settings |
| Ollama connection failure | Ensure Ollama service is running |
| Model unavailable | Confirm the model is downloaded locally |
Messaging Platform Connection
| Platform | Common Issues | Solution |
|---|
| WhatsApp | QR code scan failure | Regenerate QR code |
| Telegram | Invalid Bot Token | Reacquire via BotFather |
| Discord | Insufficient permissions | Check Bot permission settings |
| Slack | OAuth failure | Reconfigure OAuth app |
Runtime Issues
Performance Issues
| Issue | Diagnosis | Solution |
|---|
| Slow response | Check model latency and network | Use local models or caching |
| Memory leak | Monitor memory usage trends | Regularly restart or update version |
| High CPU usage | Check concurrent agent count | Limit concurrency |
| Insufficient disk space | Check logs and memory files | Clean up old logs and data |
Agent Behavior Anomalies
| Issue | Possible Cause | Solution |
|---|
| Irrelevant output | Improper prompt configuration | Optimize SOUL.md |
| Loop execution | Unclear task definition | Define task boundaries |
| Permission errors | Overly tight permission settings | Adjust allowlist |
| Skill execution failure | Skill compatibility issues | Update or replace skills |
Security Issue Troubleshooting
WebSocket Security
| Issue | Severity | Solution |
|---|
| ClawJacked vulnerability | Critical | Upgrade to 2026.2.23+ |
| Unauthenticated access | High | Configure Gateway authentication |
| Plaintext API keys | High | Use environment variables or key management |
Skill Security
| Issue | Diagnosis | Solution |
|---|
| Malicious skills | Run security audit commands | Remove suspicious skills |
| Prompt injection | Check skill input handling | Enable input validation |
| Credential leakage | Audit skill code | Restrict skill permissions |
Version Upgrade Issues
v2026.3.22 Upgrade Notes
- 13 breaking changes to be aware of
- Check API compatibility of custom skills
- Backup configuration files before upgrading
- Test upgrade in a staging environment first
General Upgrade Process
- Backup current configuration and data
- Read version release notes
- Test upgrade in a staging environment
- Upgrade production environment
- Verify all functionalities are normal
- Prepare rollback plan
Support Channels
| Channel | Applicable Scenarios | Response Time |
|---|
| GitHub Issues | Bug reports | Hours to days |
| Discord | Immediate assistance | Minutes to hours |
| Stack Overflow | General technical questions | Hours to days |
| Reddit r/OpenClaw | Experience discussions | Hours to days |
| Official documentation | Self-help troubleshooting | Immediate |
Sources
External References
Learn more from these authoritative sources: