SOUL 备份技能

对 OpenClaw 工作区的 SOUL 文件（SOUL.md、USER.md、AGENTS.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md）执行带版本控制、校验与回滚能力的备份与恢复。

目的

防止关键工作区配置文件因误删、损坏或错误配置而丢失，支持快速恢复及版本历史追踪。

备份内容

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

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

配置文件备份策略：

• openclaw.json 以脱敏副本形式包含：openclaw.sanitized.json
• 敏感字段（如 token、key、secret、password 等）已被抹除
• 恢复操作仅还原非敏感结构；密钥类信息可在新版工作流中自动补全，或根据需要手动重新填入

使用方法

备份当前 SOUL 文件

# 创建带时间戳的备份
node scripts/backup.mjs

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

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

列出所有备份

# 列出全部备份
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-hunter",
  "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-hunter/soul-backup-skill && node scripts/backup.mjs --name "daily-$(date +%Y-%m-%d)"

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

部署前钩子（Pre-Deployment Hook）

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

校验检查项

validate 脚本执行以下检查：

• 清单完整性（合法 JSON、必需字段存在）
• 文件存在性（清单中列出的所有文件均真实存在）
• 哈希校验（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-hunter

# 克隆备份技能仓库
cd /Users/m1/.openclaw/workspace-hunter
git clone  soul-backup-skill

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

最佳实践

1. 重大变更前务必备份：重构 SOUL 文件前，始终创建命名备份
2. 定期校验：每周运行 validate.mjs，尽早发现损坏
3. 保留 30 天备份：每月清理过期备份
4. 测试恢复流程：每季度演练一次完整恢复过程
5. 记录定制化变更：使用 --desc 参数说明备份创建原因
6. 版本控制：可考虑将备份目录提交至 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）