OpenClaw 主控 Agent + 子 Agent 分工协作完全指南

单个 AI 能力有限，复杂任务容易"脑子打结"。主控 Agent + 子 Agent 的协作模式，让 AI 像人类团队一样分工协作：主控负责调度，子 Agent 各司其职。

为什么需要主控 + 子 Agent？

单 Agent 的局限

问题	表现
任务过载	复杂任务"脑子打结"，输出质量下降
角色混乱	既当客服又当程序员，风格切换不自然
上下文污染	长对话后上下文混乱，输出不可控
无法并行	只能串行处理，效率低

主控 + 子 Agent 的优势

优势	说明
专业分工	每个 Agent 只做一件事，输出更精准
并行处理	多个子 Agent 同时工作，效率翻倍
上下文隔离	各 Agent 独立上下文，互不干扰
可扩展	需要新能力，加个子 Agent 即可

---

架构设计

基本架构

┌─────────────────────────────────────────────────────────────┐
│                      用户请求                                │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     主控 Agent                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ • 理解用户意图                                        │   │
│  │ • 拆解任务                                            │   │
│  │ • 分发给子 Agent                                      │   │
│  │ • 汇总结果                                            │   │
│  │ • 返回用户                                            │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ 子Agent A   │  │ 子Agent B   │  │ 子Agent C   │
│ (代码生成)   │  │ (数据分析)   │  │ (文档撰写)   │
└─────────────┘  └─────────────┘  └─────────────┘

通信协议

主控 Agent 与子 Agent 通过 ACP（Agent Communication Protocol） 通信：

主控 Agent ──ACP Request──▶ 子 Agent
主控 Agent ◀──ACP Response── 子 Agent

---

配置方法

Step 1：定义主控 Agent

在 ~/.openclaw/openclaw.json 中配置：

{
  "agents": {
    "main-controller": {
      "name": "主控助手",
      "model": "deepseek/deepseek-chat",
      "systemPrompt": "你是主控 Agent，负责理解用户需求、拆解任务、分发给子Agent、汇总结果。你本身不执行具体任务，只负责调度。",
      "subagents": [
        "code-agent",
        "data-agent",
        "doc-agent"
      ]
    }
  }
}

Step 2：定义子 Agent

{
  "agents": {
    "code-agent": {
      "name": "代码助手",
      "model": "deepseek/deepseek-chat",
      "systemPrompt": "你是专业的代码生成助手。专注于编写高质量代码，代码要有注释、遵循最佳实践。不要做代码以外的事情。",
      "capabilities": ["code_generation", "file_operations"]
    },
    "data-agent": {
      "name": "数据分析助手",
      "model": "deepseek/deepseek-chat",
      "systemPrompt": "你是数据分析专家。专注于数据处理、统计分析、可视化。输出要有数据支撑、结论清晰。",
      "capabilities": ["data_analysis", "chart_generation"]
    },
    "doc-agent": {
      "name": "文档撰写助手",
      "model": "deepseek/deepseek-chat",
      "systemPrompt": "你是专业的技术文档撰写者。文档结构清晰、语言简洁、重点突出。擅长写教程、API文档、技术规范。",
      "capabilities": ["document_writing"]
    }
  }
}

Step 3：配置路由规则

{
  "routing": {
    "rules": [
      {
        "condition": "task_type == 'code'",
        "target": "code-agent"
      },
      {
        "condition": "task_type == 'data'",
        "target": "data-agent"
      },
      {
        "condition": "task_type == 'document'",
        "target": "doc-agent"
      }
    ]
  }
}

---

实战场景一：代码生成 + 文档撰写

场景描述

用户请求："帮我写一个用户登录功能，并生成对应的 API 文档"

执行流程

1. 主控 Agent 接收请求
2. 拆解任务：
   - 任务A：生成登录代码 → code-agent
   - 任务B：生成API文档 → doc-agent
3. 并行分发
4. 汇总结果返回

配置示例

{
  "agents": {
    "main-controller": {
      "workflow": {
        "parallel": true,
        "tasks": [
          {
            "name": "generate_code",
            "agent": "code-agent",
            "input": {
              "type": "user_login",
              "language": "python"
            }
          },
          {
            "name": "generate_docs",
            "agent": "doc-agent",
            "input": {
              "format": "openapi",
              "depends_on": "generate_code"
            }
          }
        ]
      }
    }
  }
}

---

实战场景二：数据分析 + 报告生成

场景描述

用户请求："分析这份销售数据，生成一份分析报告"

执行流程

1. 主控 Agent 接收请求
2. 拆解任务：
   - 任务A：数据清洗、统计分析 → data-agent
   - 任务B：生成图表 → chart-agent
   - 任务C：撰写报告 → doc-agent
3. 串行执行（有依赖关系）
4. 汇总返回

配置示例

{
  "agents": {
    "main-controller": {
      "workflow": {
        "parallel": false,
        "tasks": [
          {
            "name": "analyze_data",
            "agent": "data-agent"
          },
          {
            "name": "generate_charts",
            "agent": "chart-agent",
            "depends_on": "analyze_data"
          },
          {
            "name": "write_report",
            "agent": "doc-agent",
            "depends_on": "generate_charts"
          }
        ]
      }
    }
  }
}

---

实战场景三：多技能协同

场景描述

用户请求："监控 GitHub Issues，自动分析、修复并回复"

架构设计

GitHub Webhook
      │
      ▼
┌─────────────┐
│ 主控 Agent  │ ◀── 监控触发
└─────────────┘
      │
      ├─────▶ 分析Agent：理解 Issue 内容
      │
      ├─────▶ 修复Agent：生成修复代码
      │
      ├─────▶ 测试Agent：验证修复有效性
      │
      └─────▶ 回复Agent：生成回复内容

配置示例

{
  "agents": {
    "github-controller": {
      "trigger": "webhook",
      "workflow": {
        "tasks": [
          {"name": "analyze", "agent": "issue-analyzer"},
          {"name": "fix", "agent": "code-fixer", "depends_on": "analyze"},
          {"name": "test", "agent": "test-runner", "depends_on": "fix"},
          {"name": "reply", "agent": "reply-generator", "depends_on": "test"}
        ]
      }
    }
  }
}

---

实战场景四：客服机器人

场景描述

智能客服系统，根据问题类型路由到专业 Agent

架构设计

用户问题
    │
    ▼
┌─────────────┐
│ 路由 Agent  │ ◀── 意图识别
└─────────────┘
    │
    ├─────▶ 售前Agent：产品咨询、价格查询
    │
    ├─────▶ 售后Agent：问题排查、退换货
    │
    ├─────▶ 技术Agent：技术支持、Bug反馈
    │
    └─────▶ 投诉Agent：投诉处理、人工转接

配置示例

{
  "agents": {
    "customer-service-router": {
      "name": "客服路由",
      "intentDetection": true,
      "routes": [
        {"intent": "presale", "agent": "presale-agent"},
        {"intent": "aftersale", "agent": "aftersale-agent"},
        {"intent": "technical", "agent": "tech-support-agent"},
        {"intent": "complaint", "agent": "complaint-agent"}
      ]
    }
  }
}

---

实战场景五：内容创作流水线

场景描述

用户请求："帮我写一篇关于 AI 趋势的文章"

执行流程

1. 研究 Agent：搜索资料、整理信息
2. 大纲 Agent：生成文章大纲
3. 写作 Agent：撰写正文
4. 编辑 Agent：润色修改
5. 排版 Agent：格式化输出

配置示例

{
  "agents": {
    "content-pipeline": {
      "workflow": {
        "tasks": [
          {"name": "research", "agent": "research-agent"},
          {"name": "outline", "agent": "outline-agent", "depends_on": "research"},
          {"name": "write", "agent": "writer-agent", "depends_on": "outline"},
          {"name": "edit", "agent": "editor-agent", "depends_on": "write"},
          {"name": "format", "agent": "formatter-agent", "depends_on": "edit"}
        ]
      }
    }
  }
}

---

高级配置

结果缓存

避免重复计算：

{
  "subagents": {
    "cache": {
      "enabled": true,
      "ttl": 3600
    }
  }
}

超时控制

{
  "subagents": {
    "timeout": 60000,
    "retry": {
      "maxAttempts": 3,
      "backoff": "exponential"
    }
  }
}

成本控制

不同任务使用不同模型：

{
  "agents": {
    "code-agent": {
      "model": "deepseek/deepseek-coder"
    },
    "doc-agent": {
      "model": "deepseek/deepseek-chat"
    },
    "analysis-agent": {
      "model": "openai/gpt-4o"
    }
  }
}

---

调试技巧

查看任务分发日志

openclaw logs -f --filter "subagent"

单独测试子 Agent

openclaw agent test code-agent --input "写一个 Hello World"

查看通信详情

openclaw debug --show-acp

---

常见问题

问题一：任务卡住不执行

原因： 依赖任务未完成或循环依赖

解决：

检查 workflow 配置，确保无循环依赖：

openclaw workflow validate

问题二：结果不完整

原因： 子 Agent 超时

解决：

增加超时时间：

{
  "subagents": {
    "timeout": 120000
  }
}

问题三：成本过高

原因： 所有 Agent 都用贵模型

解决：

简单任务用便宜模型：

{
  "routing": {
    "modelSelection": {
      "simple": "deepseek-chat",
      "complex": "gpt-4o"
    }
  }
}

---

最佳实践

实践一：明确分工

每个子 Agent 只做一件事，职责单一。

实践二：合理模型选择

• 简单任务：便宜模型
• 复杂任务：强模型
• 主控 Agent：中等模型

实践三：并行优先

无依赖的任务尽量并行执行。

实践四：结果验证

关键任务加结果验证 Agent：

{
  "tasks": [
    {"name": "generate", "agent": "code-agent"},
    {"name": "validate", "agent": "validator-agent", "depends_on": "generate"}
  ]
}

---

总结

要素	说明
主控 Agent	调度、分发、汇总
子 Agent	执行具体任务
ACP 协议	Agent 间通信
工作流	任务编排规则

主控 + 子 Agent 的核心价值：

• 专业分工，输出更精准
• 并行处理，效率翻倍
• 上下文隔离，更可控
• 可扩展，随需添加能力

从简单的双 Agent 协作开始，逐步扩展到复杂的多 Agent 工作流。关键是明确每个 Agent 的职责，设计合理的任务编排规则。用对了，AI 团队比单兵作战效率高出数倍。