打包并恢复你的 OpenClaw Agent 工作区配置。换电脑或重装系统后,一个命令把整个团队迁移到新环境。执行前展示配置内容供用户确认,确认后全自动执行。
---
name: quick-resurrection
打包并恢复你的 OpenClaw Agent 工作区配置。换电脑或重装系统后,一个命令把整个团队迁移到新环境。执行前展示配置 diff 供用户确认,支持 --dry-run/--no-cron/--no-restart 细粒度控制。
metadata:
openclaw:
requires:
bins: [openclaw]
install: []
version: "1.0.6"
permissions:
- action: "修改 ~/.qclaw/openclaw.json(添加 agent 配置)"
risk: "修改运行时配置,影响 agent spawn 行为"
mitigation: "修改前展示完整 diff,用户确认后再写入;allowAgents 默认最小白名单,不用通配符"
- action: "读写 ~/.qclaw/ 目录(复制 workspace、备份配置)"
risk: "可能暴露 MEMORY.md/TOOLS.md 等敏感文件"
mitigation: "打包时标注敏感文件,搬家包妥善保管"
- action: "创建 cron 定时任务"
risk: "定时任务可自动执行任意命令"
mitigation: "执行前展示所有 cron 任务内容(含 payload),用户确认后自动创建"
- action: "打包含敏感文件(MEMORY.md/TOOLS.md 可能含 API keys、账号密码)"
risk: "搬家包泄露会暴露所有敏感配置和私人记忆"
mitigation: "SKILL.md 明确警告不要分享搬家包;建议传输时加密"
- action: "调用 openclaw CLI(list tasks、restart gateway 等)"
risk: "依赖外部命令行工具"
mitigation: "requires.bins 已声明 openclaw 依赖"
---
# Quick Resurrection
> **触发:** 用户说「我要搬家」「换电脑了」「重装系统」「帮我打包带走团队」等。
>
> **版本:v3.0** — 审查确认 + diff 展示 + 细粒度控制(--dry-run/--no-cron/--no-restart)。
---
## 快速开始
### 打包(旧环境)
```bash
cd ~/.qclaw/workspace/skills/quick-resurrection
python3 pack.py
```
生成搬家包 → 复制到新环境。
### 迁移(新环境)
```bash
# 审查模式:只看不做(推荐首次使用)
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
**回滚方法:**
```bash
cp -r ~/.qclaw/backup/搬家备份_xxx/* ~/.qclaw/
openclaw gateway restart
```
### 配置合并策略
**核心原则:不覆盖新环境的其他配置。**
- agents 配置:deep merge
- hooks.allowedAgentIds:union merge(取并集)
- 其他配置(channel、plugins 等):原样保留
---
## 二、脚本说明
### 打包脚本 pack.py
```bash
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
```bash
# 方式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 关键配置
```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 独立)
```json
{
"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 已修复 |
---
## 六、验证清单
搬家完成后逐一检查:
```bash
# 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
```
```
don't have the plugin yet? install it then click "run inline in claude" again.