Agent Migration
Migrate OpenClaw agents across servers and platforms while preserving identity, memory, and configuration.
When to Use
✅ USE this skill when:
- - Moving agent from local machine to remote server
- Cloning agent configuration to multiple environments
- Backing up complete agent state for disaster recovery
- Syncing workspace changes between dev/prod
- Upgrading OpenClaw with full rollback capability
❌ DON'T use when:
- - Simple file copy operations → use
cp/rsync directly - Database migrations → use database-specific tools
- Non-OpenClaw application deployment
Core Concepts
Agent State Components
CODEBLOCK0
Migration Workflows
1. Export (Source Machine)
CODEBLOCK1
2. Transfer
CODEBLOCK2
3. Import (Target Machine)
CODEBLOCK3
Scripts
Export Agent
CODEBLOCK4
Options:
- -
name - Export identifier (default: timestamp) - INLINECODE3 - Include session history and logs
Import Agent
CODEBLOCK5
Options:
- -
--merge - Merge with existing agent (default) - INLINECODE5 - Wipe existing, clean install
Sync to GitHub
CODEBLOCK6
Syncs agent state to GitHub for versioned deployment.
Platform-Specific Notes
Linux → Linux
Direct transfer, no conversion needed.
macOS → Linux
- - Check for macOS-specific paths in scripts
- Update file watchers if used
Windows WSL → Native Linux
- - Line endings auto-handled
- Verify executable permissions
Docker Deployment
See references/docker-deploy.md for containerized deployment.
Security Checklist
- - [ ] Sanitize
openclaw.json (remove sensitive tokens before export) - [ ] Verify target machine permissions
- [ ] Rotate any exposed credentials post-migration
- [ ] Test agent functionality before production cutover
Rollback
Exports are immutable snapshots. To rollback:
CODEBLOCK7
Agent 迁移
在保持身份、记忆和配置不变的情况下，跨服务器和平台迁移 OpenClaw 代理。
何时使用
✅ 在以下情况下使用此技能：
- - 将代理从本地机器迁移到远程服务器
- 将代理配置克隆到多个环境
- 备份完整的代理状态以进行灾难恢复
- 在开发/生产环境之间同步工作区变更
- 升级 OpenClaw 并具备完整回滚能力
❌ 在以下情况下不要使用：
- - 简单的文件复制操作 → 直接使用 cp/rsync
- 数据库迁移 → 使用数据库专用工具
- 非 OpenClaw 应用程序部署
核心概念
代理状态组件
代理状态 = 身份 + 记忆 + 配置 + 技能 + 扩展
├── workspace/ # 核心身份文件
│ ├── IDENTITY.md # 代理身份
│ ├── USER.md # 服务对象
│ ├── SOUL.md # 个性特征
│ ├── MEMORY.md # 长期记忆
│ ├── AGENTS.md # 操作规则
│ ├── TOOLS.md # 环境说明
│ └── memory/ # 日常日志
├── .openclaw/
│ ├── openclaw.json # 网关配置
│ ├── agents/ # 会话数据
│ └── extensions/ # 自定义插件
└── skills/ # 自定义技能（如有）
迁移工作流程
1. 导出（源机器）
bash
完整代理导出
./scripts/export-agent.sh [导出名称]
创建以下内容：
/tmp/agent-export-[名称]/
├── manifest.json # 导出元数据
├── workspace.tar.gz # 核心文件
├── config.tar.gz # OpenClaw 配置
└── restore.sh # 自包含恢复脚本
2. 传输
bash
通过 SSH
scp -r /tmp/agent-export-[名称] user@新服务器:/tmp/
通过 GitHub（推荐用于版本化部署）
推送到仓库，在目标机器上克隆
3. 导入（目标机器）
bash
运行自包含恢复
cd /tmp/agent-export-[名称] && ./restore.sh
或手动操作：
./scripts/import-agent.sh /tmp/agent-export-[名称]
脚本
导出代理
bash
scripts/export-agent.sh [名称] [--full]
选项：
- - 名称 - 导出标识符（默认：时间戳）
- --full - 包含会话历史记录和日志
导入代理
bash
scripts/import-agent.sh <导出路径> [--merge|--replace]
选项：
- - --merge - 与现有代理合并（默认）
- --replace - 清除现有内容，全新安装
同步到 GitHub
bash
scripts/sync-github.sh <仓库URL> [--push|--pull]
将代理状态同步到 GitHub 以实现版本化部署。
平台特定说明
Linux → Linux
直接传输，无需转换。
macOS → Linux
- - 检查脚本中是否有 macOS 特定路径
- 如果使用了文件监视器，请更新
Windows WSL → 原生 Linux
Docker 部署
容器化部署请参阅 references/docker-deploy.md。
安全检查清单
- - [ ] 清理 openclaw.json（导出前移除敏感令牌）
- [ ] 验证目标机器权限
- [ ] 迁移后轮换任何暴露的凭据
- [ ] 在生产切换前测试代理功能
回滚
导出是不可变的快照。要回滚：
bash
重新导入之前的导出
./scripts/import-agent.sh /路径/到/之前的导出 --replace
