跳转至

迁移指南

OpenClaw 支持三种迁移路径：从另一个代理系统导入、将现有安装迁移到新机器，以及就地升级插件。

从其他代理系统导入

内置的迁移提供程序会将说明、MCP 服务器、技能、模型配置以及（可选）API 密钥导入 OpenClaw。在执行任何更改之前会预览迁移计划，报告中的机密信息会被遮蔽隐藏。独立运行的 openclaw migrate 以经过验证的备份为后盾；而全新的引导导入则改为先在暂存区中放置并验证本地工件，然后在任何不可逆的外部激活发生之前提交配置并发布。

从 Claude 迁移

导入 Claude Code 和 Claude Desktop 的状态，包括 CLAUDE.md、MCP 服务器、技能和项目命令。

从 Hermes 迁移

导入 Hermes 配置、提供程序、MCP 服务器、记忆、技能以及受支持的 .env 密钥。

CLI 入口点是 openclaw migrate。当检测到已知来源时，引导流程也可以提供迁移选项（openclaw onboard --flow import）。

将 OpenClaw 迁移到新机器

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

  • 配置 — openclaw.json 和所有网关设置。
  • 认证 — 共享的和每个代理的 SQLite 认证存储（API 密钥加 OAuth），以及 credentials/ 下的任何渠道或提供程序状态。
  • 会话 — 对话历史和代理状态。
  • 渠道状态 — WhatsApp 登录、Telegram 会话等。
  • 工作区文件 — MEMORY.md、USER.md、技能和提示词。

Tip

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

迁移步骤

1. 停止网关并备份

在旧机器上，停止网关，然后创建并验证备份归档：

openclaw gateway stop
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

在进行机器迁移快照之前，先停止网关。对正在变化的 SQLite 数据库进行原始复制可能会捕获到不匹配的数据库和 WAL 文件；使网关静默也能保持状态树其余部分的稳定。如果你使用多个配置文件，请在选中每个配置文件时各运行一次该命令。

2. 在新机器上安装 OpenClaw

在新机器上安装 CLI（如有需要也安装 Node）。即使引导过程创建了全新的 ~/.openclaw/ 也没关系 —— 你接下来会覆盖它。

3. 传输并恢复到暂存区

通过 `scp`、外部驱动器或其他受保护的通道传输生成的 `.tar.gz` 归档。在新机器上，将其恢复到全新的暂存目录：

```bash
openclaw backup restore <archive.tar.gz> --target ~/openclaw-restored
```

恢复绝不会就地激活。在网关停止的情况下，使用恢复出的 `manifest.json` 映射将状态和工作区资产移动到其记录的目标位置，或者将 `OPENCLAW_STATE_DIR` 指向恢复出的状态资产。确认所有者与将要运行网关的用户一致。

绝对符号链接会保留其原始目标位置，包括指向单独备份的配置或凭据的链接。在另一台机器或另一个路径上激活状态之前，请检查这些链接，确保其目标在新位置是正确的。参见[备份符号链接注意事项](../cli/backup.md#what-gets-backed-up)。

Warning

恢复较旧的渠道状态可能会使 WhatsApp 等滚动更新凭据失去同步。审批以及投递/去重状态也会回滚，并且必须重新安装插件的 node_modules 依赖树。参见恢复完整归档。

4. 运行 Doctor 并验证

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

openclaw doctor
openclaw gateway restart
openclaw status

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

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

当已启用的默认 Telegram 或 Discord 账户没有配置令牌，且对应的环境变量对 doctor 进程不可用时，openclaw doctor 也会发出警告。

常见陷阱

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

如果旧网关使用了 --profile 或 OPENCLAW_STATE_DIR，而新网关没有，渠道会显示为已登出，会话也会是空的。请使用你迁移时的相同配置文件或状态目录启动网关，然后重新运行 openclaw doctor。

仅复制 openclaw.json

仅配置文件是不够的。共享的模型认证位于 state/openclaw.sqlite，代理本地配置文件位于 agents/<agentId>/agent/openclaw-agent.sqlite，渠道和提供程序状态位于 credentials/ 下。务必使用上述备份和恢复流程迁移整个状态目录。

权限和所有权

如果你以 root 身份复制或切换了用户，网关可能无法读取凭据。请确保状态目录和工作区归属于运行网关的用户。

远程模式

如果你的 UI 指向远程网关，那么会话和工作区归远程主机所有。请迁移网关主机本身，而不是你的本地笔记本电脑。参见常见问题。

备份中的机密信息

状态目录包含认证配置文件、渠道凭据和其他提供程序状态。请加密存储备份，避免使用不安全的传输通道，如果怀疑泄露请轮换密钥。

验证清单

在新机器上，确认：

  • [ ] openclaw status 显示网关正在运行。
  • [ ] 渠道仍然保持连接（无需重新配对）。
  • [ ] 仪表盘可以打开并显示现有会话。
  • [ ] 工作区文件（记忆、配置）已存在。

原地升级插件

原地插件升级会保留相同的插件 ID 和配置键，但可能会将磁盘上的状态迁移到当前布局中。插件专属升级指南与其频道放在一起：

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw