🔄 OpenClaw Auto Rollback

智能自动备份与自动回滚工具，专为 OpenClaw 设计。特别适用于黑盒子服务器（无显示器）和出差场景，提供出行模式自动守护功能。

基于 OpenClaw Config Guardian 的核心备份/回滚能力，增加了智能健康监测和自动恢复功能。

✨ 核心功能

| 功能 | 说明 | |------|------| | 🔄 自动备份 | 定时自动备份 OpenClaw 配置文件 | | ✈️ 出行模式 | 专为无人值守场景设计，自动监测 + 自动回滚 | | 🏥 健康检测 | 深度检测 Gateway 状态（进程 + API） | | 🚨 自动回滚 | Gateway 异常时自动回滚到最后已知良好配置 | | 🌐 Web UI | 图形化界面管理备份和出行模式 | | ⚡ 一键回滚 | 手动快速恢复到任意备份点 | | 🧹 自动清理 | 自动保留最近 N 个备份，删除旧备份 |

🚀 快速安装

npm install -g openclaw-auto-rollback

安装后自动创建默认配置和备份目录。

📖 使用方式

命令行 (CLI)

全局安装后，使用 oar 简写命令：

# 查看 Gateway 状态和出行模式信息
oar status

# 立即创建备份
oar backup

# 列出所有备份
oar list

# 回滚到指定备份
oar restore backup-2024-01-15T08-30-00-000Z

# 删除指定备份
oar delete backup-2024-01-15T08-30-00-000Z

# 启动 Web UI
oar webui

# 查看/修改配置
oar config

✈️ 出行模式 (Travel Mode)

专为黑盒子服务器或出差场景设计：

# 开启出行模式
oar travel-mode on

# 设置检查间隔：10分钟 / 2小时 / 8小时
oar travel-interval 120

# 启动守护进程（后台运行）
oar daemon

# 手动触发一次出行模式检测
# （在 Web UI 中操作或调用 API）

出行模式工作原理：

1. 定时检测 → 按设定间隔检查 Gateway 健康状态
2. 正常时备份 → Gateway 健康 → 自动创建备份，标记为 "known-good"
3. 异常时回滚 → Gateway 异常 → 自动回滚到最后 "known-good" 备份
4. 自动恢复 → 回滚后 Gateway 重新启动，服务恢复

Web UI

oar webui

访问 http://localhost:3738

Web UI 提供：

• 📊 实时 Gateway 健康状态
• ✈️ 出行模式开关和配置
• 📦 备份列表管理（创建/回滚/删除）
• ⚙️ 自动备份设置

⚙️ 配置

配置文件位置：~/.openclaw/extensions/openclaw-auto-rollback/config.json

{
  "autoBackup": true,
  "maxBackups": 10,
  "webUIPort": 3738,
  "backupItems": [],
  "travelMode": false,
  "travelModeInterval": 120,
  "travelModeMaxBackups": 20
}

| 配置项 | 说明 | 默认值 | |--------|------|--------| | autoBackup | 启用普通定时备份 | true | | maxBackups | 普通备份最大保留数 | 10 | | webUIPort | Web UI 端口 | 3738 | | backupItems | 自定义备份项（空数组=自动扫描） | [] | | travelMode | 启用出行模式 | false | | travelModeInterval | 出行模式检查间隔（分钟） | 120 | | travelModeMaxBackups | 出行模式最大备份数 | 20 |

检查间隔选项

| 间隔 | 适用场景 | |------|----------| | 10 分钟 | 高频监控，重要生产环境 | | 2 小时 | 推荐，平衡检测频率和资源消耗 | | 8 小时 | 低频监控，开发/测试环境 |

🔒 安全机制

• 回滚前紧急备份: 每次回滚前自动创建当前配置快照
• 关键配置验证: 回滚后验证 openclaw.json 有效性
• 安全覆盖: 只覆盖备份中的文件，不删除现有文件
• 连续失败保护: 记录连续失败次数，避免频繁回滚
• 备份标记: 出行模式备份标记 Gateway 健康状态

📁 备份内容

自动扫描并备份以下文件类型：

• .md - Markdown 配置文件
• .json - JSON 配置文件
• .yaml / .yml - YAML 配置文件
• .toml - TOML 配置文件
• .ini / .conf / .config - 其他配置文件

🔌 API 接口

Web UI 提供 REST API：

| 接口 | 方法 | 说明 | |------|------|------| | /api/config | GET/POST | 获取/更新配置 | | /api/backups | GET | 获取备份列表 | | /api/backup | POST | 立即执行备份 | | /api/restore | POST | 回滚到指定备份 | | /api/status | GET | 获取 Gateway 深度健康状态 | | /api/last-good-backup | GET | 获取最后已知良好备份 | | /api/travel-mode/check | POST | 手动触发出行模式检测 |

🏗️ 技术架构

openclaw-auto-rollback/
├── src/
│   ├── core.ts      # 核心引擎（备份/回滚/健康检测）
│   ├── daemon.ts    # 守护进程（定时任务 + 出行模式）
│   ├── webui.ts     # Web 服务（Express + API）
│   ├── cli.ts       # 命令行接口
│   └── index.ts     # 模块导出
├── webui/
│   └── index.html   # 可视化仪表盘
├── bin/
│   └── cli.js       # CLI 入口
└── skills/
    └── auto-rollback/
        └── SKILL.md # OpenClaw 技能定义

📝 与 Config Guardian 的区别

| 特性 | Config Guardian | Auto Rollback | |------|----------------|---------------| | 核心功能 | 定时备份 + 手动回滚 | 智能监测 + 自动回滚 | | 出行模式 | ❌ 不支持 | ✅ 核心功能 | | 自动回滚 | ❌ 不支持 | ✅ Gateway 异常时自动回滚 | | 健康检测 | 基础进程检测 | 深度检测（进程 + API） | | Web UI 端口 | 3737 | 3738 | | CLI 命令 | ocg | oar | | 适用场景 | 日常手动管理 | 无人值守/出差/黑盒子 |

🤝 依赖

• Node.js >= 18.0.0
• express ^4.18.2
• node-cron ^3.0.3

📄 License

MIT

📋 更新日志

v1.0.6 (2026-06-11)

• 修复: 出行模式检测结果不刷新
  • 修复点击"立即检测"后 UI 仍显示旧结果（"异常"）的问题
  • 后端 /api/travel-mode/check 接口现在正确保存 lastCheckTime 和 lastCheckResult
• 修复: Windows 路径分隔符导致排除逻辑异常
  • shouldExclude 函数统一处理 \ 和 / 路径分隔符，确保 Windows 下排除规则正确生效
• 优化: Web UI 显示自动备份时间
  • 在"自动备份设置"卡片显示"下次自动备份：每天凌晨 2:00"

v1.0.5 (2026-06-11)

• 修复: Windows 健康检测逻辑优化
  • 端口检测优先: 重写健康检测逻辑，端口通了直接认为 Gateway 健康（最可靠）
  • 修复进程名检测: Windows 下 Gateway 可能是 node.exe 运行，原逻辑总是检测失败
  • 双方法端口检测: Windows 先用 Test-NetConnection，失败再用 TcpClient
  • 同时兼容 Windows / Linux / macOS

v1.0.4 (2026-06-11)

• 修复: Windows 健康检测机制
  • 修复 Web UI 在 Windows 下错误显示 Gateway 已停止的问题
  • 进程检测：Windows 使用 tasklist 代替 pgrep（Linux 命令）
  • 端口检测：Windows 使用 PowerShell TcpClient 代替 curl
  • CLI 检测：Windows 下自动隐藏命令行窗口 (windowsHide: true)
  • 完全跨平台支持：Windows / Linux / macOS

v1.0.3 (2026-06-11)

• 修复: Windows 路径兼容性问题
  • 修复 oar webui 在 Windows PowerShell 下启动失败的问题
  • 使用 pathToFileURL 转换 ESM 导入路径，支持 Windows 绝对路径 (C:\...)
  • 修复守护进程启动时的路径转换问题

v1.0.2 (2026-06-09)

• 普通备份每天凌晨2点执行
• 备份目录分离（regular/travel-mode）
• 各自独立数量限制

v1.0.1 (2026-06-09)

• 守护进程自动启动
• HTTP 深度健康检测（能识别 token 被改导致的 401/403）

v1.0.0 (2026-06-09)

• 初始版本，基于 Config Guardian 1.0.16
• 新增出行模式

🔗 相关项目

• OpenClaw Config Guardian - 基础备份回滚工具