OpenClaw 云端迁移至本地部署指南

适用场景：OpenClaw 最初部署在云端（VPS/服务器），调教完成后迁移到本地机器（Mac/Linux/Windows）继续使用。
本文档涵盖：完整数据迁移、选择性迁移、部分迁移方案、以及迁移后的验证步骤。

1. 前置准备

1.1 确认 OpenClaw 版本

在云端服务器执行：

openclaw --version
openclaw status

记录输出的版本号、Gateway 地址、已安装的插件和技能列表。

1.2 检查数据量

du -sh ~/.openclaw/           # 总大小
du -sh ~/.openclaw/workspace/ # workspace 大小
du -sh ~/.openclaw/skills/    # 技能大小
du -sh ~/.openclaw/logs/      # 日志大小（可排除）

当前示例数据总量约 877MB，其中 workspace + skills 是核心，logs 可排除。

1.3 本地安装 OpenClaw

在本地机器上安装与云端相同（或更新）版本：

# macOS
brew install openclaw
# Linux / macOS (npm)
npm install -g openclaw
# 验证版本一致
openclaw --version

2. 完整迁移（推荐）

2.1 云端 — 停止网关并打包

⚠️ 停止网关可以防止迁移过程中数据被写入，保证数据一致性。

# 登录云端服务器
# 1. 停止 OpenClaw 网关
openclaw gateway stop
# 2. 确认进程已停止
openclaw status | grep Gateway
# 预期输出：Gateway ... stopped 或类似
# 3. 排除不必要的目录（减小体积）
# 日志文件体积大但迁移价值低，可以先清空或排除
rm -rf ~/.openclaw/logs/*.log   # 可选：清理旧日志
# 4. 打包整个目录
tar -czvf openclaw-full-backup.tar.gz \
  --exclude='.DS_Store' \
  --exclude='node_modules' \
  --exclude='.git' \
  ~/.openclaw/
# 5. 查看打包结果
ls -lh openclaw-full-backup.tar.gz

2.2 传输备份文件到本地

选择以下任意一种方式：

方式 A：SCP（推荐）

# 在本地机器执行
scp your-user@your-cloud-server:/path/to/openclaw-full-backup.tar.gz ~/
# 如果使用了 SSH 密钥
scp -i ~/.ssh/your-key.pem your-user@your-cloud-server:/path/to/openclaw-full-backup.tar.gz ~/

方式 B：Rsync（适合大文件、断点续传）

rsync -avP -e ssh your-user@your-cloud-server:/path/to/openclaw-full-backup.tar.gz ~/

方式 C：云对象存储

上传到 OSS/S3/GCS，本地下载（适合网络不稳定的情况）。

2.3 本地 — 解压恢复

# 1. 解压到临时目录（先不覆盖，防止意外）
mkdir -p ~/openclaw-restore
tar -xzvf openclaw-full-backup.tar.gz -C ~/openclaw-restore/
# 2. 查看解压结果
ls ~/openclaw-restore/
# 3. 备份本地已有的 openclaw 目录（如果有）
mv ~/.openclaw ~/.openclaw.local.bak 2>/dev/null
# 4. 移动恢复
mv ~/openclaw-restore/.openclaw ~/
# 5. 验证目录结构
ls -la ~/.openclaw/

2.4 修复路径问题

# 运行诊断工具，自动修复路径不一致问题
openclaw doctor
# 根据提示修复任何路径或权限问题

2.5 启动网关

openclaw gateway start

3. 选择性迁移

如果你不需要完整迁移（比如只想要记忆和配置），可以只打包部分目录。

3.1 打包时选择性包含

tar -czvf openclaw-selective.tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/identity/ \
  ~/.openclaw/agents/ \
  ~/.openclaw/workspace/ \
  ~/.openclaw/cron/ \
  ~/.openclaw/memory/ \
  ~/.openclaw/skills/ \
  ~/.openclaw/devices/

3.2 选择性迁移清单

4. 部分迁移（轻量方案）

适用于只想迁移核心记忆和配置，不迁移会话历史的情况。

4.1 只迁移工作区和记忆

# 在云端打包
tar -czvf openclaw-minimal.tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/identity/ \
  ~/.openclaw/workspace/ \
  ~/.openclaw/memory/
# 传输后本地解压恢复
tar -xzvf openclaw-minimal.tar.gz -C ~/
# 重新安装 skills
clawhub sync
# 重启网关
openclaw gateway restart

4.2 技能重建

如果选择不迁移 skills/ 目录，本地可以用以下方式重建：

# 查看云端装了哪些技能（备份前记录）
ls ~/.openclaw/skills/
# 在本地重新安装（需要先查云端装的 skill IDs 或 names）
clawhub install <skill-name>
# 或者在 workspace/skills/ 目录手动恢复

5. 云端善后

迁移完成后，建议在云端执行以下操作：

5.1 停止云端网关（防止混淆）

# 在云端服务器执行
openclaw gateway stop

5.2 考虑删除或保留备份

# 确认本地迁移成功后再删除云端数据（谨慎！）
# rm -rf ~/.openclaw/
# rm openclaw-full-backup.tar.gz

5.3 如果要彻底释放云端资源

⚠️ 这是不可逆操作，请确保本地迁移完全成功后再执行。

# 停止并卸载 OpenClaw
openclaw gateway stop
npm uninstall -g openclaw
# 删除所有数据（不可恢复！）
rm -rf ~/.openclaw/
# 释放服务器（如果是按量付费的实例可以关机/删除）

6. 迁移后验证

6.1 基本验证

# 1. 确认版本
openclaw --version
# 2. 检查网关状态
openclaw status
# 3. 检查工作区文件完整性
ls ~/.openclaw/workspace/
cat ~/.openclaw/workspace/MEMORY.md | head -20
# 4. 检查记忆文件
ls ~/.openclaw/memory/
# 5. 检查定时任务
openclaw cron list

6.2 功能验证

• 对话功能：发送一条消息，确认 AI 能正常回复
• 记忆检索：问一个之前保存在 MEMORY.md 中的问题
• 定时任务：检查 cron 任务是否正常
• 频道连接：Telegram/WhatsApp/QQ 等频道是否正常连接
• 技能：检查自定义技能是否正常工作

6.3 完整性检查清单

✅ OpenClaw 版本一致✅ 网关正常启动✅ 工作区文件完整（MEMORY.md、SOUL.md 等）✅ 记忆文件恢复✅ 定时任务配置保留✅ 频道（Telegram/WhatsApp/QQ）登录状态保留✅ 自定义技能可用✅ AI 能正常对话✅ API 密钥和认证信息正确

7. 常见问题

Q1：迁移后 openclaw doctor 报路径错误？

A：正常现象。旧路径是云端的绝对路径（如 /root/.openclaw/），本地路径是 /Users/yourname/.openclaw/。openclaw doctor 会自动修复配置文件中的路径，无需手动修改。

Q2：Telegram/WhatsApp 登录态丢失？

A：认证 token 保存在 identity/ 目录，完整迁移时不会丢失。如果使用部分迁移方案，确保包含 identity/ 目录。

如果确实丢失，需要重新在本地设备进行 OAuth 授权。

Q3：API 密钥需要重新配置吗？

A：如果完整迁移，openclaw.json 中的 API Key 会一起迁移过来，无需重新配置。如果只迁移了工作区，需要在本地 openclaw.json 或环境变量中重新配置。

Q4：迁移后模型不工作？

A：检查 openclaw.json 中的模型配置是否正确。如果是云端专用的 API 地址（如内网地址），本地无法访问，需要更改为公网可用的端点。

Q5：技能（Skills）需要重新安装吗？

A：不一定。如果完整迁移，skills/ 目录会一起过来，本地可以直接使用。如果选择了轻量方案，从 ClawHub 安装的公共技能可以重新通过 clawhub sync 拉回，自定义技能需要手动恢复。

Q6：云端和本地可以同时运行吗？

A：可以，但不推荐，因为会共享同一份数据目录（如果用同一个 state dir），会导致状态混乱。如果确实需要双端运行，可以使用不同的 --profile 参数指定不同的配置目录。

Q7：数据量太大，传输慢怎么办？

A：

1. 排除 logs/ 目录（节省大量空间）
2. 优先传输 openclaw.json + workspace/ + memory/，这三个最重要
3. 使用压缩率更高的 xz 格式：tar -cJvf backup.tar.xz ~/.openclaw/
4. 使用 Rsync 的 --compress 选项减少传输量

Q8：迁移后发现缺少文件怎么办？

A：

1. 检查打包时是否用了 --exclude 排除了某些文件
2. 确认云端原始目录是否包含这些文件
3. 如果备份文件还在，可以重新解压提取丢失的文件
4. 养成习惯：重要操作前先 du -sh ~/.openclaw/ 记录大小，迁移后对比

附录：快速命令速查

# = 云端操作 =
# 停止网关
openclaw gateway stop
# 查看数据大小
du -sh ~/.openclaw/
# 完整打包（排除日志）
tar -czvf openclaw-backup.tar.gz \
  --exclude='.DS_Store' \
  --exclude='logs' \
  ~/.openclaw/
# = 本地操作 =
# 解压恢复
tar -xzvf openclaw-backup.tar.gz -C ~/
# 修复路径
openclaw doctor
# 启动网关
openclaw gateway start
# 验证状态
openclaw status