迁移指南

将 OpenClaw 从一台机器迁移到另一台，只需 复制数据 + 验证 两步。

---

迁移前准备

在旧机器上：

# 1. 停止 Gateway
openclaw stop

# 2. 确认版本
openclaw --version
# 记录版本号，确保新机器安装相同或更高版本

# 3. 确认数据目录位置
openclaw config get data_dir
# 默认为 ~/.openclaw

---

步骤一：复制数据

需要复制的目录

目录	说明	必须？
~/.openclaw/	配置、数据库、插件、密钥	✅ 是
~/workspace/（或自定义）	Agent 工作区文件	⚠️ 按需

使用 rsync（推荐）

# 从旧机器复制到新机器
rsync -avz --progress ~/.openclaw/ user@new-machine:~/.openclaw/
rsync -avz --progress ~/workspace/ user@new-machine:~/workspace/

使用 tar + scp

# 旧机器：打包
tar czf openclaw-backup.tar.gz -C ~ .openclaw workspace

# 传输到新机器
scp openclaw-backup.tar.gz user@new-machine:~/

# 新机器：解压
ssh user@new-machine
tar xzf openclaw-backup.tar.gz -C ~

使用 Docker 卷迁移

如果使用 Docker 部署：

# 旧机器：导出卷
docker run --rm -v openclaw-home:/data -v $(pwd):/backup alpine \
  tar czf /backup/openclaw-volume.tar.gz -C /data .

# 传输到新机器后：导入卷
docker volume create openclaw-home
docker run --rm -v openclaw-home:/data -v $(pwd):/backup alpine \
  tar xzf /backup/openclaw-volume.tar.gz -C /data

---

步骤二：在新机器上验证

# 1. 安装 OpenClaw（如果还没有）
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. 运行 doctor 检查
openclaw doctor

# 3. 启动 Gateway
openclaw start

# 4. 验证配置是否完整
openclaw status

---

常见问题

权限不匹配

如果新旧机器的用户 UID 不同：

sudo chown -R $(whoami) ~/.openclaw

插件加载失败

某些插件包含平台相关的原生模块，跨平台迁移时需要重新安装：

openclaw plugin reinstall --all

API Key / Token 是否需要重新配置？

不需要——API Key 和 Token 存储在 ~/.openclaw/ 中，复制后自动生效。

旧机器能否继续使用？

可以，但 不建议同时运行两个 Gateway 实例访问同一组服务（如同一个 Telegram Bot Token），会导致消息冲突。确保旧机器的 Gateway 已停止。

---

🇨🇳 中国用户须知

如果新旧机器分别在国内和海外，rsync / scp 传输速度可能较慢。可先将备份上传到对象存储（如阿里云 OSS、腾讯云 COS），再从另一端下载：

# 上传到阿里云 OSS
ossutil cp openclaw-backup.tar.gz oss://your-bucket/

# 从新机器下载
ossutil cp oss://your-bucket/openclaw-backup.tar.gz .