OpenClaw 备份与恢复

对 OpenClaw 工作区状态（包括 SOUL.md、USER.md、AGENTS.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md、各 agent 的 Markdown 文件，以及可选的真实 openclaw.json）执行备份、恢复、校验及 GitHub 同步操作，支持版本管理、回滚与离机恢复。

用途

防止关键工作区配置文件被意外删除、损坏或错误配置；支持快速恢复与版本历史追踪。

备份内容

工作区根目录下的核心 SOUL 文件：

• SOUL.md — agent 的人格设定与使命
• USER.md — 用户档案与偏好设置
• AGENTS.md — agent 指令与工作流
• IDENTITY.md — agent 身份配置
• TOOLS.md — 本地工具配置
• HEARTBEAT.md — 周期性任务配置
• BOOTSTRAP.md — 初始化指令

使用方法

备份当前工作区状态

# 创建带时间戳的备份（含脱敏处理的 openclaw.json）
node scripts/backup.mjs

# 创建命名备份
node scripts/backup.mjs --name "pre-migration"

# 带描述的备份
node scripts/backup.mjs --desc "Before major refactor"

# 在备份集中包含真实的 ~/.openclaw/openclaw.json
node scripts/backup.mjs --raw-openclaw-config

每日 GitHub 备份

# 创建备份、执行 git add backups/、git commit 并推送到 origin/当前分支
node scripts/backup-and-push.mjs --remote origin

# 推送至专用备份远程仓库
node scripts/backup-and-push.mjs --remote clawlite-backup

# 仅推送脱敏配置备份（不包含真实配置）
node scripts/backup-and-push.mjs --remote origin --sanitized-config-only

backup-and-push.mjs 已自动完成完整 Git 同步流程：

• git add backups
• git commit -m "backup: ..."
• git push

如需无人值守运行，请使用内置的 GitHub Actions 工作流 .github/workflows/daily-backup.yml，或通过 cron / launchd 调用相同脚本。

列出所有备份

# 列出全部备份
node scripts/list.mjs

# 显示详细信息
node scripts/list.mjs --verbose

从备份中恢复

# 恢复最新备份
node scripts/restore.mjs

# 按时间戳恢复特定备份
node scripts/restore.mjs --timestamp 2026-03-05T00-51-30

# 按名称恢复特定备份
node scripts/restore.mjs --name "pre-migration"

# 预演模式（仅预览，不实际应用）
node scripts/restore.mjs --dry-run

校验备份完整性

# 校验全部备份
node scripts/validate.mjs

# 校验特定备份
node scripts/validate.mjs --timestamp 2026-03-05T00-51-30

备份结构

backups/
├── 2026-03-05T00-51-30/
│   ├── manifest.json          # 备份元数据
│   ├── SOUL.md
│   ├── USER.md
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── TOOLS.md
│   ├── HEARTBEAT.md
│   └── BOOTSTRAP.md
├── 2026-03-05T01-15-42/
│   └── ...
└── named/
    ├── pre-migration/
    │   └── ...
    └── stable-v1/
        └── ...

Manifest 格式

每个备份均包含一个 manifest.json：

{
  "timestamp": "2026-03-05T00:51:30.123Z",
  "name": "pre-migration",
  "description": "Before major refactor",
  "workspace": "/Users/m1/.openclaw/workspace-YOUR-AGENT",
  "files": {
    "SOUL.md": {
      "size": 1234,
      "hash": "sha256:abc123...",
      "exists": true
    },
    "USER.md": {
      "size": 567,
      "hash": "sha256:def456...",
      "exists": true
    }
  },
  "created_by": "hunter",
  "openclaw_version": "1.0.0"
}

恢复工作流

标准恢复流程

1. 列出可用备份：node scripts/list.mjs
2. 预览恢复效果：node scripts/restore.mjs --timestamp --dry-run
3. 执行恢复：node scripts/restore.mjs --timestamp
4. 验证：手动检查工作区文件

紧急恢复

若工作区已损坏且脚本无法运行：

# 手动从备份目录恢复
cd /Users/m1/.openclaw/workspace-hunter
cp -r soul-backup-skill/backups/LATEST_TIMESTAMP/* .

错误恢复后的回滚

每次恢复操作均会自动生成前置恢复备份：

# 恢复操作将创建：backups/pre-restore-2026-03-05T01-20-00/
# 回滚命令如下：
node scripts/restore.mjs --timestamp pre-restore-2026-03-05T01-20-00

自动化

Cron 调度（推荐）

添加到 OpenClaw heartbeat 或系统 cron 中：

# 每日凌晨 2 点执行备份
0 2 * * * cd /Users/m1/.openclaw/workspace-YOUR-AGENT/openclaw-backup-restore && node scripts/backup.mjs --name "daily-$(date +%Y-%m-%d)"

# 每周日早上 3 点执行备份
0 3 * * 0 cd /Users/m1/.openclaw/workspace-YOUR-AGENT/openclaw-backup-restore && node scripts/backup.mjs --name "weekly-$(date +%Y-W%V)"

部署前钩子

# 部署变更前执行
cd /Users/m1/.openclaw/workspace-hunter/soul-backup-skill
node scripts/backup.mjs --name "pre-deploy-$(git rev-parse --short HEAD)"

校验检查项

校验脚本执行以下检查：

• Manifest 完整性（合法 JSON、必需字段存在）
• 文件存在性（manifest 中列出的所有文件均存在）
• 哈希校验（SHA-256 校验和匹配）
• 工作区路径一致性
• 时间戳格式合法性

故障场景与恢复方案

场景 1：误删 SOUL.md

# 立即恢复
node scripts/restore.mjs --file SOUL.md

# 或执行全量恢复
node scripts/restore.mjs

场景 2：错误的配置变更

# 预览即将恢复的内容
node scripts/restore.mjs --dry-run

# 恢复上一版本
node scripts/restore.mjs --timestamp 

场景 3：备份损坏

# 校验全部备份
node scripts/validate.mjs

# 查找最近有效的备份
node scripts/list.mjs --verbose

# 从最近有效备份恢复
node scripts/restore.mjs --timestamp 

场景 4：工作区完全丢失

# 重建工作区目录
mkdir -p /Users/m1/.openclaw/workspace-YOUR-AGENT

# 克隆备份技能
cd /Users/m1/.openclaw/workspace-YOUR-AGENT
git clone  openclaw-backup-restore

# 恢复最新备份
cd openclaw-backup-restore
node scripts/restore.mjs

最佳实践

1. 重大变更前务必备份：重构 SOUL 文件前，始终创建命名备份
2. 定期校验：每周运行 validate.mjs，尽早发现损坏
3. 保留 30 天备份：每月清理过期备份
4. 测试恢复流程：每季度演练一次恢复操作
5. 记录自定义变更：使用 --desc 参数说明备份创建原因
6. 版本控制：建议将 backup 目录提交至 Git，实现离机冗余

安全须知

• 备份内容包含敏感配置（如 TOOLS.md 中的 API 密钥、USER.md 中的用户信息）
• 备份目录权限应与工作区保持一致
• 切勿将备份提交至公开仓库
• 若工作区包含密钥等敏感信息，建议加密备份目录

依赖项

• Node.js 18+
• 无需外部 npm 包（仅使用内置模块：crypto、fs、path）

故障排查

“未找到备份目录”

• 在技能目录中执行：mkdir -p backups

“权限被拒绝”

• 检查工作区目录权限：ls -la ..
• 确保备份脚本具有执行权限：chmod +x scripts/*.mjs

“校验时哈希不匹配”

• 文件在备份创建后被修改过
• 该备份可能已损坏——请改用更早的备份

“恢复失败：文件冲突”

• 使用 --force 参数强制覆盖现有文件
• 或在恢复前手动移走冲突文件

未来增强功能

• 压缩支持（使用 gzip 压缩备份以节省空间）
• 远程备份同步（支持 S3、Dropbox、rsync）
• 差分备份（仅备份变更文件）
• 备份保留策略（自动清理旧备份）
• 加密备份（支持 GPG 加密）
• Web UI（用于备份管理）
• Slack/Telegram 通知（备份/恢复事件提醒）