Quick Resurrection
> 触发： 用户说「我要搬家」「换电脑了」「重装系统」「帮我打包带走团队」等。
>
> 版本：v3.0 — 审查确认 + diff 展示 + 细粒度控制（--dry-run/--no-cron/--no-restart）。
快速开始
打包（旧环境）
cd ~/.qclaw/workspace/skills/quick-resurrection
python3 pack.py
生成搬家包 → 复制到新环境。
迁移（新环境）
# 审查模式：只看不做（推荐首次使用）
python3 migrate.py /path/to/搬家包.zip --dry-run
# 基本用法
python3 migrate.py /path/to/搬家包.zip
# 跳过危险操作
python3 migrate.py /path/to/搬家包.zip --no-cron --no-restart
⚠️ 重要提示
打包内容含敏感信息。 搬家包会包含 MEMORY.md（含个人记忆/偏好）、TOOLS.md（含 API keys、账号密码、服务器地址）等文件，可能含有 API keys、账号密码、内部流程等敏感内容。不要公开分享搬家包，传输时使用加密介质。
安全使用建议：
1. 务必先 --dry-run — 在新环境运行前，先用 python3 migrate.py 搬家包.zip --dry-run 审查 diff，确认无误后再正式执行。
2. 敏感操作可跳过 — 使用 --no-cron 跳过 cron 创建、--no-restart 跳过 Gateway 重启，逐步验证。
3. 检查搬家包内容 — 解压后先检查 MEMORY.md、TOOLS.md、openclaw-agents.json、cron payload 是否包含不想迁移的敏感内容。
4. 确认备份存在 — 操作前确认 ~/.qclaw/backup/ 下有备份目录，如需回滚可恢复。
5. 检查绝对路径 — 验证 openclaw-agents.json 中的 workspace 路径指向的是目标环境而非旧环境的路径。
6. 低信任环境 — 如对搬家包来源不确定，先逐行审计 pack.py/migrate.py，或在隔离环境中测试。
一、核心概念
三要素激活原理
子代理正确激活必须同时满足三个条件：
| 要素 | 参数 | 作用 |
|---|---|---|
| 身份 | agentId |
控制读哪个 SOUL.md（人格） |
| 隔离 | cwd |
控制 workspace 根目录 |
| 权限 | allowAgents |
白名单，允许 spawn |
关键发现（2026-04-21 实测验证）：
- agentId 控制人格，不控制 workspace
- cwd 才控制 workspace 隔离
- 不设 cwd → 子代理永远读父代理的 workspace
通用化设计
| 场景 | pack.py 行为 | migrate.py 行为 |
|---|---|---|
| 有团队成员 | 打包团队成员 | 复制团队成员 |
| 无团队成员 | 跳过 | 跳过，提示 |
| 有 cron | 打包 | 创建（跳过已存在） |
| 无 cron | 跳过 | 跳过，提示 |
备份与回滚
搬家前自动备份：
- 目标：~/.qclaw/backup/搬家备份_YYYYMMDD_HHMMSS/
- 内容：所有 workspace-* + openclaw.json
回滚方法：
cp -r ~/.qclaw/backup/搬家备份_xxx/* ~/.qclaw/
openclaw gateway restart
配置合并策略
核心原则：不覆盖新环境的其他配置。
- agents 配置：deep merge
- hooks.allowedAgentIds：union merge（取并集）
- 其他配置（channel、plugins 等）：原样保留
二、脚本说明
打包脚本 pack.py
python3 pack.py
自动检测内容：
1. 从 openclaw.json 找到 active workspace（自动推断，不再硬编码）
2. 收集身份文件（SOUL/MEMORY/TOOLS 等）
3. 收集团队成员（有则打包，无则跳过）
4. 收集 skills（有则打包，无则跳过）
5. 获取 cron 任务配置
6. 动态生成 README.md
输出： ~/一键搬家包/{Agent名称}搬家包_YYYYMMDD.zip
迁移脚本 migrate.py
# 方式A（推荐）：解压后直接运行
unzip 搬家包.zip
cd 搬家包
python3 migrate.py
# 方式B：zip 在当前目录
python3 migrate.py
# 方式C：传入路径
python3 migrate.py /path/to/搬家包.zip
执行步骤：
| Step | 内容 |
|---|---|
| 0 | 备份现有配置（自动） |
| 0.5 | 选择如何处理 main agent（交互） |
| 1 | 复制身份文件 |
| 2 | 复制团队成员 |
| 3 | 复制 skills |
| 4 | 合并 agent 配置 |
| 5 | 创建 cron 任务 |
| 6 | 重启 Gateway |
Main Agent 三个选项（均有完整执行逻辑）：
1. 指向现有 agent（把当前 agent 变成你的主控）
2. 新建 main agent 实例（另起一个，保留当前配置）
3. 覆盖现有 main agent（⚠️ 替换现有主控）
⚠️ 已废弃脚本（v2.0 不再使用）：
- setup_config.py — 配置更新已并入 migrate.py
- init.sh — 创建 main agent 已并入 migrate.py
三、搬家包结构
搬家包/
├── README.md ← 动态生成
├── migrate.py ← v2.0
│
├── 身份层/ ← Main Agent 核心文件
│ ├── SOUL.md
│ ├── MEMORY.md
│ ├── TOOLS.md
│ ├── AGENTS.md
│ ├── IDENTITY.md
│ ├── USER.md
│ └── memory/ ← 历史记录
│
├── 团队成员层/ ← 自动检测，有则包含
│ ├── 成员A/
│ │ └── SOUL.md
│ └── ...
│
├── skills/ ← 自动检测，有则包含
│
├── openclaw-agents.json ← Agent 配置片段
├── cron_jobs.json ← Cron 任务清单
└── 工作目录说明.md ← git 仓库提示
四、配置说明
openclaw.json 关键配置
{
"agents": {
"defaults": {
"subagents": { "allowAgents": ["成员A", "成员B"] } // 最小白名单，仅实际成员ID
},
"list": [
{ "id": "main", "name": "Main Agent" },
{ "id": "成员A", "name": "成员A", "workspace": "...", "agentDir": "..." }
]
},
"hooks": {
"allowedAgentIds": ["成员A", "成员B", ...]
}
}
models.json（每个 agent 独立）
{
"providers": {
"qclaw": {
"baseUrl": "http://127.0.0.1:19000/proxy/llm",
"apiKey": "__QCLAW_AUTH_GATEWAY_MANAGED__",
"api": "openai-completions",
"models": [{ "id": "modelroute", "name": "modelroute", "input": ["text", "image"] }]
}
}
}
五、常见问题
| 问题 | 原因 | 解法 |
|---|---|---|
agentId is not allowed |
缺 allowAgents 白名单 | migrate.py 自动补上最小白名单（仅实际成员ID） |
| 子代理读错 SOUL.md | 没传 cwd 参数 | spawn 时必须传 agentId + cwd |
| Gateway 重启后 spawn 报错 | channel 注册需时间 | 等 5-10 秒再 spawn |
| 子代理空跑 | 任务描述不够具体 | 预写脚本让子代理执行 |
| 搬家后配置丢失 | v1.0 用 replace 而非 merge | v2.0 已修复 |
六、验证清单
搬家完成后逐一检查：
# Gateway 状态
openclaw gateway status
# SOUL.md 是否存在
ls ~/.qclaw/workspace-*/SOUL.md
# 团队成员
ls ~/.qclaw/workspace-*/
# 测试子代理激活
# 在 agent 对话中说："测试激活团队成员"
# cron 任务
openclaw tasks list
# 回滚（如需要）
ls ~/.qclaw/backup/
cp -r ~/.qclaw/backup/搬家备份_xxx/* ~/.qclaw/
openclaw gateway restart
