Agent 迁移

在跨服务器与跨平台迁移 OpenClaw agent 时，完整保留其身份、记忆与配置。

适用场景

✅ 建议使用该能力的场景：

• 将 agent 从本地机器迁移至远程服务器
• 将 agent 配置克隆至多个环境
• 为灾难恢复备份完整的 agent 状态
• 同步开发/生产环境间的 workspace 变更
• 升级 OpenClaw 并确保具备完整回滚能力

❌ 不建议使用的场景：

• 简单文件拷贝操作 → 直接使用 cp/rsync
• 数据库迁移 → 使用数据库专用工具
• 非 OpenClaw 应用的部署

核心概念

Agent 状态组成

Agent 状态 = 身份 + 记忆 + 配置 + 技能 + 扩展
├── workspace/           # 核心身份文件
│   ├── IDENTITY.md      # agent 的身份定义
│   ├── USER.md          # agent 所服务的对象
│   ├── SOUL.md          # agent 的个性设定
│   ├── MEMORY.md        # 长期记忆
│   ├── AGENTS.md        # 运行规则
│   ├── TOOLS.md         # 环境说明
│   └── memory/          # 每日日志
├── .openclaw/
│   ├── openclaw.json    # 网关配置
│   ├── agents/          # 会话数据
│   └── extensions/      # 自定义插件
└── skills/              # 自定义技能（如有）

迁移工作流

1. 导出（源机器）

# 全量导出 agent
./scripts/export-agent.sh [export-name]

# 生成以下内容：
# /tmp/agent-export-[name]/
#   ├── manifest.json      # 导出元数据
#   ├── workspace.tar.gz   # 核心文件
#   ├── config.tar.gz      # OpenClaw 配置
#   └── restore.sh         # 自包含恢复脚本

2. 传输

# 通过 SSH 传输
scp -r /tmp/agent-export-[name] user@new-server:/tmp/

# 通过 GitHub 传输（推荐用于版本化部署）
# 推送至代码仓库，在目标环境执行 clone

3. 导入（目标机器）

# 运行自包含恢复脚本
cd /tmp/agent-export-[name] && ./restore.sh

# 或手动导入：
./scripts/import-agent.sh /tmp/agent-export-[name]

脚本说明

导出 Agent

scripts/export-agent.sh [name] [--full]

参数选项：

• name — 导出标识符（默认：时间戳）
• --full — 包含会话历史与日志

导入 Agent

scripts/import-agent.sh  [--merge|--replace]

参数选项：

• --merge — 与现有 agent 合并（默认行为）
• --replace — 清除现有 agent，执行全新安装

同步至 GitHub

scripts/sync-github.sh  [--push|--pull]

将 agent 状态同步至 GitHub，支持版本化部署。

平台相关注意事项

Linux → Linux

可直接传输，无需格式转换。

macOS → Linux

• 检查脚本中是否存在 macOS 特有的路径
• 如使用了文件监听器，需相应更新

Windows WSL → 原生 Linux

• 换行符由系统自动处理
• 需验证可执行文件权限是否正确

Docker 部署

参见 references/docker-deploy.md 获取容器化部署说明。

安全检查清单

• 对 openclaw.json 进行脱敏处理（导出前移除敏感令牌）
• 核查目标机器的权限设置
• 迁移完成后轮换所有已暴露的凭据
• 在正式切换前测试 agent 功能完整性

回滚

导出包为不可变快照。执行回滚操作如下：

# 重新导入上一个导出包
./scripts/import-agent.sh /path/to/previous-export --replace