# OpenClaw 子代理完全操作手册

> 从命令行到配置文件，手把手教学
> 版本：v2.0 | 作者：小小叶 🌱

---

## 目录

1. [命令行操作](#一命令行操作)
2. [配置文件详解](#二配置文件详解)
3. [项目与代理的关联](#三项目与代理的关联)
4. [实战：从零创建项目](#四实战从零创建项目)
5. [常用命令速查](#五常用命令速查)

---

## 一、命令行操作

### 1.1 查看当前子代理

```bash
# 查看活跃和最近的子代理
openclaw subagents list

# 输出示例：
# active subagents:
# 1. LiteratureBot (kimi-k2.5, 2m) running
# 
# recent (last 30m):
# 1. AnalysisBot (kimi-k2.5, 5m) done
```

### 1.2 手动启动子代理（命令行方式）

**方法1：使用 openclaw run**
```bash
# 创建任务脚本
vim ~/.openclaw/workspace/tasks/literature_task.js

# 内容：
module.exports = async ({ agent }) => {
  const result = await agent.skill('tavily-search').search({
    query: "空间数据挖掘",
    maxResults: 10
  });
  return result;
};

# 运行（在隔离会话中）
openclaw run ~/.openclaw/workspace/tasks/literature_task.js \
  --session-target isolated \
  --label LiteratureBot \
  --timeout 120
```

**方法2：使用 sessions_spawn（推荐）**
```bash
# 这个需要在主代理会话中执行
# 通过 QQ/微信发送指令给我，我来执行
```

### 1.3 强制终止子代理

```bash
# 通过名称终止
openclaw subagents kill LiteratureBot

# 或者通过 sessionKey
openclaw subagents kill --session-key agent:main:subagent:xxx
```

### 1.4 给子代理发送指令

```bash
# 向运行中的子代理发送消息
openclaw subagents steer LiteratureBot \
  --message "请加快进度"
```

---

## 二、配置文件详解

### 2.1 全局配置文件

**位置：** `~/.openclaw/openclaw.json`

```json
{
  "agent": {
    "default_model": "bailian/kimi-k2.5",
    "subagents": {
      "enabled": true,
      "max_concurrent": 5,        // 最大并行子代理数
      "default_timeout": 120,      // 默认超时（秒）
      "auto_cleanup": true         // 自动清理已完成代理
    }
  },
  "projects": {
    "default": "Spatial_Data_Mining",
    "base_dir": "~/.openclaw/workspace/projects"
  },
  "skills": {
    "auto_load": true,
    "allowed": ["docx-editor", "pptx-editor", "tavily-search", "mediacrawler"]
  }
}
```

### 2.2 项目配置文件

**位置：** `~/.openclaw/workspace/projects/{项目名}/.claw/config.json`

```json
{
  "project": {
    "name": "Spatial_Data_Mining",
    "description": "空间数据挖掘研究项目",
    "created_at": "2026-05-26",
    "version": "1.0"
  },
  
  "agent": {
    "default_model": "bailian/kimi-k2.5",
    "thinking": "off"
  },
  
  "subagents": {
    // 项目专属子代理配置
    "available": [
      {
        "name": "LiteratureBot",
        "description": "文献检索专家",
        "skills": ["tavily-search", "mediacrawler"],
        "timeout": 120
      },
      {
        "name": "AnalysisBot", 
        "description": "数据分析专家",
        "skills": ["xlsx-editor", "summarize"],
        "timeout": 180
      },
      {
        "name": "WriterBot",
        "description": "文档写作专家", 
        "skills": ["docx-editor", "pptx-editor"],
        "timeout": 300
      }
    ],
    
    // 工作流定义
    "workflows": {
      "literature_review": {
        "steps": [
          {"agent": "LiteratureBot", "output": "literature/"},
          {"agent": "AnalysisBot", "input": "literature/", "output": "data/"},
          {"agent": "WriterBot", "input": "data/", "output": "drafts/"}
        ]
      }
    }
  },
  
  "paths": {
    "data": "./data",
    "literature": "./literature", 
    "drafts": "./drafts",
    "scripts": "./scripts"
  },
  
  "env": {
    "API_KEY": "${API_KEY}",
    "DEBUG": "false"
  }
}
```

### 2.3 子代理任务脚本模板

**位置：** `~/.openclaw/workspace/projects/{项目名}/scripts/`

**literature_task.js：**
```javascript
// 子代理任务脚本
module.exports = async ({ agent, parameters }) => {
  const { query, outputPath } = parameters;
  
  // 1. 使用技能搜索
  const papers = await agent.skill('tavily-search').search({
    query: query,
    maxResults: 20
  });
  
  // 2. 处理结果
  const summary = {
    total: papers.length,
    papers: papers.map(p => ({
      title: p.title,
      url: p.url,
      date: p.published_date
    }))
  };
  
  // 3. 保存到项目目录
  await agent.fs.writeFile(
    `${outputPath}/literature_summary.json`,
    JSON.stringify(summary, null, 2)
  );
  
  return {
    status: 'success',
    papersCount: papers.length,
    outputFile: `${outputPath}/literature_summary.json`
  };
};
```

---

## 三、项目与代理的关联

### 3.1 关联原理

```
项目目录结构：
~/.openclaw/workspace/projects/
└── Spatial_Data_Mining/          # 项目根目录
    ├── .claw/
    │   └── config.json           # 项目配置（绑定子代理）
    ├── data/                     # 数据目录
    ├── literature/               # 文献目录
    ├── drafts/                   # 草稿目录
    └── scripts/                  # 脚本目录
        ├── literature_task.js    # 文献虾脚本
        ├── analysis_task.js      # 分析虾脚本
        └── writer_task.js        # 写作虾脚本
```

### 3.2 启动时绑定项目

**方式1：通过 cwd 参数**
```javascript
sessions_spawn({
  runtime: "subagent",
  task: "...",
  cwd: "~/.openclaw/workspace/projects/Spatial_Data_Mining",
  label: "Spatial_LiteratureBot"
});
```

**方式2：任务中指定路径**
```javascript
task: `
  // 读取项目配置
  const config = JSON.parse(fs.readFileSync(
    '~/.openclaw/workspace/projects/Spatial_Data_Mining/.claw/config.json'
  ));
  
  // 保存到项目目录
  fs.writeFileSync(
    '~/.openclaw/workspace/projects/Spatial_Data_Mining/data/result.json',
    data
  );
`
```

**方式3：使用环境变量**
```bash
# 设置当前项目
export OPENCLAW_PROJECT=Spatial_Data_Mining

# 子代理自动读取
const project = process.env.OPENCLAW_PROJECT;
```

### 3.3 数据流转图

```
┌─────────────────────────────────────────┐
│         Spatial_Data_Mining 项目        │
│                                         │
│  ┌─────────────┐    ┌─────────────┐   │
│  │  LiteratureBot    │    │  AnalysisBot      │   │
│  │  (文献虾)     │───→│  (分析虾)     │   │
│  └──────┬──────┘    └──────┬──────┘   │
│         │                   │           │
│         ▼                   ▼           │
│  ┌─────────────────────────────────┐   │
│  │        WriterBot (写作虾)        │   │
│  │              ↓                  │   │
│  │    drafts/literature_review.docx│   │
│  └─────────────────────────────────┘   │
│                                         │
│  数据路径：                              │
│  literature/ → data/ → drafts/         │
└─────────────────────────────────────────┘
```

---

## 四、实战：从零创建项目

### 步骤1：创建项目目录

```bash
# 创建项目根目录
mkdir -p ~/.openclaw/workspace/projects/MyResearch/{data,literature,drafts,scripts,.claw}

# 创建项目配置
cat > ~/.openclaw/workspace/projects/MyResearch/.claw/config.json << 'EOF'
{
  "project": {
    "name": "MyResearch",
    "description": "我的研究项目"
  },
  "subagents": {
    "available": [
      {"name": "LiteratureBot", "skills": ["tavily-search"]},
      {"name": "WriterBot", "skills": ["docx-editor"]}
    ]
  }
}
EOF
```

### 步骤2：创建子代理脚本

```bash
# 创建文献虾脚本
cat > ~/.openclaw/workspace/projects/MyResearch/scripts/literature.js << 'EOF'
module.exports = async ({ agent }) => {
  const result = await agent.skill('tavily-search').search({
    query: "机器学习",
    maxResults: 10
  });
  
  await agent.fs.writeFile(
    '~/.openclaw/workspace/projects/MyResearch/literature/papers.json',
    JSON.stringify(result, null, 2)
  );
  
  return { count: result.length };
};
EOF
```

### 步骤3：启动子代理

```bash
# 方法1：命令行启动
openclaw run ~/.openclaw/workspace/projects/MyResearch/scripts/literature.js \
  --session-target isolated \
  --label MyResearch_LiteratureBot \
  --timeout 120

# 方法2：通过主代理（QQ/微信发指令）
# "启动 MyResearch 项目的文献虾"
```

### 步骤4：查看结果

```bash
# 检查生成的文件
ls -la ~/.openclaw/workspace/projects/MyResearch/literature/

# 查看内容
cat ~/.openclaw/workspace/projects/MyResearch/literature/papers.json
```

---

## 五、常用命令速查

### 5.1 子代理管理

| 命令 | 说明 |
|---|---|
| `openclaw subagents list` | 列出所有子代理 |
| `openclaw subagents kill <name>` | 终止子代理 |
| `openclaw subagents steer <name> --message "msg"` | 向子代理发送指令 |
| `openclaw subagents logs <name>` | 查看子代理日志 |

### 5.2 项目管理

| 命令 | 说明 |
|---|---|
| `openclaw project list` | 列出所有项目 |
| `openclaw project create <name>` | 创建新项目 |
| `openclaw project switch <name>` | 切换当前项目 |
| `openclaw project info` | 查看当前项目信息 |

### 5.3 任务执行

| 命令 | 说明 |
|---|---|
| `openclaw run <script.js>` | 执行脚本 |
| `openclaw run --session-target isolated` | 在隔离会话中执行 |
| `openclaw run --label <name>` | 指定子代理名称 |
| `openclaw run --timeout <seconds>` | 设置超时时间 |

### 5.4 技能管理

| 命令 | 说明 |
|---|---|
| `clawhub list` | 列出已安装技能 |
| `clawhub install <skill>` | 安装技能 |
| `clawhub update --all` | 更新所有技能 |
| `openclaw skills check` | 检查技能健康状态 |

---

## 六、配置文件完整示例

### 6.1 全局配置 `~/.openclaw/openclaw.json`

```json
{
  "version": "1.0",
  "agent": {
    "name": "小小叶",
    "default_model": "bailian/kimi-k2.5",
    "thinking": "off",
    "subagents": {
      "enabled": true,
      "max_concurrent": 5,
      "default_timeout": 120,
      "auto_cleanup": true,
      "sandbox": {
        "enabled": true,
        "allowedPaths": [
          "~/.openclaw/workspace",
          "~/.openclaw/projects"
        ]
      }
    }
  },
  "projects": {
    "base_dir": "~/.openclaw/workspace/projects",
    "default": "Spatial_Data_Mining"
  },
  "channels": {
    "qqbot": {
      "enabled": true,
      "requireMention": false
    }
  },
  "skills": {
    "auto_load": true,
    "directories": [
      "~/.openclaw/workspace/skills"
    ]
  }
}
```

### 6.2 项目配置 `.claw/config.json`

```json
{
  "project": {
    "name": "Spatial_Data_Mining",
    "description": "空间数据挖掘研究",
    "version": "1.0",
    "created_at": "2026-05-26"
  },
  
  "agent": {
    "model": "bailian/kimi-k2.5",
    "temperature": 0.7
  },
  
  "subagents": {
    "definitions": {
      "LiteratureBot": {
        "description": "文献检索专家",
        "skills": ["tavily-search", "mediacrawler"],
        "timeout": 120,
        "max_retries": 3
      },
      "AnalysisBot": {
        "description": "数据分析专家",
        "skills": ["xlsx-editor", "summarize"],
        "timeout": 180
      },
      "WriterBot": {
        "description": "文档写作专家",
        "skills": ["docx-editor", "pptx-editor"],
        "timeout": 300
      }
    },
    
    "workflows": {
      "literature_review": {
        "name": "文献综述",
        "description": "从检索到生成的完整流程",
        "steps": [
          {
            "agent": "LiteratureBot",
            "task": "search_literature",
            "output": "literature/"
          },
          {
            "agent": "AnalysisBot",
            "task": "analyze_data",
            "input": "literature/",
            "output": "data/"
          },
          {
            "agent": "WriterBot",
            "task": "generate_report",
            "input": "data/",
            "output": "drafts/"
          }
        ]
      }
    }
  },
  
  "paths": {
    "data": "./data",
    "literature": "./literature",
    "drafts": "./drafts",
    "scripts": "./scripts",
    "shared": "~/.openclaw/workspace/shared"
  },
  
  "env": {
    "PROJECT_NAME": "Spatial_Data_Mining",
    "DEBUG": "false"
  }
}
```

---

## 七、实战：完整工作流

### 7.1 一键启动文献综述

**创建启动脚本：**
```bash
cat > ~/.openclaw/workspace/projects/Spatial_Data_Mining/scripts/start_workflow.sh << 'EOF'
#!/bin/bash

PROJECT="Spatial_Data_Mining"
PROJECT_DIR="$HOME/.openclaw/workspace/projects/$PROJECT"

echo "🚀 启动文献综述工作流..."
echo "项目: $PROJECT"

# Phase 1: 文献虾
echo "📚 Phase 1: 启动文献虾..."
openclaw run "$PROJECT_DIR/scripts/literature_task.js" \
  --session-target isolated \
  --label "${PROJECT}_LiteratureBot" \
  --timeout 120

# Phase 2: 分析虾
echo "📊 Phase 2: 启动分析虾..."
openclaw run "$PROJECT_DIR/scripts/analysis_task.js" \
  --session-target isolated \
  --label "${PROJECT}_AnalysisBot" \
  --timeout 180

# Phase 3: 写作虾
echo "📝 Phase 3: 启动写作虾..."
openclaw run "$PROJECT_DIR/scripts/writer_task.js" \
  --session-target isolated \
  --label "${PROJECT}_WriterBot" \
  --timeout 300

echo "✅ 工作流完成！"
echo "输出文件: $PROJECT_DIR/drafts/literature_review.docx"
EOF

chmod +x ~/.openclaw/workspace/projects/Spatial_Data_Mining/scripts/start_workflow.sh
```

**执行：**
```bash
# 一键执行完整工作流
~/.openclaw/workspace/projects/Spatial_Data_Mining/scripts/start_workflow.sh
```

### 7.2 监控工作流

```bash
# 查看所有子代理状态
watch -n 5 'openclaw subagents list'

# 查看特定代理日志
openclaw subagents logs Spatial_Data_Mining_LiteratureBot --tail 50

# 查看项目文件变化
watch -n 2 'ls -lh ~/.openclaw/workspace/projects/Spatial_Data_Mining/drafts/'
```

---

## 八、故障排查

### 8.1 子代理超时

**症状：** 子代理状态显示 `timeout`

**解决：**
```bash
# 1. 检查日志
openclaw subagents logs <name> --tail 100

# 2. 增加超时时间
openclaw run script.js --timeout 300

# 3. 简化任务，给代码模板
```

### 8.2 权限错误

**症状：** `Permission denied` 或 `Path not allowed`

**解决：**
```bash
# 检查沙箱配置
cat ~/.openclaw/openclaw.json | grep -A 10 sandbox

# 添加允许路径
openclaw config set agent.subagents.sandbox.allowedPaths '["~/mydata"]'
```

### 8.3 技能未找到

**症状：** `Skill not found`

**解决：**
```bash
# 检查技能是否安装
clawhub list

# 安装缺失技能
clawhub install docx-editor

# 检查技能路径
ls ~/.openclaw/workspace/skills/
```

---

## 附录：环境变量参考

| 变量 | 说明 | 示例 |
|---|---|---|
| `OPENCLAW_PROJECT` | 当前项目 | `Spatial_Data_Mining` |
| `OPENCLAW_HOME` | OpenClaw根目录 | `~/.openclaw` |
| `OPENCLAW_MODEL` | 默认模型 | `bailian/kimi-k2.5` |
| `OPENCLAW_DEBUG` | 调试模式 | `true`/`false` |

---

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