Skip to content

将 OpenClaw 迁移到新机器 ​

本指南用于把 OpenClaw Gateway 从一台机器迁移到另一台机器,无需重新做 onboarding。

概念上迁移很简单:

  • 复制 state 目录($OPENCLAW_STATE_DIR,默认:~/.openclaw/)——其中包含 config、鉴权、sessions,以及 channel state。
  • 复制你的 workspace(默认:~/.openclaw/workspace/)——其中包含你的 agent 文件(memory、prompts 等)。

但实践中常见坑集中在 profiles、权限、以及只拷贝了一部分。

开始之前(你要迁移的是什么) ​

1)确认你的 state 目录 ​

大多数安装使用默认值:

  • State dir: ~/.openclaw/

但如果你使用了以下任一项,它可能不同:

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

如果你不确定,在旧机器上运行:

bash
openclaw status

在输出里查找 OPENCLAW_STATE_DIR / profile 的相关信息。如果你跑了多个 gateways,请对每个 profile 重复检查。

2)确认你的 workspace ​

常见默认值:

  • ~/.openclaw/workspace/(推荐 workspace)
  • 你自己创建的自定义目录

workspace 是 MEMORY.md、USER.md、memory/*.md 等文件所在位置。

3)理解你会保留哪些内容 ​

如果你同时复制 state dir + workspace,你会保留:

  • Gateway 配置(openclaw.json)
  • Auth profiles / API keys / OAuth tokens
  • Session 历史 + agent state
  • Channel state(例如 WhatsApp 的登录/会话)
  • Workspace 文件(memory、技能笔记等)

如果你只复制 workspace(例如通过 Git),你不会保留:

  • sessions
  • credentials
  • channel logins

这些都在 $OPENCLAW_STATE_DIR 下。

迁移步骤(推荐) ​

Step 0 — 先备份(旧机器) ​

在旧机器上,先停止 gateway,避免拷贝过程中有文件变化:

bash
openclaw gateway stop

(可选但推荐)把 state dir 和 workspace 打包归档:

bash
# 如果你使用 profile 或自定义路径,请调整下面的路径
cd ~
tar -czf openclaw-state.tgz .openclaw

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

如果你有多个 profiles/state dirs(例如 ~/.openclaw-main、~/.openclaw-work),请分别归档每个目录。

Step 1 — 在新机器上安装 OpenClaw ​

在新机器上安装 CLI(必要时也安装 Node):

此时即使 onboarding 创建了一个新的 ~/.openclaw/ 也没关系——下一步你会覆盖它。

Step 2 — 把 state dir + workspace 复制到新机器 ​

需要同时复制两者:

  • $OPENCLAW_STATE_DIR(默认 ~/.openclaw/)
  • 你的 workspace(默认 ~/.openclaw/workspace/)

常见方式:

  • scp 传 tar 包并解压
  • 通过 SSH 用 rsync -a
  • 外接硬盘

复制完成后请确认:

  • 包含了隐藏目录(例如 .openclaw/)
  • 文件所有权属于运行 gateway 的那个用户

Step 3 — 运行 Doctor(迁移 + service 修复) ​

在新机器上运行:

bash
openclaw doctor

Doctor 是“安全但无聊”的命令:修复 services、应用 config migrations,并对不匹配给出警告。

然后:

bash
openclaw gateway restart
openclaw status

常见坑(以及如何避免) ​

坑:profile / state-dir 不匹配 ​

如果旧 gateway 使用了 profile(或 OPENCLAW_STATE_DIR),但新 gateway 使用了不同的 profile/state dir,你会看到类似症状:

  • config 改了不生效
  • channels 丢失/登出
  • session history 为空

修复:确保新机器上的 gateway/service 使用与你迁移过来的同一个 profile/state dir,然后再运行:

bash
openclaw doctor

坑:只复制 openclaw.json ​

openclaw.json 不够。很多 provider 的状态存放在:

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

务必迁移整个 $OPENCLAW_STATE_DIR 文件夹。

坑:权限 / 所有权 ​

如果你用 root 复制或更换了用户,gateway 可能无法读取 credentials/sessions。

修复:确保 state dir + workspace 的所有者是运行 gateway 的用户。

坑:在 remote/local 模式之间迁移 ​

  • 如果你的 UI(WebUI/TUI)指向一个远程 gateway,那么 session store + workspace 的“事实来源”在远程主机上。
  • 仅迁移你的笔记本并不会迁移远程 gateway 的 state。

如果你处于 remote mode,请迁移gateway host。

坑:备份中包含 secrets ​

$OPENCLAW_STATE_DIR 包含 secrets(API keys、OAuth tokens、WhatsApp creds)。请把备份当作生产级 secrets 来对待:

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

验证清单 ​

在新机器上确认:

  • openclaw status 显示 gateway 正在运行
  • channels 仍保持连接(例如 WhatsApp 不需要重新配对)
  • dashboard 能打开并能看到既有 sessions
  • workspace 文件(memory、configs)存在

相关链接 ​