OpenClaw 完整备份与还原策略 v4.0

OpenClaw 完整备份与还原策略

版本： v4.0 - 路径替换版

创建时间： 2026-04-01

基于版本： v3.0 Final（2026-03-23）

目的： 新服务器部署或重置后快速恢复已训练的 OpenClaw 环境

核心改进： 支持跨用户还原，自动替换路径

一、OpenClaw 完整目录结构分析

1.1 核心配置文件（必须备份）

|-----------|------|----------|----------|-----------|

1.2 凭证和授权文件（必须备份）

**credentials/** - `~/.openclaw/credentials/` - **通道授权凭证**（Telegram pairing、飞书授权等） ⚠️ 包含用户授权信息 | 🔴 **P0**

- telegram-pairing.json - Telegram Bot 与用户配对信息

- feishu-pairing.json - 飞书 Bot 配对信息

1.3 Agent 配置（必须备份）

**agents/** - `~/.openclaw/agents/` - **所有 Agent 的配置和会话数据** ✅ 一般无敏感 | 🔴 **P0**

- main/ - 大虾 Agent 配置

- erxia/ - 二虾 Agent 配置

- sanxia/ - 三虾 Agent 配置

1.4 工作区文件（核心资产）

**workspace/** - `~/.openclaw/workspace/` - **主工作区**（大虾） ✅ 无 | 🔴 **P0**

- MEMORY.md - 长期记忆（核心规矩、用户偏好）

- SOUL.md - Agent 人格定义

- memory/ - 每日记忆日志

**workspace-erxia/** - `~/.openclaw/workspace-erxia/` - **二虾工作区** ✅ 无 | 🔴 **P0**

**workspace-sanxia/** - `~/.openclaw/workspace-sanxia/` - **三虾工作区** ✅ 无 | 🔴 **P0**

1.5 扩展和插件（必须备份）

**extensions/** - `~/.openclaw/extensions/` - **通道扩展插件** ⚠️ 部分包含配置 | 🔴 **P0**

- qqbot/ - QQ Bot 扩展

- wecom/ - 企业微信扩展

- dingtalk/ - 钉钉扩展

1.6 通道状态文件（建议备份）

**telegram/** - `~/.openclaw/telegram/` - **Telegram 通道状态** ⚠️ 用户 offset | 🟡 **P1**

**feishu/** - `~/.openclaw/feishu/` - **飞书通道状态** ✅ 无 | 🟢 **P2**

1.7 脚本和工具（必须备份）

**scripts/** - `~/.openclaw/scripts/` - **自定义脚本** ✅ 无 | 🔴 **P0**

- freeze/ - 冻结脚本（备份、还原等）

1.8 不备份的内容

`logs/` - 日志文件，可重新生成

`cache/` - 缓存文件，无需备份

`node_modules/` - 可通过 `npm install` 恢复

`delivery-queue/` - 消息队列，临时数据

`media/` - 媒体文件，占用空间大

二、备份文件结构

2.1 完整压缩包结构

2.2 命名规则

**完整压缩包**：`openclaw-backup-<自定义名>-YYYYMMDD.tar.gz`，示例：`openclaw-backup-manual-20260401.tar.gz`

**OpenClaw 压缩包**：`openclaw-data-YYYYMMDD.tar.gz`，示例：`openclaw-data-2026-04-01.tar.gz`

**还原脚本**：`restore.sh`（固定）

**策略文档**：`backup-strategy.md`（固定）

2.3 本地存储路径

固定输出目录：

BACKUP_LOCAL_DIR="$HOME/.openclaw/backups"

完整路径示例：

/home/admin/.openclaw/backups/openclaw-backup-manual-20260401.tar.gz

三、敏感信息处理策略

3.1 备份策略：默认非脱敏

原则： 备份时不脱敏，保留完整配置信息

| 文件 | 备份内容 | 说明 |

|------|----------|------|

| openclaw.json | 包含完整 botToken、appSecret、apiKey | 还原时可选择是否保留 |

| models.json | 包含完整 apiKey | 还原时可选择是否保留 |

| credentials/ | 包含完整 pairing 信息 | 还原时可选择是否保留 |

原因：

✅ 方便快速还原，无需重新配置

✅ 还原时提供选择权，灵活处理

✅ 适合私有环境、可信服务器

3.2 还原策略：交互式选择

还原脚本执行时提示：

选择 yes 的处理：

脱敏 openclaw.json、models.json

删除凭证文件

需手动重新配置 API Keys

选择 no 的处理：

保留原始配置文件

还原后可直接使用

四、路径替换策略（v4.0 新增）

4.1 为什么需要路径替换

场景 1：跨服务器还原

备份服务器：`/home/admin/`

还原服务器：`/home/ubuntu/`

自动替换路径，无需手动修改

场景 2：多环境部署

开发环境：`/home/dev/`

测试环境：`/home/test/`

生产环境：`/home/prod/`

同一备份包，还原到任意环境

场景 3：用户迁移

原用户：`admin`

新用户：`newuser`

迁移时自动替换所有路径

4.2 还原时路径替换流程

步骤 1：输入用户名

还原脚本提示：

用户输入：

同用户名还原：直接回车（默认 `admin`）

跨用户还原：输入目标用户名（如 `ubuntu`）

步骤 2：确认替换

脚本提示：

步骤 3：批量替换

脚本自动执行：

替换 JSON 文件

替换 Shell 脚本

替换 Markdown 文档

步骤 4：验证替换

脚本自动检查，确认没有旧路径残留。

4.3 替换范围

**JSON 配置**：所有路径字段，包括 openclaw.json、models.json

**Shell 脚本**：路径变量、硬编码路径，所有 *.sh 脚本

**Markdown 文档**：路径引用，包括 MEMORY.md、SESSION-STATE.md

五、备份执行流程

5.1 备份脚本功能

脚本名称： backup-openclaw.sh

位置： /home/admin/.openclaw/scripts/freeze/backup-openclaw.sh

功能：

1. ✅ 打包 OpenClaw 数据（非脱敏）

2. ✅ 生成还原脚本（v4.0 含路径替换）

3. ✅ 生成策略文档

4. ✅ 创建完整压缩包

5.2 备份脚本使用方式

运行备份脚本：`~/.openclaw/scripts/freeze/backup-openclaw.sh`

或带自定义名称：`~/.openclaw/scripts/freeze/backup-openclaw.sh manual`

六、还原流程（v4.0 增强版）

6.1 前置准备

1. 下载完整压缩包，放到指定目录（如 /tmp/）

2. 确认新环境已安装 OpenClaw，执行 openclaw --version 验证

6.2 解压完整压缩包

6.3 执行还原脚本

6.4 还原脚本交互流程（v4.0）

脚本会一步步提示你输入，全程交互式操作，跟着走就行。

七、验证清单

7.1 备份后验证

7.2 还原后验证

八、使用示例

8.1 备份示例

8.2 还原示例

九、常见问题

Q1: 还原后路径仍有错误？

Q2: 还原后 Telegram 无法使用？

十、freeze 脚本修改规矩

脚本位置： /home/admin/.openclaw/scripts/freeze/backup-openclaw.sh

修改前必须：

1. 汇报主人（原因 + 修改内容）

2. 等主人确认（说"确认"或"可以"）

3. 再修改脚本

4. 更新版本履历

十一、版本履历

| 版本 | 日期 | 说明 |

|------|------|------|

| v4.0 | 2026-04-01 | 路径替换版（新增用户名输入和批量替换） |

| v3.0 Final | 2026-03-23 | 完整备份与还原策略 |

文档版本： v4.0

最后更新： 2026-04-14

维护者： 松遥的大虾 🦞

脚本位置： /home/admin/.openclaw/scripts/freeze/backup-openclaw.sh