---
name: restore-state
description: 从 ZIP 备份文件恢复 SophClaw 完整状态。当用户说要"恢复数据"、"还原备份"、"恢复我的账号"、"restore"并上传了 ZIP 文件时触发。支持恢复 agent 配置、会话历史、workspace 文件、语义记忆等全部状态。
---

# Restore State

从用户上传的 ZIP 备份文件恢复 SophClaw 完整状态到当前空白容器。

## 前置检查

在开始恢复之前，先确认以下几点：

1. 用户已通过聊天上传了一个 `.zip` 文件（从 SophClaw 前端下载的备份包）
2. 当前容器是空白状态（新创建的容器，不包含用户之前的数据）
3. 如果当前容器已有重要数据，警告用户会被部分覆盖

向用户简短确认：

- "我将用你上传的备份文件恢复你的 SophClaw 状态，包括 agent 配置、会话历史和 workspace 文件。当前容器的某些数据会被覆盖。确认继续吗？"

用户确认后继续。

## 定位上传的 ZIP 文件

用户通过 SophClaw Web UI 上传的文件会被保存在 `~/.openclaw/media/inbound/` 目录下，文件名格式为 `<原始名称>---<uuid>.zip`。

**第一步：查找最新上传的 ZIP 文件**

```bash
ls -lt ~/.openclaw/media/inbound/*.zip 2>/dev/null | head -5
```

如果用户刚上传了一个恢复用的 ZIP，最新的文件就是它（文件名包含恢复相关的关键词如 `restore`、`backup`、`openclaw` 等）。

如果找到明确的文件，直接使用它的完整路径。如果有多个 ZIP，选择最新的那个。

**第二步：如果 media/inbound 目录没有 ZIP**

可能用户是通过其他方式提供的文件路径。请用户确认文件位置，然后用 `ls` 验证。

## 执行恢复

找到 ZIP 文件路径后，运行：

```bash
python3 skills/restore-state/src/scripts/restore.py "<找到的zip文件完整路径>"
```

也可以不加参数直接运行，脚本会自动搜索 `~/.openclaw/media/inbound/` 中最新的 ZIP：

```bash
python3 skills/restore-state/src/scripts/restore.py
```

## 解释恢复结果

脚本会输出恢复摘要，包括：
- 恢复了哪些 agent（main、assistant、beauty、vip-qa 等）
- 恢复了多少条会话记录
- 恢复了哪些 workspace
- 是否有跳过的文件及原因

向用户报告摘要。

## 下一步提示

提醒用户：

- "由于更新了配置，SophClaw 会自动重新加载。等待约 10 秒后刷新前端页面即可看到恢复的会话和 agent。"

## 异常处理

| 场景 | 处理方式 |
|------|----------|
| ZIP 文件路径不存在 | 用 `ls ~/.openclaw/media/inbound/` 查看可用文件，选最新的 ZIP |
| ZIP 文件格式损坏 | 请用户重新下载备份文件后再试 |
| 未找到任何 ZIP 文件 | 请用户重新上传备份文件到聊天中 |
| Python 或依赖缺失 | 运行 `which python3` 确认解释器存在 |
| 权限被拒绝写入 ~/.openclaw | 检查当前用户和目录权限 |
| openclaw.json 解析失败 | 检查备份文件是否完整，尝试用 `python3 -m json.tool` 验证 JSON |
| Gateway 重载失败 | 手动运行 `openclaw daemon restart` |