将 OpenClaw 迁移到新机器

本指南教你如何将 OpenClaw Gateway 从一台机器迁移到另一台，无需重新走引导流程。

迁移的概念很简单：

  • 复制 state 目录（$OPENCLAW_STATE_DIR，默认是 ~/.openclaw/）—— 包含配置、认证、session 和 channel 状态。
  • 复制你的 workspace（默认是 ~/.openclaw/workspace/）—— 包含 agent 文件（记忆、prompt 等）。

但有一些常见的坑，涉及 profile、权限 和 部分复制。

开始之前（了解你要迁移什么）

1) 确认你的 state 目录

大多数安装使用默认位置：

  • State 目录： ~/.openclaw/

但如果你使用了以下方式，位置可能不同：

  • --profile <name>（通常会变成 ~/.openclaw-<profile>/）
  • OPENCLAW_STATE_DIR=/some/path

如果不确定，在旧机器上运行：

openclaw status

在输出中查找 OPENCLAW_STATE_DIR / profile 的提及。如果你运行多个 gateway，对每个 profile 重复检查。

2) 确认你的 workspace

常见的默认位置：

  • ~/.openclaw/workspace/（推荐的 workspace）
  • 你自己创建的自定义文件夹

你的 workspace 是存放 MEMORY.md、USER.md 和 memory/*.md 等文件的地方。

3) 了解你会保留什么

如果你同时复制 state 目录和 workspace，你会保留：

  • Gateway 配置（openclaw.json）
  • 认证 profile / API 密钥 / OAuth token
  • Session 历史 + agent 状态
  • Channel 状态（例如 WhatsApp 登录/session）
  • 你的 workspace 文件（记忆、skill 笔记等）

如果你只复制 workspace（例如通过 Git），你不会保留：

  • session
  • 凭证
  • channel 登录状态

这些都存储在 $OPENCLAW_STATE_DIR 下。

迁移步骤（推荐）

步骤 0 — 备份（旧机器）

在旧机器上，先停止 gateway，避免复制过程中文件变化：

openclaw gateway stop

（可选但推荐）打包 state 目录和 workspace：

# 如果你使用了 profile 或自定义位置，调整路径
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

如果你有多个 profile/state 目录（例如 ~/.openclaw-main、~/.openclaw-work），分别打包每一个。

步骤 1 — 在新机器上安装 OpenClaw

在新机器上，安装 CLI（如果需要的话还要装 Node）：

这个阶段，引导流程创建一个新的 ~/.openclaw/ 也没关系 —— 你会在下一步覆盖它。

步骤 2 — 复制 state 目录 + workspace 到新机器

复制两者：

  • $OPENCLAW_STATE_DIR（默认是 ~/.openclaw/）
  • 你的 workspace（默认是 ~/.openclaw/workspace/）

常见方法：

  • 用 scp 传输压缩包并解压
  • 用 rsync -a 通过 SSH 同步
  • 用外置硬盘

复制后，确保：

  • 隐藏目录被包含了（例如 .openclaw/）
  • 文件所有权对运行 gateway 的用户是正确的

步骤 3 — 运行 Doctor（迁移 + 服务修复）

在新机器上：

openclaw doctor

Doctor 是”安全无聊”的命令。它会修复服务、应用配置迁移，并警告不匹配的地方。

然后：

openclaw gateway restart
openclaw status

常见的坑（以及如何避免）

坑：profile / state-dir 不匹配

如果你在旧 gateway 上使用了 profile（或 OPENCLAW_STATE_DIR），而新 gateway 使用了不同的，你会看到这些症状：

  • 配置更改不生效
  • channel 丢失 / 登出
  • session 历史为空

修复方法：使用相同的 profile/state 目录运行 gateway/服务，然后重新运行：

openclaw doctor

坑：只复制 openclaw.json

只有 openclaw.json 是不够的。很多 provider 会在以下位置存储状态：

  • $OPENCLAW_STATE_DIR/credentials/
  • $OPENCLAW_STATE_DIR/agents/<agentId>/...

始终迁移整个 $OPENCLAW_STATE_DIR 文件夹。

坑：权限 / 所有权

如果你以 root 身份复制或更换了用户，gateway 可能无法读取凭证/session。

修复方法：确保 state 目录 + workspace 的所有者是运行 gateway 的用户。

坑：在 remote/local 模式之间迁移

  • 如果你的 UI（WebUI/TUI）指向远程 gateway，远程主机拥有 session 存储 + workspace。
  • 迁移你的笔记本不会移动远程 gateway 的状态。

如果你在 remote 模式，迁移 gateway 主机。

坑：备份中的密钥

$OPENCLAW_STATE_DIR 包含密钥（API 密钥、OAuth token、WhatsApp 凭证）。像对待生产密钥一样对待备份：

  • 加密存储
  • 避免通过不安全的渠道分享
  • 如果怀疑泄露，轮换密钥

验证清单

在新机器上，确认：

  • openclaw status 显示 gateway 正在运行
  • 你的 channel 仍然连接（例如 WhatsApp 不需要重新配对）
  • dashboard 打开并显示现有的 session
  • 你的 workspace 文件（记忆、配置）都在

相关内容