ckriti/HuggingClaw

1# OpenClaw 持久化存储配置指南2 3## 概述4 5本配置实现了 OpenClaw 在 Hugging Face Space 中的**完整持久化存储**，确保容器重启后所有状态都能恢复。6 7### 核心特性8 9- **完整目录备份**: 持久化整个 `~/.openclaw` 目录10- **原子操作**: 使用 tar.gz 归档确保备份一致性11- **自动轮转**: 保留最近 5 个备份，自动清理旧备份12- **优雅关闭**: 容器停止时自动执行最终备份13 14---15 16## 持久化的目录和文件17 18### 1. 核心配置19```20~/.openclaw/21├── openclaw.json              # 主配置文件（模型、插件、网关设置）22└── credentials/               # 所有渠道的登录凭证23    ├── whatsapp/24    │   └── default/25    │       └── auth_info_multi.json26    └── telegram/27        └── session.data28```29 30### 2. 工作空间31```32~/.openclaw/workspace/33├── AGENTS.md                 # 代理定义34├── SOUL.md                   # 灵魂（性格、说话风格）35├── TOOLS.md                  # 可用工具列表36├── MEMORY.md                 # 长期聚合记忆37├── memory/                   # 每日记忆文件38│   ├── 2025-01-15.md39│   └── 2025-01-16.md40└── skills/                   # 技能定义41    ├── my-skill/42    │   └── SKILL.md43    └── ...44```45 46### 3. 会话历史47```48~/.openclaw/agents/<agentId>/sessions/49├── <sessionId>.jsonl          # 每个会话的完整对话历史50└── sessions.json             # 会话索引51```52 53### 4. 记忆索引（SQLite）54```55~/.openclaw/memory/56└── <agentId>.sqlite          # 语义搜索索引57```58 59### 5. QMD 后端（如果启用）60```61~/.openclaw/agents/<agentId>/qmd/62├── xdg-config/              # QMD 配置63├── xdg-cache/               # QMD 缓存64└── sessions/                # QMD 会话导出65```66 67---68 69## 排除的文件/目录70 71以下内容**不会**被持久化（临时文件、缓存、锁文件）：72 73- `*.lock` - 锁文件74- `*.tmp` - 临时文件75- `*.socket` - Unix socket 文件76- `*.pid` - PID 文件77- `node_modules/` - Node 依赖78- `.cache/` - 缓存目录79- `logs/` - 日志目录80 81---82 83## 环境变量配置84 85在 Hugging Face Space 的 Settings > Variables 中设置：86 87| 变量名 | 必需 | 默认值 | 说明 |88|--------|------|--------|------|89| `HF_TOKEN` | ✅ | - | Hugging Face 访问令牌（需要写入权限） |90| `OPENCLAW_DATASET_REPO` | ✅ | - | 数据集仓库 ID，如 `username/openclaw-state` |91| `OPENCLAW_HOME` | ❌ | `~/.openclaw` | OpenClaw 主目录 |92| `SYNC_INTERVAL` | ❌ | `300` | 自动备份间隔（秒） |93| `ENABLE_AUX_SERVICES` | ❌ | `false` | 是否启用辅助服务（WA Guardian, QR Manager） |94 95### 快速配置步骤96 971. **创建数据集仓库**98   ```99   在 Hugging Face 上创建一个新的 Dataset 仓库，例如：username/openclaw-state100   设置为 Private（私有）101   ```102 1032. **获取访问令牌**104   ```105   访问：https://huggingface.co/settings/tokens106   创建新 Token，勾选 "Write" 权限107   ```108 1093. **配置 Space 变量**110   ```111   HF_TOKEN = hf_xxxxx...（你的 Token）112   OPENCLAW_DATASET_REPO = username/openclaw-state（你的数据集 ID）113   ```114 115---116 117## 脚本说明118 119### openclaw_persist.py120 121核心持久化模块，提供备份和恢复功能。122 123```bash124# 备份当前状态125python3 openclaw_persist.py save126 127# 恢复状态128python3 openclaw_persist.py load129 130# 查看状态131python3 openclaw_persist.py status132```133 134### openclaw_sync.py135 136主同步管理器，被 entrypoint.sh 调用。137 138功能：1391. 启动时从数据集恢复状态1402. 启动 OpenClaw 网关1413. 后台定期备份1424. 优雅关闭时执行最终备份143 144---145 146## 备份文件命名147 148备份数据集中的文件命名格式：149 150```151backup-YYYYMMDD_HHMMSS.tar.gz152```153 154例如：`backup-20250116_143022.tar.gz`155 156系统会自动保留最近 5 个备份，删除更旧的。157 158---159 160## 故障排除161 162### 备份失败163 1641. 检查 `HF_TOKEN` 是否有写入权限1652. 检查 `OPENCLAW_DATASET_REPO` 是否正确1663. 查看日志中的错误信息167 168### 恢复失败169 1701. 数据集为空是正常的（首次运行）1712. 检查网络连接1723. 尝试手动恢复：`python3 openclaw_persist.py load`173 174### WhatsApp 凭证丢失175 176备份包含 WhatsApp 凭证，恢复后应该能自动连接。如果需要重新扫码：177 1781. 登录 Hugging Face Space1792. 在日志中查找二维码1803. 使用手机 WhatsApp 扫码登录181 182---183 184## 与原 sync_hf.py 的区别185 186| 特性 | sync_hf.py | openclaw_sync.py |187|------|------------|------------------|188| 同步方式 | 逐文件夹同步 | 完整目录 tar 归档 |189| 配置复杂度 | 高（需映射路径） | 低（自动处理） |190| 原子性 | 否 | 是 |191| 回滚能力 | 无 | 有（保留 5 个备份） |192| 文件完整性 | 部分 | 完整 |193 194---195 196## 手动备份/恢复命令197 198### 本地测试199 200```bash201# 设置环境变量202export HF_TOKEN="hf_..."203export OPENCLAW_DATASET_REPO="username/openclaw-state"204 205# 手动备份206cd /home/node/scripts207python3 openclaw_persist.py save208 209# 手动恢复210python3 openclaw_persist.py load211 212# 查看状态213python3 openclaw_persist.py status214```215 216---217 218## 技术实现细节219 220### 备份过程221 2221. 检查 `~/.openclaw` 目录2232. 创建 tar.gz 归档（应用排除规则）2243. 上传到 Hugging Face Dataset2254. 旋转备份（保留最近 5 个）2265. 更新本地状态文件227 228### 恢复过程229 2301. 从数据集获取最新备份2312. 下载到临时目录2323. 如有本地状态，先创建本地备份2334. 解压到 `~/.openclaw`2345. 验证文件完整性235 236### 排除规则237 238```python239EXCLUDE_PATTERNS = [240    "*.lock", "*.tmp", "*.pyc", "*__pycache__*",241    "*.socket", "*.pid", "node_modules", ".DS_Store", ".git",242]243 244SKIP_DIRS = {".cache", "logs", "temp", "tmp"}245```246 247---248 249## 更新日志250 251- **v8** (2025-01-16): 实现完整目录持久化，使用 tar 归档方式252- **v7** (之前): 使用 sync_hf.py 逐文件夹同步253