openClaw_agent_dm/rollback_guide.md

# 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+  
**维护策略**: 此文档会随每次重大架构变更自动更新