在实际使用 OpenClaw Gateway 的过程中，很多用户会遇到这样的需求：

服务器需要升级、机器需要更换，或者需要把环境迁移到新的云主机。

好消息是：OpenClaw 的迁移其实非常简单。只要正确复制关键目录，就可以在新机器上恢复原来的运行环境，无需重新进行新手引导，也不需要重新配置渠道或智能体。

家兴网络将详细介绍完整的迁移流程以及常见问题。

一、OpenClaw 迁移的核心原理

OpenClaw 的运行数据主要存储在两个位置：

1. 状态目录（State Directory）

默认路径：

~/.openclaw/

这个目录保存：

• Gateway 配置文件 openclaw.json

• API Key / OAuth 认证信息

• 渠道登录状态（如 WhatsApp 会话）

• 智能体运行状态

• 会话历史记录

简单来说：系统运行的所有状态都在这里。

2. 工作区（Workspace）

默认路径：

~/.openclaw/workspace/

这个目录主要保存用户编写的内容，例如：

• MEMORY.md

• USER.md

• memory/*.md

• 智能体提示词

• Skills 笔记

简单理解就是：你的 AI 代理配置和知识库。

3. 两个目录的区别

如果迁移：

状态目录 + 工作区

你会完整保留：

• Gateway 配置

• API Key 和认证

• 会话记录

• 渠道登录状态

• 智能体记忆和提示词

如果只迁移：

工作区

你只会保留：

• 智能体配置

• 知识库文件

不会保留：

• 会话

• API Key

• 渠道登录

二、迁移前需要确认的两件事

1 确认状态目录位置

大多数用户使用默认路径：

~/.openclaw/

但如果使用以下方式安装，路径可能不同：

• 使用 profile

--profile <name>

例如：

~/.openclaw-main/
~/.openclaw-work/

或者通过环境变量指定：

OPENCLAW_STATE_DIR=/custom/path

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

openclaw status

在输出中查找：

OPENCLAW_STATE_DIR
profile

如果运行多个 Gateway，需要分别确认。

2 确认工作区位置

常见路径：

~/.openclaw/workspace/

如果你自己设置了其他目录，也需要一并迁移。

三、OpenClaw 迁移完整步骤（推荐方案）

步骤 1 停止 Gateway 服务

在旧机器上先停止服务，避免复制时数据发生变化。

openclaw gateway stop

步骤 2 备份数据

建议先打包状态目录和工作区。

cd ~

tar -czf openclaw-state.tgz .openclaw

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

如果使用多个 profile，例如：

.openclaw-main
.openclaw-work

也需要分别备份。

步骤 3 在新机器安装 OpenClaw

在新服务器上安装 CLI：

curl -fsSL https://openclaw.ai/install.sh | bash

如果安装过程中生成了新的 .openclaw 目录，不用担心，后面会覆盖。

步骤 4 复制数据到新机器

可以使用多种方式：

方式一：scp

scp openclaw-state.tgz user@new-server:~
scp openclaw-workspace.tgz user@new-server:~

然后解压：

tar -xzf openclaw-state.tgz
tar -xzf openclaw-workspace.tgz

方式二：rsync

rsync -a ~/.openclaw user@new-server:~

复制完成后需要确认：

• .openclaw 目录已复制

• 文件权限正确

• 文件属于当前用户

步骤 5 运行系统修复工具

在新机器执行：

openclaw doctor

这个命令会自动：

• 修复服务配置

• 执行配置迁移

• 检查系统兼容性

然后重启 Gateway：

openclaw gateway restart

查看状态：

openclaw status

四、迁移完成后的验证

在新机器检查以下内容：

1 Gateway 服务运行

openclaw status

确保 Gateway 正常运行。

2 渠道仍然在线

例如：

• WhatsApp

• Telegram

• API 连接

正常情况下不需要重新登录。

3 会话历史存在

打开：

• Dashboard

• WebUI

确认之前的聊天记录仍然存在。

4 工作区文件存在

检查：

~/.openclaw/workspace

确认以下文件仍在：

MEMORY.md
USER.md
memory/

五、常见迁移问题

1 只复制了 openclaw.json

这是很多人最容易犯的错误。

很多关键数据并不在配置文件，而是在：

credentials/
agents/
sessions/

因此必须复制：

整个 .openclaw 目录

2 profile 不一致

如果旧机器使用：

--profile main

而新机器使用默认配置，会出现：

• 会话丢失

• 渠道未登录

• 配置不生效

解决办法：

使用相同 profile 运行 Gateway，然后执行：

openclaw doctor

3 权限问题

如果用 root 复制文件，可能导致 Gateway 无法读取凭证。

解决方法：

chown -R user:user ~/.openclaw

确保目录属于当前用户。

4 本地与远程 Gateway 混淆

如果你使用：

• WebUI

• 远程 Gateway

会话数据实际上在 远程服务器。

迁移本地电脑不会迁移远程 Gateway 数据。

正确做法是：

迁移 Gateway 所在服务器。

六、安全注意事项

.openclaw 目录中包含：

• API Key

• OAuth Token

• 渠道登录信息

因此备份时应注意：

• 不要上传到公开仓库

• 不要通过不安全渠道发送

• 建议加密存储

如果怀疑密钥泄露，应该立即轮换 API Key。

结语

OpenClaw 的迁移设计得非常简单，只要理解一个核心原则：

复制状态目录 + 复制工作区

基本就可以完成完整环境迁移。

相比重新配置智能体、重新登录渠道，这种方式可以节省大量时间，也避免配置丢失的问题。

如果你正在计划升级服务器、迁移云平台，按照本文的步骤操作，通常几分钟就可以完成整个迁移过程。