# 迁移指南

> 迁移中心：跨系统导入、机器间迁移和插件升级

- 网址：https://funcoding.ai/agents/openclaw/install/migrating/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/install/migrating

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

## 从其他智能体系统导入

内置迁移提供商可将指令、MCP 服务器、Skills、模型配置以及（选择启用的）API 密钥导入 OpenClaw。执行任何更改前都会预览计划，报告中的机密信息会被遮盖。独立执行的 `openclaw migrate` 以经过验证的备份为保障；而全新新手引导中的导入会先暂存并验证本地工件，在提交配置后再发布这些工件，之后才会执行任何不可逆的外部激活操作。

- [从 Claude 迁移](https://funcoding.ai/agents/openclaw/install/migrating-claude/)：导入 Claude Code 和 Claude Desktop 状态，包括 `CLAUDE.md`、MCP 服务器、Skills 和项目命令。
- [从 Hermes 迁移](https://funcoding.ai/agents/openclaw/install/migrating-hermes/)：导入 Hermes 配置、提供商、MCP 服务器、记忆、Skills 和支持的 `.env` 密钥。

CLI 入口点为 [`openclaw migrate`](https://funcoding.ai/agents/openclaw/cli/migrate/)。新手引导检测到已知来源（`openclaw onboard --flow import`）时，也可以提供迁移选项。

## 将 OpenClaw 迁移到新机器

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

- **配置** — `openclaw.json` 和所有 Gateway 网关设置。
- **身份验证** — 每个智能体的 `auth-profiles.json`（API 密钥和 OAuth），以及 `credentials/` 下的所有渠道或提供商状态。
- **会话** — 对话历史记录和智能体状态。
- **渠道状态** — WhatsApp 登录信息、Telegram 会话等。
- **工作区文件** — `MEMORY.md`、`USER.md`、Skills 和提示词。

<div class="callout callout-tip">

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

</div>

### 迁移步骤

**停止 Gateway 网关并备份**

在**旧**机器上停止 Gateway 网关，以免文件在复制过程中发生变化，然后创建归档：

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

如果使用多个配置文件（例如 `~/.openclaw-work`），请分别归档每个配置文件。

**在新机器上安装 OpenClaw**

在新机器上[安装](https://funcoding.ai/agents/openclaw/install/) CLI（如有需要，也安装 Node）。即使新手引导创建了全新的 `~/.openclaw/` 也没关系，因为下一步会将其覆盖。

**复制状态目录和工作区**

通过 `scp`、`rsync -a` 或外部驱动器传输归档，然后解压：

```bash
cd ~
tar -xzf openclaw-state.tgz
```

确认归档中包含隐藏目录，并且文件所有权与将运行 Gateway 网关的用户一致。

**运行 Doctor 并验证**

在新机器上运行 [Doctor](https://funcoding.ai/agents/openclaw/gateway/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
```

如果已启用的默认 Telegram 或 Discord 账号未配置令牌，并且 Doctor 进程无法访问对应的环境变量，`openclaw doctor` 也会发出警告。

### 常见问题

<details>
<summary>配置文件或状态目录不匹配</summary>

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

</details>

<details>
<summary>仅复制 openclaw.json</summary>

仅复制配置文件并不够。模型身份验证配置文件位于 `agents/<agentId>/agent/auth-profiles.json` 下，渠道和提供商状态位于 `credentials/` 下。始终迁移**整个**状态目录。

</details>

<details>
<summary>权限和所有权</summary>

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

</details>

<details>
<summary>远程模式</summary>

如果 UI 指向**远程** Gateway 网关，则会话和工作区归远程主机所有。请迁移 Gateway 网关主机本身，而不是本地笔记本电脑。请参阅[常见问题](https://funcoding.ai/agents/openclaw/help/faq/#where-things-live-on-disk)。

</details>

<details>
<summary>备份中的机密信息</summary>

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

</details>

### 验证清单

在新机器上确认：

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

## 原地升级插件

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

- [Matrix 迁移](https://funcoding.ai/agents/openclaw/channels/matrix-migration/)：加密状态恢复限制、自动快照行为和手动恢复命令。

## 相关内容

- [`openclaw migrate`](https://funcoding.ai/agents/openclaw/cli/migrate/)：跨系统导入的 CLI 参考。
- [安装概览](https://funcoding.ai/agents/openclaw/install/)：所有安装方式。
- [Doctor](https://funcoding.ai/agents/openclaw/gateway/doctor/)：迁移后的健康检查。
- [卸载](https://funcoding.ai/agents/openclaw/install/uninstall/)：彻底移除 OpenClaw。