# OpenClaw 子代理使用完全教程

> 作者：小小叶 🌱  
> 版本：v1.0  
> 更新时间：2026-05-26

---

## 📖 目录

1. [什么是子代理](#一什么是子代理)
2. [子代理 vs 主代理](#二子代理-vs-主代理)
3. [基础使用](#三基础使用)
4. [项目与代理的关系](#四项目与代理的关系)
5. [高级用法](#五高级用法)
6. [实战案例](#六实战案例)
7. [常见问题](#七常见问题)

---

## 一、什么是子代理

### 1.1 概念

**子代理（Subagent）** 是 OpenClaw 中的后台工作单元，专门处理复杂、耗时或独立的任务。

```
┌─────────────────────────────────────────┐
│              用户（你）                  │
│                 ↓                       │
│           通过 QQ/微信对话               │
│                 ↓                       │
│  ┌─────────────────────────────────┐   │
│  │        主代理（小小叶）          │   │ ← 你看到的"我"
│  │      统一入口，协调调度          │   │
│  └──────────────┬──────────────────┘   │
│                 ↓                       │
│        启动子代理（后台运行）            │
│                 ↓                       │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│  │ 文献虾  │ │ 分析虾  │ │ 写作虾  │ │ ← 你看不到的"苦力"
│  └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────┘
```

### 1.2 为什么需要子代理

| 场景 | 不用子代理 | 使用子代理 |
|---|---|---|
| **文献检索** | 主虾卡住，无法回复你 | 文献虾后台跑，主虾继续聊天 |
| **数据分析** | 占用对话上下文 | 分析虾独立运行，不污染上下文 |
| **文档生成** | 一步一步等待 | 写作虾并行处理，最后给结果 |
| **多任务** | 只能串行执行 | 可并行启动多只虾 |

---

## 二、子代理 vs 主代理

### 2.1 对比表

| 特性 | 主代理（我） | 子代理 |
|---|---|---|
| **对话** | ✅ 可以直接对话 | ❌ 不能直接对话 |
| **可见性** | QQ里能看到 | 后台运行，看不到 |
| **上下文** | 继承你的对话历史 | 独立的上下文 |
| **任务** | 协调、管理、汇报 | 执行具体任务 |
| **数量** | 只有1个 | 可同时启动多个 |
| **超时** | 无限制 | 需要设置超时时间 |

### 2.2 工作流程

```
你："帮我查文献"
    ↓
主代理："好的，启动文献虾"
    ↓
文献虾（后台）：搜索 → 整理 → 保存结果
    ↓
文献虾完成 → 自动通知主代理
    ↓
主代理："文献虾已完成，找到19篇文献..."
    ↓
你：收到结果
```

---

## 三、基础使用

### 3.1 启动子代理

**基本命令：**
```javascript
sessions_spawn({
  runtime: "subagent",           // 必须：指定为子代理
  task: "任务描述",               // 必须：给子代理的指令
  label: "代理名称",              // 可选：给代理起个名字
  mode: "run",                   // 必须：run = 一次性任务
  runTimeoutSeconds: 120          // 必须：超时时间（秒）
})
```

**示例：启动一只文献虾**
```javascript
sessions_spawn({
  runtime: "subagent",
  task: "搜索空间数据挖掘相关文献，整理成JSON格式保存",
  label: "LiteratureBot",
  mode: "run",
  runTimeoutSeconds: 120
})
```

### 3.2 查看子代理状态

```javascript
subagents({
  action: "list"    // 查看所有子代理
})
```

**返回结果：**
```json
{
  "active": [
    {
      "label": "LiteratureBot",
      "status": "running",      // running / done / timeout
      "runtime": "2m",
      "model": "bailian/kimi-k2.5"
    }
  ]
}
```

### 3.3 管理子代理

| 操作 | 命令 |
|---|---|
| **查看列表** | `subagents({action: "list"})` |
| **强制终止** | `subagents({action: "kill", target: "代理名称"})` |
| **发送指令** | `subagents({action: "steer", target: "代理名称", message: "指令"})` |

---

## 四、项目与代理的关系

### 4.1 项目隔离

```
~/.openclaw/workspace/projects/
├── Project_A/           # 项目A
│   ├── data/            # 项目A的数据
│   ├── literature/      # 项目A的文献
│   └── drafts/          # 项目A的草稿
│
└── Project_B/           # 项目B（完全隔离）
    ├── data/
    ├── literature/
    └── drafts/
```

### 4.2 子代理绑定项目

**方式1：通过工作目录绑定**
```javascript
sessions_spawn({
  runtime: "subagent",
  task: "...",
  cwd: "~/.openclaw/workspace/projects/Project_A",  // 关键！
  label: "ProjectA_Bot"
})
```

**方式2：任务中指定路径**
```javascript
task: `
  1. 读取项目配置：~/.openclaw/workspace/projects/Project_A/config.json
  2. 保存结果到：~/.openclaw/workspace/projects/Project_A/data/
`
```

### 4.3 数据传递

子代理之间通过**文件**传递数据：

```
文献虾 → literature/result.json
              ↓
分析虾 读取 → 分析 → data/analysis.json
              ↓
写作虾 读取 → 生成 → drafts/final.docx
```

---

## 五、高级用法

### 5.1 给代码模板（推荐）

**❌ 不好的方式：**
```javascript
task: "创建一个Word文档，标题2号字，正文5号字"
// 子代理需要自己思考怎么写代码，容易超时
```

**✅ 好的方式：**
```javascript
task: `
执行这段代码：
\`\`\`javascript
const { Document, Packer, Paragraph } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({ text: "标题", heading: HeadingLevel.HEADING_2 }),
      new Paragraph({ text: "内容" })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('/path/output.docx', buffer);
  console.log('完成');
});
\`\`\`
`
// 子代理只需复制粘贴执行，成功率高
```

### 5.2 并行启动多个子代理

```javascript
// 同时启动3只虾，分别搜索不同数据库
sessions_spawn({...});  // 文献虾-知乎
sessions_spawn({...});  // 文献虾-arXiv
sessions_spawn({...});  // 文献虾-PubMed

// 然后合并结果
```

### 5.3 条件分支

```javascript
// 主代理检查子代理结果，决定下一步
const result = await sessions_spawn({...});

if (result.papersCount < 5) {
  // 文献太少，扩大搜索范围
  sessions_spawn({...});
} else {
  // 文献足够，进入分析阶段
  sessions_spawn({...});
}
```

### 5.4 错误处理

```javascript
// 设置超时和重试
sessions_spawn({
  runtime: "subagent",
  task: "...",
  mode: "run",
  runTimeoutSeconds: 180,  // 3分钟超时
  retry: 3               // 失败重试3次
})
```

---

## 六、实战案例

### 案例1：文献综述流水线（3只虾协作）

```javascript
// Phase 1: 文献虾
const litResult = await sessions_spawn({
  runtime: "subagent",
  task: "搜索文献并保存到 literature/summary.json",
  label: "LiteratureBot",
  mode: "run",
  runTimeoutSeconds: 120
});

// Phase 2: 分析虾
const anaResult = await sessions_spawn({
  runtime: "subagent",
  task: "读取literature/summary.json，分析保存到data/analysis.json",
  label: "AnalysisBot",
  mode: "run",
  runTimeoutSeconds: 120
});

// Phase 3: 写作虾
const writeResult = await sessions_spawn({
  runtime: "subagent",
  task: "读取data/analysis.json，生成Word文档保存到drafts/",
  label: "WriterBot",
  mode: "run",
  runTimeoutSeconds: 180
});

// 完成！
console.log("文献综述已生成：", writeResult.filePath);
```

### 案例2：带质检的文档生成

```javascript
// 写作虾生成
const draft = await sessions_spawn({...});

// 质检虾检查
const check = await sessions_spawn({
  task: "检查文档格式，返回是否合格"
});

if (!check.qualified) {
  // 不合格，重写
  await sessions_spawn({task: "根据反馈修改文档"});
}
```

---

## 七、常见问题

### Q1: 子代理超时怎么办？

**A:** 
- 增加 `runTimeoutSeconds`（建议 120-300秒）
- 简化任务，给代码模板
- 检查是否有阻塞操作（如等待用户输入）

### Q2: 子代理能访问哪些文件？

**A:** 
- 可以访问 `~/.openclaw/workspace/` 下的文件
- 通过 `cwd` 参数限制工作目录
- 不能访问系统敏感目录

### Q3: 子代理之间能通信吗？

**A:** 
- 不能直接通信
- 通过共享文件传递数据
- 主代理负责协调

### Q4: 子代理失败了怎么办？

**A:**
```javascript
// 检查状态
const status = await subagents({action: "list"});

// 如果失败，重新启动
if (status.recent[0].status === "timeout") {
  sessions_spawn({...});  // 重试
}
```

### Q5: 子代理能调用技能吗？

**A:** 
- ✅ 可以调用所有已安装技能
- ✅ 和主代理使用相同的技能库
- ✅ 在任务中直接使用 `agent.skill('skill-name')`

---

## 🎯 最佳实践

1. **任务要简单明确** - 一次只做一件事
2. **给代码模板** - 减少子代理的思考负担
3. **设置合理超时** - 根据任务复杂度调整
4. **通过文件传递数据** - JSON格式方便解析
5. **主代理负责协调** - 子代理只干活不决策

---

## 📚 相关文档

- OpenClaw 官方文档
- MediaCrawler Skill 文档
- docx-editor Skill 文档

---

**祝你使用愉快！有任何问题随时问我 🦞**