将 OpenClaw 迁移到新机器

本指南帮助你把 OpenClaw Gateway 从一台机器迁到另一台，不用重做引导流程。

迁移本身很简单：

复制状态目录（$OPENCLAW_STATE_DIR，默认 ~/.openclaw/）——包含配置、认证、会话和渠道状态。
复制工作区（默认 ~/.openclaw/workspace/）——包含你的 Agent 文件（记忆、提示词等）。

但在配置文件、权限和不完整复制方面有些常见的坑。

开始之前（你在迁移什么）

1) 确认你的状态目录

大多数安装使用默认值：

状态目录： ~/.openclaw/

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

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

不确定的话，在旧机器上运行：

openclaw status

留意输出中提到的 OPENCLAW_STATE_DIR / profile。如果运行了多个网关，每个 profile 都需要重复操作。

2) 确认你的工作区

常见默认值：

~/.openclaw/workspace/（推荐的工作区）
你创建的自定义文件夹

工作区中包含 MEMORY.md、USER.md 和 memory/*.md 等文件。

3) 了解你会保留什么

如果同时复制状态目录和工作区，你会保留：

网关配置（openclaw.json）
认证配置 / API key / OAuth token
会话历史 + Agent 状态
渠道状态（如 WhatsApp 登录/会话）
工作区文件（记忆、技能笔记等）

如果只复制工作区（比如通过 Git），你不会保留：

会话
凭据
渠道登录

这些都在 $OPENCLAW_STATE_DIR 下。

迁移步骤（推荐）

第 0 步 — 备份（旧机器）

在旧机器上，先停止网关，确保文件不会在复制过程中变动：

openclaw gateway stop

（可选但推荐）打包状态目录和工作区：

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

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

如果有多个 profile/状态目录（如 ~/.openclaw-main、~/.openclaw-work），每个都要打包。

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

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

参阅：安装

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

第 2 步 — 将状态目录 + 工作区复制到新机器

两者都要复制：

$OPENCLAW_STATE_DIR（默认 ~/.openclaw/）
你的工作区（默认 ~/.openclaw/workspace/）

常见方法：

scp 传输压缩包并解压
rsync -a 通过 SSH 同步
移动硬盘

复制完后确认：

隐藏目录已包含（如 .openclaw/）
文件所有者是运行网关的用户

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

在新机器上：

openclaw doctor

Doctor 是那种”安全、无聊”的命令。它修复服务、应用配置迁移、在有问题时发出警告。

然后：

openclaw gateway restart
openclaw status

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

坑：profile / 状态目录不匹配

如果旧网关使用了 profile（或 OPENCLAW_STATE_DIR），而新网关用了不同的，你会遇到：

配置修改不生效
渠道丢失 / 已登出
会话历史为空

修复：用迁移过来的相同 profile/状态目录启动网关/服务，然后重新运行：

openclaw doctor

坑：只复制了 `openclaw.json`

openclaw.json 远远不够。很多提供商的状态存储在：

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

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

坑：权限/所有权问题

如果用 root 复制或更换了用户，网关可能无法读取凭据/会话。

修复：确保状态目录 + 工作区的所有者是运行网关的用户。

坑：远程/本地模式间迁移

如果你的 UI（WebUI/TUI）指向远程网关，那么会话存储 + 工作区归远程主机所有。
迁移你的笔记本不会迁移远程网关的状态。

如果是远程模式，迁移网关主机。

坑：备份中的密钥

$OPENCLAW_STATE_DIR 包含密钥（API key、OAuth token、WhatsApp 凭据）。备份要当生产密钥对待：

加密存储
不要通过不安全的渠道传输
如果怀疑泄露，轮换密钥

验证清单

在新机器上确认：

openclaw status 显示网关正在运行
你的渠道仍然连接（例如 WhatsApp 无需重新配对）
Dashboard 可以打开并显示已有的会话
工作区文件（记忆、配置）都在