一、安装阶段报错
1.1 npm install 卡死、超时、网络错误
根因：官方源国内访问慢、丢包
解决方案：切换淘宝镜像源，清理缓存后重装
npm cache clean -f
npm config set registry https://registry.npmmirror.com/1.2 Node version not match 版本不匹配
根因：Node 版本低于20.x，环境不兼容
解决方案：升级至 Node.js 20+ LTS 稳定版，重启终端
1.3 权限不足、permission denied
根因：系统目录无写入权限
解决方案：Linux/Mac 使用 sudo 执行，Windows 使用管理员终端
二、启动阶段报错
2.1 端口被占用、listen EADDRINUSE
根因：8090 端口被其他程序占用
解决方案：杀掉占用端口进程 或 修改 OpenClaw 运行端口
2.2 启动成功但网页打不开
根因：防火墙拦截、本地监听地址异常
解决方案：关闭防火墙放行端口、检查监听地址为 0.0.0.0
2.3 后台启动后自动闪退
根因：内存不足、依赖缺失、配置文件损坏
解决方案：查看运行日志，修复损坏配置，重启系统环境
三、运行任务报错
3.1 任务执行失败、脚本报错
解决方案：优先查看单条任务日志，99% 错误信息会直接打印在日志中，精准定位代码问题。
3.2 定时任务不触发
常见原因：工作流未启用、Cron表达式错误、服务未正常运行
排查步骤：检查服务状态 → 核对定时表达式 → 确认工作流开启状态
3.3 并发任务卡死、堆积
解决方案：开启任务限流、优化单任务执行耗时、重启服务释放僵死进程
四、升级与卸载异常
4.1 升级失败、文件占用
先停止服务，再执行升级命令，避免文件被占用无法覆盖更新。
4.2 卸载不干净、残留配置
手动删除全局安装目录与本地数据目录，彻底清除残留配置，解决重装冲突问题。