本页内容

本页内容

维护

迁移指南

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

从另一个代理系统导入

捆绑的迁移提供商将说明、MCP 服务器、技能、模型配置和(选择加入)API 密钥引入 OpenClaw。在任何更改之前都会预览计划,并且在报告中编辑秘密。独立的 openclaw migrate 有经过验证的备份支持;新的入门导入会在发布本地工件之前暂存并验证本地工件,并在任何不可逆的外部激活之前提交配置。

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

将 OpenClaw 迁移到新机器

复制 状态目录(默认是 ~/.openclaw/)和你的 工作区,以保留:

  • 配置 — openclaw.json 和所有网关设置。
  • Auth — 共享和每个代理 SQLite 身份验证存储(API 密钥加上 OAuth),以及 credentials/ 下的任何通道或提供者状态。
  • 会话 — 对话历史和代理状态。
  • 通道状态 — WhatsApp 登录、Telegram 会话,以及类似内容。
  • 工作区文件 — MEMORY.md、USER.md、技能和提示。

迁移步骤

  • 停止网关并备份

    在 old 计算机上,停止网关,然后创建并验证备份存档:

    bash
    openclaw gateway stopmkdir -p ~/Backups/openclawopenclaw backup create --output ~/Backups/openclaw --verify

    在拍摄机器移动快照之前停止网关。更改的 SQLite 数据库的原始副本可以捕获不匹配的数据库和 WAL 文件;静默网关还可以保持状态树的其余部分稳定。如果您使用多个配置文件,请对每个选定的配置文件运行一次命令。

  • 在新机器上安装OpenClaw

    在新机器上安装 CLI(如有需要也安装 Node)。即使入门流程创建了一个新的 ~/.openclaw/ 也没关系——下一步会覆盖它。

  • 转移并恢复到暂存

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

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

    恢复永远不会就地激活。网关停止后,使用恢复的 manifest.json 映射将状态和工作区资产移动到其记录的目标,或将 OPENCLAW_STATE_DIR 指向恢复的状态资产。确认所有权与将运行网关的用户匹配。

    绝对符号链接保留其原始目标位置,包括指向单独备份的配置或凭据的链接。在另一台计算机或另一条路径上激活状态之前,请检查这些链接并确保它们的目标对于新位置来说是正确的。请参阅 备份符号链接警告 。

  • 运行 Doctor 并验证

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

    bash
    openclaw doctoropenclaw gateway restartopenclaw 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 也会发出警告。

    常见陷阱

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

    如果旧网关使用了 --profile 或 OPENCLAW_STATE_DIR,而新网关没有使用,那么通道会显示为已登出,且会话将为空。请使用你迁移过来的相同配置文件或 state-dir 启动网关,然后重新运行 openclaw doctor。

    仅复制 openclaw.json

    仅配置文件是不够的。共享模型身份验证位于 state/openclaw.sqlite 中,代理本地配置文件位于 agents/<agentId>/agent/openclaw-agent.sqlite 中,通道和提供者状态位于 credentials/ 中。始终使用上述备份和恢复流程迁移 entire 状态目录。

    权限和所有权

    如果您以 root 或切换用户身份进行复制,网关可能无法读取凭据。检查状态目录和工作区是否由运行网关的用户拥有。

    远程模式

    如果你的 UI 指向的是一个远程网关,那么远程主机拥有会话和工作区。应迁移网关主机本身,而不是你的本地笔记本电脑。参见 FAQ。

    备份中的秘密

    状态目录包含认证配置文件、通道凭据以及其他提供方状态。请将备份加密存储,避免不安全的传输通道,并在怀疑泄露时轮换密钥。

    验证清单

    在新机器上,确认:

    • [ ] openclaw status 显示网关正在运行。
    • [ ] 通道仍然已连接(无需重新配对)。
    • [ ] 仪表板可以打开并显示现有会话。
    • [ ] 工作区文件(内存、配置)都存在。

    就地升级插件

    就地插件升级会保留相同的插件 id 和配置键,但可能会将磁盘上的状态迁移到当前布局中。插件特定的升级指南与其通道一起提供:

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

    相关内容

    本页有帮助吗?