claw-saver

将整个 OpenClaw 环境（~/.openclaw）备份至 Git 仓库。支持定时备份、交互式还原，以及在网络失败时采用指数退避重试策略。

功能特性

• 完整备份：备份 ~/.openclaw 下所有内容，包括 agents、skills、配置文件、知识库（kb）及 agent memory
• 智能排除：仅忽略明确无害的运行时产物（如日志、缓存、node_modules、canvas）
• 定时备份：支持可配置的 cron 调度（默认每 5 小时执行一次）
• 原子化提交：采用双提交策略，确保备份文件与还原指南（RESTORE.md）始终一致
• Git LFS 支持：大型模型文件自动通过 Git LFS 追踪
• 指数退避：推送失败时按 60s → 120s → 240s 延迟重试
• 陈旧锁保护：自动检测并清理已失效的备份进程锁
• 动态 .gitignore：基于实际目录结构扫描生成排除规则，不依赖硬编码假设

快速开始

# 1. 配置 Git 访问令牌
openclaw config set env.OPENCLAW_BACKUP_GIT_TOKEN 

# 2. 设置目标仓库地址
# 编辑 ~/.openclaw/skills/claw-saver/config.json，设置 "repo" 字段
# 示例："repo": "https://cnb.cool/yourname/your-repo"

# 3. 执行首次备份
openclaw backup run

# 4. 启用自动定时备份（每 5 小时一次）
openclaw backup enable-cron

CLI 命令

openclaw backup run            # 立即执行一次备份
openclaw backup status         # 显示最近一次备份时间及对应 commit hash
openclaw backup restore        # 从历史 commit 中交互式还原（interactive）
openclaw backup enable-cron    # 启用定时备份
openclaw backup disable-cron   # 禁用定时备份
openclaw backup set-cron  # 设置自定义调度表达式（例如 "0 */2 * * *"）

配置

编辑 ~/.openclaw/skills/claw-saver/config.json：

{
  "repo": "https://cnb.cool/yourname/your-repo",
  "cron": "0 */5 * * *",
  "lfs_threshold_mb": 10,
  "lfs_extensions": [".bin", ".gguf", ".safetensors", ".pt", ".pth", ".onnx", ".msgpack", ".model"],
  "push_retries": 3,
  "push_retry_interval_ms": 60000
}

备份内容

除明确无害的运行时产物外，全部备份：

# === 已备份内容 ===
agents/              # Agent 配置、认证信息、会话数据
credentials/         # 渠道凭证与密钥
identity/           # 设备身份密钥
kb/                 # 知识库（用户文档 + 向量数据库）
lts/                # 长期脚本（如清理、OOM 防护）
openclaw.json       # 核心配置（含 tokens）
skills/             # 所有已安装 skills 及其配置
workspace-* /       # Agent 工作区、memory、learnings
**/.learnings/      # Agent 自优化日志
**/.openclaw/       # 每个工作区的 OpenClaw 状态
~/.openclaw/ 下所有其他目录

排除内容（仅限运行时产物）

以下内容为临时性或可重建数据，明确不参与备份：

.git/               # Git 仓库本身（仅本地存在）
logs/               # 运行时日志
canvas/             # Canvas 运行时状态
media/             # 已上传的媒体文件
npm/               # NPM 包（可通过 npm install 重建）
cron/runs/         # Cron 执行历史
**/node_modules/   # 依赖包（可通过 npm install / pip install 重建）
**/__pycache__/     # Python 字节码缓存
**/.cache/          # 通用缓存
**/dreaming/        # 短期记忆状态
*.tmp, *.bak        # 系统临时文件
.backup.lock        # 运行时锁文件

用户数据原则：如有疑问，默认备份。凭证（credentials）、身份密钥（identity keys）、知识库（kb）、agent memory 和学习所得数据（learned data）均被完整保留。

安全性

• 令牌隔离：Git 访问令牌仅存储于 ~/.openclaw/.git/config（本地，永不推送到备份仓库）和 cron 环境变量中（仅限本机系统）
• 提交中不含令牌：还原指南（RESTORE.md）与提交信息中仅包含仓库 URL，绝不包含访问令牌
• 屏蔽 stderr 输出：将 git push 的 stderr 重定向，防止错误信息中泄露令牌
• 排除 .git 目录：.git/ 已加入 .gitignore，因此其中包含远程 URL（含令牌）的 .git/config 永远不会被备份

还原操作

openclaw backup restore

该命令会将仓库克隆至临时目录，检出指定 commit，并将文件复制回 ~/.openclaw。运行中的备份进程不受影响（skills/claw-saver 在还原期间持续运行）。

还原完成后，请执行：

openclaw gateway restart

还原指南

每次备份均会在对应 commit 中嵌入一份 RESTORE.md 文件，其中包含：精确的 commit hash、克隆指令，以及本次备份所排除的文件列表，便于您识别哪些内容需手动恢复。

架构设计

skills/claw-saver/
  lib/
    backup.js      # 核心编排逻辑（加锁、暂存、提交、推送）
    git.js         # Git 操作封装（init、add、commit、push、clone）
    lfs.js         # Git LFS 初始化与文件追踪逻辑
    restore.js     # 交互式还原主逻辑
  scripts/
    cli.js         # CLI 入口（run/status/restore/cron 等命令）
  config.json      # 用户配置（仓库地址、cron 表达式、LFS 设置等）

锁机制

通过基于原子化 mkdir 的锁防止并发备份：

• 锁目录路径：~/.openclaw/.backup.lock/（内部含 PID 文件）
• 若检测到陈旧锁（持有者 PID 已不存在），则强制接管
• 无论备份成功或失败，锁均通过 finally{} 块确保释放