OpenClaw 提供三种迁移方式：跨系统导入（支持 Claude、Hermes 等现有 agent 系统）、机器间迁移（复制状态目录和工作区）、插件原地升级。机器迁移需先停止旧机 gateway，打包 ~/.openclaw/，在新机解压后运行 openclaw doctor 修复；跨系统导入使用 openclaw migrate 命令，预览变更、隐藏敏感信息，apply 前自动备份；插件升级参考对应频道的迁移文档。迁移后务必用 openclaw status 和频道连接状态验证。

OpenClaw 迁移指南：从其他系统导入、换机迁移与插件升级

OpenClaw 支持三种迁移路径：从其他 agent 系统导入状态、将现有安装迁移到新机器、以及原地升级插件。

从其他 agent 系统导入

使用内置的迁移提供程序，可以将指令、MCP 服务器、技能、模型配置以及（可选）API 密钥导入 OpenClaw。任何变更前都会预览计划，报告中的机密信息会被遮盖，apply 操作受备份保护。

从 Claude 迁移 — 导入 Claude Code 和 Claude Desktop 的状态，包括 CLAUDE.md、MCP 服务器、技能和项目命令。
从 Hermes 迁移 — 导入 Hermes 配置、provider、MCP 服务器、记忆、技能和支持的 .env 键。

CLI 入口为 openclaw migrate。引导程序（openclaw onboard --flow import）在检测到已知来源时也可以直接发起迁移。

将 OpenClaw 迁移到新机器

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

配置 — openclaw.json 及所有网关设置。
认证 — 每个 agent 的 auth-profiles.json（API 密钥 + OAuth），以及 credentials/ 下的频道或 provider 状态。
会话 — 对话历史和 agent 状态。
频道状态 — WhatsApp 登录、Telegram 会话等。
工作区文件 — MEMORY.md、USER.md、技能和提示词。

TIP

在旧机器上运行 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.js，如果需要）。即使引导程序创建了新的 ~/.openclaw/ 也没关系——下一步会覆盖它。
复制状态目录和工作区
通过 scp、rsync -a 或外部硬盘传输压缩包，然后解压：
bash
```
cd ~
tar -xzf openclaw-state.tgz
```
确保隐藏目录被包含在内，文件所有者与运行 gateway 的用户一致。
运行 doctor 并验证
在新机器上运行 Doctor 应用配置迁移并修复服务：
bash
```
openclaw doctor
openclaw gateway restart
openclaw status
```

如果 Telegram 或 Discord 使用默认环境变量回退（TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN），验证迁移后的状态目录 .env 中包含这些键（不打印秘密值）：

bash

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

openclaw doctor 还会在启用了默认 Telegram 或 Discord 账号但未配置 token 且对应环境变量不可用时发出警告。

常见陷阱

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

如果旧 gateway 使用了 --profile 或 OPENCLAW_STATE_DIR 而新机器未使用，频道会显示已登出，会话为空。请以迁移时使用的相同 profile 或状态目录启动 gateway，然后重新运行 openclaw doctor。

只复制了 openclaw.json

仅配置文件不够。模型认证配置位于 agents/<agentId>/agent/auth-profiles.json，频道和 provider 状态位于 credentials/。务必迁移整个状态目录。

权限和所有权

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

远端模式

如果 UI 指向远端 gateway，远端主机拥有会话和工作区。迁移 gateway 主机本身，而非本地笔记本。参见 FAQ。

备份中的机密

状态目录包含认证配置、频道凭据和其他 provider 状态。请加密存储备份，避免使用不安全的传输渠道；怀疑泄露时请轮换密钥。

验证清单

在新机器上确认：

[ ] openclaw status 显示 gateway 正在运行。
[ ] 频道仍然连接（无需重新配对）。
[ ] Dashboard 打开后显示已有会话。
[ ] 工作区文件（记忆、配置）已存在。

原地升级插件

原地升级插件会保留相同的插件 ID 和配置键，但可能将磁盘上的状态迁移到当前布局。插件专属的迁移指南位于对应频道文档中：

Matrix 迁移：加密状态恢复限制、自动快照行为和手动恢复命令。

常见问题

迁移到新机器后频道都断开连接了怎么解决？

最常见原因是 profile 或状态目录不匹配。确认新机器使用与旧机器相同的 --profile 参数或 OPENCLAUD_STATE_DIR 环境变量。运行 openclaw doctor 修复配置，并检查 .env 中 TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN 是否可用。

跨系统导入时 API 密钥会被一起迁移吗？

可以启用导入 API 密钥（opt-in），但迁移报告会遮盖秘密值（显示为 ***）。apply 前会创建已验证的备份，确保可以回滚。如果希望完全手动迁移，也可以先关闭密钥导入选项。

迁移后运行 `openclaw doctor` 提示 token 缺失，但实际有 token？

可能原因是 doctor 进程无法读取环境变量。检查是否在 ~/.openclaw/.env 中设置了令牌且该文件可读。如果是通过 systemd 或 Docker 运行 gateway，确保环境变量传递给 doctor 进程。

OpenClaw 迁移指南：从其他系统导入、换机迁移与插件升级 ​

从其他 agent 系统导入 ​

将 OpenClaw 迁移到新机器 ​

迁移步骤 ​

常见陷阱 ​

验证清单 ​

原地升级插件 ​

常见问题 ​

迁移到新机器后频道都断开连接了怎么解决？ ​

跨系统导入时 API 密钥会被一起迁移吗？ ​

迁移后运行 openclaw doctor 提示 token 缺失，但实际有 token？ ​

相关 ​