夜雨聆风1. 环境背景
部署方式：systemd user 服务 安装用户：root 安装路径：/root/.local/share/pnpm/openclaw 配置目录：/root/.openclaw/ 服务文件：/root/.config/systemd/user/openclaw-gateway.service 日志路径：/tmp/openclaw/openclaw-YYYY-MM-DD.log 运行端口：36204 硬件规格：低配云主机（1 核 / 2G 内存配置）
2. 故障时间线
时间 | 事件 | 关键现象 |
|---|---|---|
7/27 晚间 | 执行升级 | pnpm add -g openclaw@latest + openclaw gateway install --force + systemd restart |
数分钟后 | 服务异常 | 消息无响应，服务状态activating (auto-restart) |
7/27 深夜 | 进程增殖 | ps aux显示 openclaw 进程持续增加，出现 7+ 实例 |
7/28 白天 | 排查权限受限 | 使用ubuntu普通用户排障，无法访问/root/.openclaw/日志与锁文件 |
7/28 晚间 | 切换 root 后定位插件问题 | 日志：Plugin "openclaw-lark" failed post-core payload smoke check；dist/index.js缺失 |
7/28 晚间 | 处理重复插件 | 日志：duplicate plugin id；npm 全局与 extensions 目录各有一份插件 |
7/28 深夜~7/29 凌晨 | 彻底恢复 | 清理插件、锁文件、systemd 服务文件后重新部署，服务稳定运行 |
3. 根因分析
3.1 根因一：插件未编译即上线
3.2 根因二：systemd auto-restart 与手动启动冲突
3.3 根因三：迁移锁未释放
3.4 根因四：重复插件 ID
3.5 根因五：排障用户权限错误
4. 故障处理关键命令
4.1 止血操作
rm -f /root/.openclaw/*.lock
rm -f /root/.openclaw/agents/main/*.lock
rm -f /root/.openclaw/agents/main/agent/*.lock
4.2 卸载问题插件
4.3 重新部署 systemd 服务
5. 升级 SOP 建议
5.1 升级前检查清单
备份配置目录、systemd 服务文件、插件列表 记录当前插件清单：openclaw plugins list --json 确认环境变量：
5.2 升级执行流程
停止服务：systemctl --user stop openclaw-gateway.service 升级本体：pnpm add -g openclaw@latest 前台验证：openclaw gateway --port 36204（观察 30~60 秒） 重新安装 systemd：openclaw gateway install --force 启动并检查：systemctl --user start + systemctl --user status
5.3 插件安装红线
安装前必须确认存在dist/index.js或dist/index.mjs或dist/index.cjs 同一插件不得同时存在于 npm 全局和 extensions 目录 安装后必须前台启动验证，再挂 systemd
5.4 升级后检查清单
☐ 服务active (running)稳定超过 5 分钟 ☐ openclaw doctor无 Config / Doctor warnings ☐ 插件列表无重复、无缺失 main entry ☐ 主频道收发正常 ☐ 内存稳定在 200M~500M ☐ 迁移锁和孤儿会话文件已清理 ☐ 敏感配置已迁移至 SecretRefs ☐ 配置文件权限chmod 600
6. 经验教训
升级是生产操作：必须遵循备份、验证、回滚流程。 前台验证先于 systemd：直接用 systemd 启动会隐藏启动日志并放大故障影响。 低配主机必须设置OPENCLAW_NO_RESPAWN=1：避免 restart 时进程 fork 失控。 插件管理必须单一来源：npm 全局与 extensions 目录不能混用。 维护操作必须使用安装用户权限：root 安装的程序必须用 root 排障。
7. 后续优化
将本次 SOP 纳入标准运维文档 定期巡检openclaw doctor输出 建立监控告警：gateway 服务状态、内存占用、进程数量 关键配置迁移至 SecretRefs，避免明文存储