scripts/PERSISTENCE_README.md

OpenClaw 持久化存储配置指南

概述

本配置实现了 OpenClaw 在 Hugging Face Space 中的完整持久化存储，确保容器重启后所有状态都能恢复。

核心特性

• 完整目录备份: 持久化整个 ~/.openclaw 目录
• 原子操作: 使用 tar.gz 归档确保备份一致性
• 自动轮转: 保留最近 5 个备份，自动清理旧备份
• 优雅关闭: 容器停止时自动执行最终备份

---

持久化的目录和文件

1. 核心配置

~/.openclaw/
├── openclaw.json              # 主配置文件（模型、插件、网关设置）
└── credentials/               # 所有渠道的登录凭证
    ├── whatsapp/
    │   └── default/
    │       └── auth_info_multi.json
    └── telegram/
        └── session.data

2. 工作空间

~/.openclaw/workspace/
├── AGENTS.md                 # 代理定义
├── SOUL.md                   # 灵魂（性格、说话风格）
├── TOOLS.md                  # 可用工具列表
├── MEMORY.md                 # 长期聚合记忆
├── memory/                   # 每日记忆文件
│   ├── 2025-01-15.md
│   └── 2025-01-16.md
└── skills/                   # 技能定义
    ├── my-skill/
    │   └── SKILL.md
    └── ...

3. 会话历史

~/.openclaw/agents/<agentId>/sessions/
├── <sessionId>.jsonl          # 每个会话的完整对话历史
└── sessions.json             # 会话索引

4. 记忆索引（SQLite）

~/.openclaw/memory/
└── <agentId>.sqlite          # 语义搜索索引

5. QMD 后端（如果启用）

~/.openclaw/agents/<agentId>/qmd/
├── xdg-config/              # QMD 配置
├── xdg-cache/               # QMD 缓存
└── sessions/                # QMD 会话导出

---

排除的文件/目录

以下内容不会被持久化（临时文件、缓存、锁文件）：

• *.lock - 锁文件
• *.tmp - 临时文件
• *.socket - Unix socket 文件
• *.pid - PID 文件
• node_modules/ - Node 依赖
• .cache/ - 缓存目录
• logs/ - 日志目录

---

环境变量配置

在 Hugging Face Space 的 Settings > Variables 中设置：

变量名	必需	默认值	说明
HF_TOKEN	✅	-	Hugging Face 访问令牌（需要写入权限）
OPENCLAW_DATASET_REPO	✅	-	数据集仓库 ID，如 username/openclaw-state
OPENCLAW_HOME	❌	~/.openclaw	OpenClaw 主目录
SYNC_INTERVAL	❌	300	自动备份间隔（秒）
ENABLE_AUX_SERVICES	❌	false	是否启用辅助服务（WA Guardian, QR Manager）

快速配置步骤

1. 创建数据集仓库

   在 Hugging Face 上创建一个新的 Dataset 仓库，例如：username/openclaw-state
   设置为 Private（私有）
   

2. 获取访问令牌

   访问：https://huggingface.co/settings/tokens
   创建新 Token，勾选 "Write" 权限
   

3. 配置 Space 变量

   HF_TOKEN = hf_xxxxx...（你的 Token）
   OPENCLAW_DATASET_REPO = username/openclaw-state（你的数据集 ID）
   

---

脚本说明

openclaw_persist.py

核心持久化模块，提供备份和恢复功能。

# 备份当前状态
python3 openclaw_persist.py save

# 恢复状态
python3 openclaw_persist.py load

# 查看状态
python3 openclaw_persist.py status

openclaw_sync.py

主同步管理器，被 entrypoint.sh 调用。

功能：

1. 启动时从数据集恢复状态
2. 启动 OpenClaw 网关
3. 后台定期备份
4. 优雅关闭时执行最终备份

---

备份文件命名

备份数据集中的文件命名格式：

backup-YYYYMMDD_HHMMSS.tar.gz

例如：backup-20250116_143022.tar.gz

系统会自动保留最近 5 个备份，删除更旧的。

---

故障排除

备份失败

1. 检查 HF_TOKEN 是否有写入权限
2. 检查 OPENCLAW_DATASET_REPO 是否正确
3. 查看日志中的错误信息

恢复失败

1. 数据集为空是正常的（首次运行）
2. 检查网络连接
3. 尝试手动恢复：python3 openclaw_persist.py load

WhatsApp 凭证丢失

备份包含 WhatsApp 凭证，恢复后应该能自动连接。如果需要重新扫码：

1. 登录 Hugging Face Space
2. 在日志中查找二维码
3. 使用手机 WhatsApp 扫码登录

---

与原 sync_hf.py 的区别

特性	sync_hf.py	openclaw_sync.py
同步方式	逐文件夹同步	完整目录 tar 归档
配置复杂度	高（需映射路径）	低（自动处理）
原子性	否	是
回滚能力	无	有（保留 5 个备份）
文件完整性	部分	完整

---

手动备份/恢复命令

本地测试

# 设置环境变量
export HF_TOKEN="hf_..."
export OPENCLAW_DATASET_REPO="username/openclaw-state"

# 手动备份
cd /home/node/scripts
python3 openclaw_persist.py save

# 手动恢复
python3 openclaw_persist.py load

# 查看状态
python3 openclaw_persist.py status

---

技术实现细节

备份过程

1. 检查 ~/.openclaw 目录
2. 创建 tar.gz 归档（应用排除规则）
3. 上传到 Hugging Face Dataset
4. 旋转备份（保留最近 5 个）
5. 更新本地状态文件

恢复过程

1. 从数据集获取最新备份
2. 下载到临时目录
3. 如有本地状态，先创建本地备份
4. 解压到 ~/.openclaw
5. 验证文件完整性

排除规则

EXCLUDE_PATTERNS = [
    "*.lock", "*.tmp", "*.pyc", "*__pycache__*",
    "*.socket", "*.pid", "node_modules", ".DS_Store", ".git",
]

SKIP_DIRS = {".cache", "logs", "temp", "tmp"}

---

更新日志

• v8 (2025-01-16): 实现完整目录持久化，使用 tar 归档方式
• v7 (之前): 使用 sync_hf.py 逐文件夹同步