$ openclaw diagnose --all
openclaw.troubleshoot()
/** Diagnose and fix common OpenClaw issues β community-sourced from GitHub Discussions */
π¨ CRITICAL β Upgrade Impact
β HIGH β Common Blockers
Highπ¦ Installation#ubuntu
Ubuntu Install Fails: systemctl --user & Homebrew
// Root cause: Ubuntu server / root: systemctl --user not available, Homebrew missing
β Fix
Highπ» Platform#windows
Windows QMD: tsx Module Not Found
// Root cause: QMD installed via Bun on Windows 11 β tsx module resolution failure
β Fix
Highπ€ API / Providers#api
API Rate Limit 429 Error
// Root cause: Provider RPM/TPM limit hit β OpenAI, Anthropic, Gemini all affected
β Fix
Highπ Connectivity#telegram
Telegram Group Sessions Reset on Restart
// Root cause: Gateway restart re-creates sessions instead of restoring from sessions.json
β Fix
Highπ Permissions#raspberrypi
Raspberry Pi 5: No File Read/Write Permissions
// Root cause: Raspberry Pi OS: no read/write/exec after fresh install β tools.profile
β Fix
Highπ Connectivity#whatsapp
WhatsApp Session Keeps Dying
// Root cause: QR code session expires / Baileys auth file corrupted
β Fix
β MEDIUM β Annoying But Fixable
Mediumπ» Platform#windows
Control UI Tools Toggles Not Saving (Windows)
// Root cause: Windows: Control UI tool toggles revert on refresh β v2026.3.2 regression
β Fix
Mediumπ¦ Installation#linux
Homebrew Not Installed on Linux β Skill Fails
// Root cause: Skill installer requires Homebrew for github/summarize skills on Linux
β Fix
Mediumπ Connectivity#streaming
Streaming Text Gets Concatenated Between Turns
// Root cause: deltaBuffer missing cross-turn separator merges text across agent turns
β Fix
Mediumπ Permissions#permissions
screen_record Blocked by Sandbox
// Root cause: screen_record blocked by sandbox policy; system.which fails in restricted profile
β Fix
Mediumβ‘ Performance#ollama
Ollama: Model Not Found on Cold Start
// Root cause: Ollama cold-start timeout too short β model loads after response returns
β Fix
Mediumβ‘ Performance#performance
Ollama Too Slow
// Root cause: Running on CPU only, wrong context length, wrong quantization
β Fix
Mediumβ‘ Performance#performance
High Memory Usage
// Root cause: Model loaded fully in RAM, large context window, no swap
β Fix
Mediumπ Connectivity#telegram
Telegram Skill Commands Show _2, _3 Duplicates
// Root cause: Telegram skill commands registered multiple times under _2, _3 suffixes
β Fix
Mediumπ Connectivity#discord
Heartbeat Messages Leaking to Discord DMs
// Root cause: Heartbeat delivery default changed in v2026.2.24-beta β leaks to Discord DMs
β Fix
Mediumπ» Platform#macos
Mac Mini: Gateway Not Auto-Starting After Reboot
// Root cause: launchd plist missing or not loaded β gateway not auto-starting on Mac
β Fix
Mediumπ¦ Installation#docker
Docker Port Conflict
// Root cause: Another process or old container is holding the port
β Fix
β LOW β Config & Setup Questions