$ openclaw diagnose --all
openclaw.troubleshoot()
/** 诊断并修复常见 OpenClaw 问题 — 来自 GitHub Discussions 的社区资源 */
🚨 CRITICAL — Upgrade Impact
⚠ HIGH — Common Blockers
High📦 Installation#ubuntu
Ubuntu 安装失败:systemctl --user 与 Homebrew
// Root cause: Ubuntu server / root: systemctl --user not available, Homebrew missing
→ Fix
High💻 Platform#windows
Windows QMD:tsx 模块找不到
// Root cause: QMD installed via Bun on Windows 11 — tsx module resolution failure
→ Fix
High🤖 API / Providers#api
API 限流 429 错误
// Root cause: Provider RPM/TPM limit hit — OpenAI, Anthropic, Gemini all affected
→ Fix
High🔗 Connectivity#telegram
重启后 Telegram 群组会话重置
// Root cause: Gateway restart re-creates sessions instead of restoring from sessions.json
→ Fix
High🔒 Permissions#树莓派
树莓派 5:无法读写文件
// Root cause: Raspberry Pi OS: no read/write/exec after fresh install — tools.profile
→ Fix
High🔗 Connectivity#whatsapp
WhatsApp 会话不断断开
// Root cause: QR code session expires / Baileys auth file corrupted
→ Fix
● MEDIUM — Annoying But Fixable
Medium💻 Platform#windows
控制 UI 工具开关不保存(Windows)
// Root cause: Windows: Control UI tool toggles revert on refresh — v2026.3.2 regression
→ Fix
Medium📦 Installation#linux
Linux 上未安装 Homebrew — 技能安装失败
// Root cause: Skill installer requires Homebrew for github/summarize skills on Linux
→ Fix
Medium🔗 Connectivity#流式传输
流式传输文本在轮次间被合并
// Root cause: deltaBuffer missing cross-turn separator merges text across agent turns
→ Fix
Medium🔒 Permissions#权限
screen_record 被沙箱阻止
// Root cause: screen_record blocked by sandbox policy; system.which fails in restricted profile
→ Fix
Medium⚡ Performance#ollama
Ollama:冷启动时'模型未找到'
// Root cause: Ollama cold-start timeout too short — model loads after response returns
→ Fix
Medium⚡ Performance#性能
Ollama 速度太慢
// Root cause: Running on CPU only, wrong context length, wrong quantization
→ Fix
Medium⚡ Performance#性能
内存使用率过高
// Root cause: Model loaded fully in RAM, large context window, no swap
→ Fix
Medium🔗 Connectivity#telegram
Telegram 技能命令出现 _2、_3 重复
// Root cause: Telegram skill commands registered multiple times under _2, _3 suffixes
→ Fix
Medium🔗 Connectivity#discord
心跳消息泄露到 Discord 私信
// Root cause: Heartbeat delivery default changed in v2026.2.24-beta — leaks to Discord DMs
→ Fix
Medium💻 Platform#macos
Mac Mini:重启后网关不自动启动
// Root cause: launchd plist missing or not loaded — gateway not auto-starting on Mac
→ Fix
Medium📦 Installation#docker
Docker 端口冲突
// Root cause: Another process or old container is holding the port
→ Fix
○ LOW — Config & Setup Questions