OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

维护

迁移指南

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

从其他智能体系统导入

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

从 Claude 迁移

导入 Claude Code 和 Claude Desktop 状态，包括 CLAUDE.md、MCP 服务器、Skills 和项目命令。
从 Hermes 迁移

导入 Hermes 配置、提供商、MCP 服务器、记忆、Skills 和支持的 .env 密钥。

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

将 OpenClaw 迁移到新机器

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

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

迁移步骤

  • 停止 Gateway 网关并备份

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

    bash
    openclaw gateway stopcd ~tar -czf openclaw-state.tgz .openclaw

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

  • 在新机器上安装 OpenClaw

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

  • 复制状态目录和工作区

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

    bash
    cd ~tar -xzf openclaw-state.tgz

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

  • 运行 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 也会发出警告。

    常见问题

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

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

    仅复制 openclaw.json

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

    权限和所有权

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

    远程模式

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

    备份中的机密信息

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

    验证清单

    在新机器上确认：

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

    原地升级插件

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

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

    相关内容

    Was this useful?
    On this page

    On this page