OpenClaw 的备份和迁移流程

2026-03-28 | |

折腾 OpenClaw，最重要的3个技能：备份、重装、迁移😆

所以这篇文章会简单介绍下 OpenClaw 的目录结构，然后说下备份和迁移的流程

OpenClaw 的目录结构

~/.openclaw/ [默认的主路径]
|-- openclaw.json [主配置文件, JSON5]
|-- workspace/ [默认主 agent 工作区]
|   |-- AGENTS.md [行为规则和操作记忆]
|   |-- SOUL.md [人设, 语气和边界]
|   |-- USER.md [用户画像和称呼偏好]
|   |-- IDENTITY.md [agent 名称, 主题和 emoji]
|   |-- TOOLS.md [本机工具和约定说明]
|   |-- HEARTBEAT.md [心跳或定时运行的简短检查清单]
|   |-- BOOT.md [gateway 重启时的启动检查清单]
|   |-- BOOTSTRAP.md [首次引导文件, 完成后通常会删除]
|   |-- MEMORY.md [长期记忆]
|   |-- memory/ [每日记忆日志目录]
|   |   `-- YYYY-MM-DD.md [当天追加式笔记]
|   |-- skills/ [仅这个工作区可见的 skills]
|   `-- canvas/ [节点或 Canvas UI 文件]
|-- agents/ [每个 agent 的状态目录]
|   `-- / [单 agent 默认通常是 main]
|       |-- agent/ [该 agent 的认证与运行状态]
|       |   `-- auth-profiles.json [模型 API key 和 OAuth 主存储]
|       `-- sessions/ [会话索引与转录]
|           |-- sessions.json [会话索引和路由元数据]
|           `-- .jsonl [对话转录]
|-- credentials/ [渠道登录态和 allowlist]
|   |-- whatsapp/ [WhatsApp 认证目录]
|   |   `-- /creds.json [WhatsApp 凭据]
|   |-- -allowFrom.json [默认账号配对 allowlist]
|   `-- --allowFrom.json [非默认账号配对 allowlist]
|-- skills/ [全局共享 skills, 本机所有 agent 可见]
|   `-- /SKILL.md [本地或托管 skill]
|-- extensions/ [已安装插件目录]
|   `-- / [插件代码与依赖]
|-- sandboxes/ [工具沙箱工作副本]
|   `-- ... [沙箱内读写过的文件副本]
|-- exec-approvals.json [exec 审批策略与 allowlist]
|-- exec-approvals.sock [审批 IPC socket]
|-- secrets.json [file SecretRef 的密钥载荷]
|-- mpm/ [外部插件目录缓存]
|   |-- plugins.json [外部插件目录清单]
|   `-- catalog.json [外部插件目录清单]
`-- plugins/ [额外插件目录元数据]
    `-- catalog.json [外部插件目录清单]

 

备份

很简单，备份整个 ~/.openclaw/ 目录即可

如果你要重新配置，但需保留 Agent 的记忆和角色定义，则只需备份 ~/.openclaw/workspace/ 即可

⚠️注意：在备份时，建议停止网关，防止意外修改：openclaw gateway stop

 

 

迁移

在新机器上安装好 OpenClaw 后，不要启动，或者确保网关已停止。

然后覆盖文件夹即可

迁移后的诊断和修复

1. 运行系统诊断 (Doctor)

内置的 doctor 工具会扫描配置树，并自动修复路径问题或处理旧版本的 Schema 兼容：

# 基础配置与健康状态检查
openclaw doctor

# 深度修复（跨大版本迁移）
openclaw doctor --deep --repair

2. 校验与更新配置项

检查配置文件是否结构完好。如果需要修改网关设置或网关鉴权方式，直接使用 CLI 修正：

# 校验配置文件结构是否正确
openclaw config validate ~/.openclaw/openclaw.json

# （可选）重置网关认证模式以适配新环境
openclaw config set gateway.auth.mode token

3. 迁移凭据安全密钥 (Secrets) 

如果迁移涉及底层硬件解密环境的变化（凭据存储变动），必须执行安全迁移以防 API Keys 读取失败

openclaw secrets migrate
 

重启并验证

确认一切步骤完成后，重启网关：openclaw gateway restart

检查清单：

  • 终端状态：运行 openclaw status 查看 Gateway 和核心 Agents 是否全部OK。

  • Web 仪表盘：浏览器访问 http://127.0.0.1:18789（或新服务器公网 IP，注意放行安全组端口），输入 openclaw dashboard 调出后台页面，确认旧的历史会话和 Skills 列表完整呈现。

  • 频道状态：使用绑定的通信软件，给小龙虾发送消息，确保一切正常