将 OpenClaw 迁移到新机器

本指南介绍如何将 OpenClaw Gateway 迁移到新机器，无需重新执行引导流程。

迁移内容

复制状态目录（默认 ~/.openclaw/）和工作区后，你将保留：

提示： 在旧机器上运行 openclaw status 确认你的状态目录路径。自定义配置文件使用 ~/.openclaw-<profile>/ 或通过 OPENCLAW_STATE_DIR 指定的路径。

第一步：停止 Gateway 并备份

在旧机器上停止 Gateway（避免文件在复制过程中被修改），然后打包：

bash

openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw

如果使用多个配置文件（如 ~/.openclaw-work），分别打包每一个。

第二步：在新机器上安装 OpenClaw

在新机器上安装 CLI（以及 Node，如果需要）。引导流程创建了新的 ~/.openclaw/ 没关系——下一步会覆盖它。

第三步：复制状态目录和工作区

通过 scp、rsync -a 或外部存储传输压缩包，然后解压：

bash

cd ~
tar -xzf openclaw-state.tgz

确认隐藏目录已包含在内，且文件所有权与将要运行 Gateway 的用户匹配。

第四步：运行 doctor 并验证

在新机器上运行 Doctor 应用配置迁移并修复服务：

bash

openclaw doctor
openclaw gateway restart
openclaw status

配置文件或状态目录不匹配：

旧 Gateway 使用了 --profile 或 OPENCLAW_STATE_DIR，新机器没有配置时，渠道会显示未登录，会话也会为空。使用与迁移时相同的 profile 或 state-dir 启动 Gateway，然后重新运行 openclaw doctor。

只复制了 openclaw.json：

仅复制配置文件是不够的。凭证存储在 credentials/ 目录，Agent 状态存储在 agents/ 目录。必须迁移完整的状态目录。

权限和所有权问题：

如果以 root 身份复制或切换了用户，Gateway 可能无法读取凭证。确保状态目录和工作区归运行 Gateway 的用户所有。

远程模式：

如果你的 UI 连接的是远程 Gateway，会话和工作区在远程主机上。迁移的是 Gateway 主机本身，而不是你的本地笔记本。参见 FAQ。

备份中含有密钥：

状态目录包含 API Key、OAuth Token 和渠道凭证。备份文件请加密存储，避免通过不安全渠道传输，如果怀疑有泄露风险请轮换密钥。

在新机器上确认：