From 10c354ff9a3c64565873bc5c6c5a649c02369f2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eason=20=28=E9=99=88=E5=8C=BB=E7=94=9F=29?=
 <eason@openclaw.ai>
Date: Fri, 20 Feb 2026 10:24:38 +0000
Subject: [PATCH] Add rollback guide for configuration recovery

---
 rollback_guide.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 rollback_guide.md

diff --git a/rollback_guide.md b/rollback_guide.md
new file mode 100644
index 0000000..8cf2069
--- /dev/null
+++ b/rollback_guide.md
@@ -0,0 +1,173 @@
+# OpenClaw Agent 回滚恢复指南
+
+## 🚨 **紧急情况：当 Agent 失去功能时**
+
+本文档提供了完整的回滚和恢复流程，确保在配置错误或系统崩溃时能够快速恢复服务。
+
+## 🔧 **回滚操作步骤**
+
+### 1. **确认当前问题**
+```bash
+# 检查 OpenClaw 状态
+openclaw status
+
+# 检查系统日志
+journalctl --user -u openclaw-gateway --no-pager -n 50
+
+# 检查工作区状态
+cd /root/.openclaw/workspace
+git status
+```
+
+### 2. **查看 Git 历史记录**
+```bash
+# 查看最近的提交历史
+git log --oneline -10
+
+# 查看特定文件的修改历史
+git log --oneline <filename>
+
+# 查看两次提交之间的差异
+git diff HEAD~1 HEAD
+```
+
+### 3. **执行回滚操作**
+
+#### **方案 A: 回滚到上一个稳定版本（推荐）**
+```bash
+# 回滚到最后一个已知良好的提交
+git reset --hard HEAD~1
+
+# 如果需要回滚多个版本，先查看日志找到正确的 commit hash
+git log --oneline -5
+git reset --hard <commit-hash>
+
+# 重新加载 Systemd 配置
+systemctl --user daemon-reload
+
+# 重启 OpenClaw 服务
+openclaw gateway restart
+```
+
+#### **方案 B: 仅恢复特定配置文件**
+```bash
+# 恢复单个文件到上一版本
+git checkout HEAD~1 -- <filename>
+
+# 恢复多个文件
+git checkout HEAD~1 -- MEMORY.md AGENTS.md CORE_INDEX.md
+
+# 提交恢复操作（可选）
+git add .
+git commit -m "Rollback: restore configuration after error"
+```
+
+#### **方案 C: 完全重置到远程仓库状态**
+```bash
+# 如果本地修改完全混乱，直接重置到远程最新状态
+git fetch origin
+git reset --hard origin/master
+
+# 重新部署所有配置
+systemctl --user daemon-reload
+openclaw gateway restart
+```
+
+### 4. **验证恢复结果**
+```bash
+# 检查服务状态
+openclaw status
+
+# 测试基本功能
+openclaw health --json
+
+# 验证配置文件完整性
+ls -la ~/.openclaw/workspace/
+```
+
+## 📋 **关键文件备份策略**
+
+### **核心配置文件清单**
+- `MEMORY.md` - 长期记忆和重要决策
+- `CORE_INDEX.md` - 记忆索引和身份信息  
+- `AGENTS.md` - 工作区约定和操作指南
+- `~/.openclaw/openclaw.json` - OpenClaw 主配置文件
+- `agent-monitor.js` - 监控脚本
+- `start-agent-monitor.sh` - 监控启动脚本
+
+### **Systemd 服务文件**
+- `~/.config/systemd/user/openclaw-gateway.service`
+
+### **Git 仓库位置**
+- **本地**: `/root/.openclaw/workspace/`
+- **远程**: `git@gl.tigerone.tech:sw_dm/openClaw_agent_dm.git`
+
+## ⚠️ **重要注意事项**
+
+### **回滚前必做**
+1. **记录当前状态**: `git status` 和 `git log --oneline -3`
+2. **备份当前配置**: 如果可能，手动复制关键文件
+3. **通知相关人员**: 如果是生产环境，通知团队成员
+
+### **回滚后必做**
+1. **验证功能**: 确保所有服务正常运行
+2. **记录原因**: 在新的 commit 中说明回滚原因
+3. **分析根本原因**: 找出导致问题的配置变更
+4. **更新文档**: 如果发现文档不足，及时补充
+
+### **避免常见错误**
+- ❌ 不要直接编辑生产配置而不 commit
+- ❌ 不要在回滚前强制推送 (`git push --force`)
+- ❌ 不要删除 Git 历史记录
+- ✅ 始终先在测试环境中验证配置变更
+
+## 🔍 **故障诊断辅助**
+
+### **常见问题症状及解决方案**
+
+#### **症状: OpenClaw 无法启动**
+- **可能原因**: 配置文件语法错误
+- **解决方案**: 回滚 `~/.openclaw/openclaw.json` 到上一版本
+
+#### **症状: 记忆功能失效**  
+- **可能原因**: CORE_INDEX.md 或 MEMORY.md 损坏
+- **解决方案**: 回滚相关记忆文件
+
+#### **症状: 监控通知停止**
+- **可能原因**: agent-monitor.js 脚本错误
+- **解决方案**: 回滚监控脚本并重启服务
+
+#### **症状: Git 无法推送**
+- **可能原因**: SSH 密钥或网络配置问题  
+- **解决方案**: 检查 `/root/.ssh/config` 和网络连接
+
+## 🔄 **自动化回滚脚本（可选）**
+
+创建快速回滚脚本 `/root/.openclaw/workspace/quick-rollback.sh`:
+
+```bash
+#!/bin/bash
+echo "⚠️  Starting emergency rollback..."
+cd /root/.openclaw/workspace
+
+# 回滚到最后一个提交
+git reset --hard HEAD~1
+
+# 重启服务
+systemctl --user daemon-reload
+openclaw gateway restart
+
+echo "✅ Rollback completed. Check service status with 'openclaw status'"
+```
+
+## 📞 **紧急联系人**
+
+- **Gitea 仓库**: https://gl.tigerone.tech/sw_dm/openClaw_agent_dm.git
+- **SSH 访问**: 使用已配置的 SSH 密钥
+- **文档维护者**: Eason (陈医生) - AI Agent 架构师
+
+---
+
+**最后更新**: 2026-02-20  
+**适用版本**: OpenClaw 2026.2.19+  
+**维护策略**: 此文档会随每次重大架构变更自动更新
\ No newline at end of file