第 10 章 多代理架构:从单兵到协同

🏗️ 本章特色:大多数 OpenClaw 用户从一个名为 main 的主代理起步,它像一位万能但孤独的助手,处理你所有的请求。然而,随着使用场景的复杂化,单代理模式会暴露出上下文污染、成本模糊、公私混淆等诸多局限。本章带你理解这些局限,并通过实战演示如何构建一支分工明确、高效协作的"AI 专业团队"。

本章目录:

节 内容 你将学到
1 什么是代理(Agent) 代理的定义、核心特征、目录结构
2 单代理模式的五大局限 上下文污染、成本模糊、公私混淆、能力僵化、并发瓶颈
3 多代理架构设计 三种常见划分模式、职责分离原则、架构决策树
4 实战:搭建多代理系统 创建代理、配置 API Key、智能路由、CLI 管理
5 高级协作:子代理与跨代理通信 sessions_spawn、任务分解、结果整合
6 安全与最佳实践 权限隔离、模型选型、常见陷阱
7 总结与进阶 核心知识回顾、课后练习

1. 什么是代理(Agent)

1.1 代理的定义

代理(Agent,AI 工作单元) 是一个拥有独立身份、职责和上下文的 AI 工作实体。你可以把它想象成数字世界中的一个"岗位"或"角色"。

在传统软件架构中,一个程序通常只有一个入口、一套状态。但 OpenClaw 的代理系统允许你创建多个并行的 AI 工作者,每个都有自己的"记忆"和"技能"。这就像一家公司不会只雇一个员工来处理所有事务,而是组建一个团队,让每个人专注于自己擅长的领域。

每个代理都具备以下核心特征:

1.2 代理的目录结构

从目录结构来看,OpenClaw 在工作区中为每个代理维护独立的配置和会话存储。以本书作者的电脑为例,代理相关的数据存储结构如下:

C:\Users\zhang\.openclaw\
├── agents/
│   ├── main/                    # 主代理
│   │   ├── agent/               # 代理配置和工作区文件
│   │   │   ├── IDENTITY.md      # 主代理的身份
│   │   │   ├── SOUL.md          # 主代理的行为准则
│   │   │   ├── MEMORY.md        # 主代理的长期记忆
│   │   │   └── memory/          # 主代理的每日日志
│   │   └── sessions/            # 主代理的会话历史
│   │
│   ├── longhub/                 # longhub 项目代理
│   │   ├── agent/
│   │   │   ├── IDENTITY.md
│   │   │   ├── SOUL.md
│   │   │   └── MEMORY.md
│   │   └── sessions/
│   │
│   └── ops/                     # 运维代理
│       ├── agent/
│       └── sessions/

每个代理有自己独立的文件夹,确保配置和会话之间互不干扰。这种物理隔离是多代理架构的基石,也是后续安全隔离和职责划分的基础。

简单来说:一个代理就是一个独立的 AI 工作者,有自己的名字、记忆、技能和会话。多个代理之间互不干扰,就像同一栋办公楼里的不同部门。

理解了代理的基本概念,接下来看看为什么单一代理无法满足复杂场景的需求。


2. 单代理模式的五大局限

对于简单的个人查询或日常聊天,单一的 main 代理绰绰有余。但一旦涉及真实的工作流、多项目管理或敏感信息处理,其局限性便会迅速显现。

2.1 局限一:上下文污染与信息泄露

这是最值得关注的问题。单代理将所有对话历史混杂在一个上下文中。当你同时处理多个项目时,AI 可能会无意中将 A 项目的信息用于回答 B 项目的问题。

场景示例:你在周一与 main 代理讨论了华为项目的技术方案细节。到了周三,当你询问另一个项目的技术选型时,AI 可能会回复"可以参考我们之前为华为设计的方案"。如果这两个项目之间存在保密要求,这种信息交叉就可能带来严重的合规风险。

上下文污染不仅限于跨项目泄露。即使是同一个项目,不同阶段的讨论也可能互相干扰。早期的错误方案可能影响后续的正确决策,过时的需求可能覆盖最新的变更。

2.2 局限二:成本核算模糊

所有 API 调用(Token 消耗)都记在同一个账户下。你无法区分哪些开销来自工作项目,哪些是个人使用,也无法向不同客户精确分摊成本。

现实困境:月底账单显示总费用为 358 元。客户问"华为项目花了多少?"你只能凭感觉估算"大概 200 吧",无法提供准确数据。对于需要向客户报账的自由职业者或咨询公司,这种模糊性是不可接受的。

2.3 局限三:公私界限模糊

工作消息与私人聊天交织在一起,导致生活与工作的边界消失。下班后收到关于工作代码审查的提醒,或在私人聊天中被工作上下文干扰,都会降低使用体验。

更深层的问题是心理负担。当你的 AI 助手同时处理工作和私人事务,你在与它交流时很难完全放松。"这个问题会不会被记录到工作日志里?"这种隐忧会削弱人机协作的信任基础。

2.4 局限四:模型与工具的"一刀切"

单代理通常绑定一套固定的模型和工具集。这意味着:

2.5 局限五:并发能力瓶颈

单代理的串行交互模式使其一次只能专注处理一个任务。当你希望同时进行代码编写、资料搜索和邮件草拟时,必须排队等待,无法发挥 AI 的并行潜力。

在团队协作场景中,这个问题更加突出。如果你的 main 代理正在处理一个复杂的代码审查任务,此时你的同事发来一条紧急消息,代理要么中断当前任务去回复,要么让同事等待。两种选择都不理想。

下面用一张表格总结这五大局限:

局限类型 核心问题 潜在后果 影响程度
上下文污染 所有历史混杂在一个上下文 信息泄露、项目间交叉干扰 🔴 高
成本模糊 开销无法按项目细分 财务核算困难、客户报账不精确 🟡 中
公私混淆 工作生活交织在一起 体验下降、心理负担增加 🟡 中
能力僵化 模型和工具固定不变 资源浪费、安全风险、能力错配 🔴 高
并发瓶颈 任务只能串行执行 响应延迟、协作效率低 🟡 中

正是这些局限,使得单代理模式无法满足专业、安全、高效的生产力需求。我们需要一种新的架构。


3. 多代理架构设计

3.1 核心思想:职责分离

多代理架构(Multi-Agent Architecture) 的核心思想是职责分离。它不再依赖一个全能的助手,而是组建一支由多个专业化"专家"组成的团队,每个成员各司其职。

这个理念来源于软件工程中的"单一职责原则"(Single Responsibility Principle):一个模块应该只有一个引起它变化的原因。同理,一个代理应该只负责一类明确的任务。当任务类型发生变化时,只需要修改对应代理的配置,不影响其他代理。

多代理架构通过物理隔离和专业化分工,逐一解决单代理的五大局限:

单代理局限 多代理解决方案 效果
上下文污染 为每个项目或领域创建独立代理 物理隔离,杜绝信息交叉
成本模糊 每个代理使用独立的 API Key 精确到项目的费用追踪
公私混淆 创建 work 和 personal 代理 清晰划分工作与生活
能力僵化 为不同任务定制模型和工具 小任务用小模型,高危操作限权限
并发瓶颈 多个代理可同时处理不同任务 真正实现并行工作流

3.2 三种常见划分模式

设计多代理架构时,通常有三种划分模式,实践中往往是它们的混合体。

模式一:按项目划分

适用于同时服务多个客户或内部项目的场景。

┌───────────────────────────────────────────┐
│            按项目划分的多代理架构           │
│                                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │ huawei   │  │ netlinkz │  │ internal │ │
│  │ 代理     │  │ 代理     │  │ 代理     │ │
│  │          │  │          │  │          │ │
│  │ 独立记忆 │  │ 独立记忆 │  │ 独立记忆 │ │
│  │ 独立会话 │  │ 独立会话 │  │ 独立会话 │ │
│  │ 独立 API │  │ 独立 API │  │ 独立 API │ │
│  └──────────┘  └──────────┘  └──────────┘ │
│                                            │
│  优势:项目间完全隔离,成本独立核算        │
│  适用:自由职业者、咨询公司、多项目团队    │
└───────────────────────────────────────────┘

模式二:按公私划分

适用于需要严格区分工作与个人生活的用户。

模式三:按职能划分

适用于任务类型差异巨大的场景。

架构决策树

不确定怎么划分?下面这棵决策树可以帮你快速判断:

你的使用场景是什么?
│
├── 同时服务多个客户/项目?
│   └── 是 → 按项目划分(huawei、netlinkz、internal)
│
├── 需要区分工作和生活?
│   └── 是 → 按公私划分(work、personal)
│
├── 不同任务需要不同能力?
│   └── 是 → 按职能划分(coding、research、review)
│
└── 以上都有?
    └── 混合模式:先按公私分,再在 work 下按项目或职能细分

实践中,往往是以上模式的混合体。比如,你可以在 work 代理下再细分为 huawei 和 netlinkz 两个项目代理,同时创建一个 coding 职能代理专门处理代码任务。

理解了设计原则,接下来进入实战环节,看看如何真正搭建一个多代理系统。


4. 实战:搭建多代理系统

让我们以"同时负责华为和 NetLinkZ 两个项目"为例,演示如何落地多代理架构。

4.1 创建代理

OpenClaw 提供了命令行工具来管理代理。你可以使用 openclaw agents 命令来创建、查看和管理代理。

# 查看所有可用的代理管理子命令
openclaw agents --help

创建一个新代理的基本流程:

# 创建名为 huawei 的代理
openclaw agents add huawei

执行后,系统会自动完成几项工作:

4.2 配置代理属性

每个代理在 agents.entries 中都有自己的配置条目。以下是一个典型的多代理配置示例:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "workspace": "C:\\Users\\zhang\\.openclaw\\workspace"
    },
    "entries": {
      "huawei": {
        "name": "华为项目助手",
        "description": "专门处理华为项目的技术沟通和文档工作",
        "model": "anthropic/claude-sonnet-4-20250514",
        "workspace": "D:\\projects\\huawei",
        "identity": {
          "name": "华为助手",
          "emoji": "📱"
        },
        "tools": {
          "profile": "full",
          "exec": {
            "mode": "ask"
          }
        }
      },
      "netlinkz": {
        "name": "NetLinkZ 项目助手",
        "description": "专门处理 NetLinkZ 路由器项目的开发工作",
        "model": "anthropic/claude-sonnet-4-20250514",
        "workspace": "D:\\projects\\netlinkz",
        "identity": {
          "name": "NetLinkZ 助手",
          "emoji": "🌐"
        },
        "tools": {
          "profile": "coding"
        }
      },
      "main": {
        "name": "个人助手",
        "description": "处理个人事务和日常聊天",
        "model": "qwen-portal/qwen3-coder-plus",
        "identity": {
          "name": "大张",
          "emoji": "🏠"
        },
        "tools": {
          "profile": "minimal"
        },
        "default": true
      }
    }
  }
}

这个配置展示了几个关键的设计决策:

配置字段 说明 示例中的用法
model 每个代理使用不同的大模型 华为用 Claude,个人用通义千问(成本更低)
workspace 每个代理有独立的工作目录 华为项目在 D:\projects\huawei
identity 每个代理有自己的名字和 emoji 在消息列表中直观区分
tools.profile 每个代理有不同的工具权限 华为用 full,NetLinkZ 用 coding,个人用 minimal
default 标记默认代理 未匹配的消息交给 main 处理

4.3 配置智能路由

路由规则决定了"什么消息应该发给哪个代理"。OpenClaw 支持基于渠道绑定(Bindings)的路由机制。

在全局配置文件中,你可以为每个代理指定它应该响应哪些渠道的消息:

{
  "agents": {
    "entries": {
      "huawei": {
        "bindings": {
          "peers": ["huawei-pm@wechat", "huawei-tech@wechat"]
        }
      },
      "netlinkz": {
        "bindings": {
          "peers": ["nlz-contact@wechat"]
        }
      },
      "main": {
        "default": true
      }
    }
  }
}

路由机制说明:

┌──────────────────────────────────────────────────────┐
│                  消息路由流程                           │
│                                                       │
│  消息来源                  路由判断              代理   │
│                                                       │
│  华为 PM @微信  ─────────→ 匹配 huawei  ──────→  huawei │
│  华为技术 @微信 ─────────→ 匹配 huawei  ──────→  huawei │
│  NetLinkZ @微信 ─────────→ 匹配 netlinkz ─────→  netlinkz│
│  其他所有消息   ─────────→ 默认路由       ──────→  main   │
│                                                       │
└──────────────────────────────────────────────────────┘

你也可以使用 CLI 子命令来管理路由规则,比直接编辑配置文件更安全便捷:

# 为 huawei 代理绑定路由
openclaw agents bind huawei

# 查看已配置的代理列表
openclaw agents list

4.4 与代理交互

创建和配置好代理后,你可以通过多种方式与特定代理交互。

方式一:通过路由自动分发

正常发送消息,系统根据路由规则自动选择代理。这是最自然的使用方式,你不需要关心"这条消息应该发给谁"。

方式二:通过 CLI 直接指定

# 向指定代理发送消息
openclaw agent --agent huawei --message "总结一下今天的项目进展"

通过 --agent 参数,你可以绕过路由规则,直接与某个代理对话。这在调试或执行特定任务时非常有用。

方式三:通过 Control UI 切换

在 OpenClaw 的 Control UI(网页管理界面)中,你可以看到所有代理的列表,点击切换当前活跃的代理,然后在该代理的会话窗口中直接对话。

4.5 独立 API Key 与成本追踪

为每个代理配置专属的 API Key,确保费用分离。每个代理的认证信息存储在其独立的配置中,这样不同代理的 API 调用会分别计费。

# 为 huawei 代理设置独立的 API Key
openclaw config set agents.entries.huawei.params.apiKey "sk-huawei-xxx"

# 为 netlinkz 代理设置独立的 API Key
openclaw config set agents.entries.netlinkz.params.apiKey "sk-nlz-xxx"

月底查看账单时,你可以清楚地看到每个代理的 Token 消耗:

代理 本月 Token 费用 主要用途
huawei 2.8M ¥168 技术方案讨论、文档撰写
netlinkz 1.5M ¥90 代码审查、Bug 修复
main 0.8M ¥32 日常聊天、个人事务

简单来说:独立 API Key 让你能精确追踪每个项目的 AI 开销,向客户报账时底气十足。

搭建好多代理系统后,接下来看看如何让代理之间协作完成复杂任务。


5. 高级协作:子代理与跨代理通信

多代理不仅是静态的隔离,更是动态的协作。当一个复杂任务需要多种能力时,主代理可以临时"召唤"子代理来协同完成。

5.1 子代理(Subagent)的概念

子代理(Subagent,临时工作代理) 是由主代理动态创建的短期工作者。它不预先配置在 agents.entries 中,而是在需要时通过 sessions_spawn 工具临时创建,完成任务后即销毁。

子代理与预配置代理的区别:

对比维度 预配置代理 子代理
生命周期 长期存在 临时创建,用完即销
配置方式 agents.entries 中声明 sessions_spawn 动态创建
上下文 独立的持久化会话 隔离的临时会话或继承父会话
适用场景 持续性的项目或职能分工 一次性的复杂任务分解
资源消耗 常驻,占用存储 临时,完成后清理

5.2 子代理协作流程

场景:huawei 代理接到任务"撰写一份关于 5G 安全的市场分析报告"。

这个任务需要多种能力:网络搜索收集信息、数据分析、长文撰写。单个代理虽然可以串行完成,但效率低下。通过子代理协作,可以大幅提升效率。

┌──────────────────────────────────────────────────────┐
│              子代理协作流程                             │
│                                                       │
│  ① huawei 代理接到任务                                 │
│     "撰写 5G 安全市场分析报告"                          │
│        │                                              │
│        ▼                                              │
│  ② 分解任务                                          │
│     子任务 A:收集竞品信息和行业动态                    │
│     子任务 B:整合数据,撰写报告初稿                    │
│        │                                              │
│        ▼                                              │
│  ③ sessions_spawn 创建子代理                          │
│     ┌────────────┐     ┌────────────┐                 │
│     │ 子代理 A   │     │ 子代理 B   │                 │
│     │ 网络搜索   │     │ 文本生成   │                 │
│     │ web_search │     │ 长文撰写   │                 │
│     └─────┬──────┘     └─────┬──────┘                 │
│           │                  │                        │
│           ▼                  ▼                        │
│  ④ 子代理并行执行,返回结果                            │
│           │                  │                        │
│           └──────┬───────────┘                        │
│                  ▼                                    │
│  ⑤ huawei 代理整合结果                                 │
│     润色、格式化、输出最终报告                          │
│                  │                                    │
│                  ▼                                    │
│  ⑥ 子代理会话清理                                      │
│     临时上下文被清除,不污染主代理记忆                  │
└──────────────────────────────────────────────────────┘

具体步骤:

  1. 分解任务:主代理将任务拆解为"收集竞品信息"和"撰写报告初稿"两个子任务
  2. 召唤子代理:使用 sessions_spawn 工具,创建临时的子代理会话。一个子代理专注于网络搜索,收集最新行业动态。另一个子代理专注于文本生成,整合信息形成草稿
  3. 并行执行:两个子代理同时工作,互不干扰,总耗时取决于最慢的那个子代理
  4. 整合结果:子代理完成后,将结果返回给主代理。主代理整合信息,润色后输出最终报告
  5. 清理现场:子代理的会话结束,其临时上下文被清除,不会污染主代理的长期记忆

5.3 sessions_spawn 使用示例

sessions_spawn 是创建子代理的核心工具。它的基本用法如下:

{
  "tool": "sessions_spawn",
  "arguments": {
    "task": "搜索 2026 年 5G 安全领域的最新动态,包括主要厂商的安全方案、行业标准更新、近期安全事件。返回结构化的搜索结果。",
    "label": "5G安全信息收集",
    "context": "isolated",
    "mode": "run"
  }
}

关键参数说明:

参数 说明 常用值
task 子代理要执行的任务描述 自然语言描述的具体任务
label 子代理的显示标签 简短的任务名称
context 上下文模式 isolated(干净上下文)或 fork(继承父会话)
mode 运行模式 run(一次性执行)
agentId 指定目标代理 可选,指定由哪个代理执行
model 模型覆盖 可选,为子代理指定不同的模型

isolated vs fork:isolated 模式创建一个全新的干净会话,子代理不会看到父代理的对话历史,适合独立的搜索或计算任务。fork 模式会复制父代理的对话历史,子代理能理解之前的讨论上下文,适合需要延续当前对话的任务。

这种"主子"协作模式,既保持了主代理上下文的干净,又灵活地扩展了其能力边界,是构建复杂 AI 工作流的关键。


6. 安全与最佳实践

多代理架构在带来灵活性的同时,也引入了新的安全考量。本节总结常见的安全准则和最佳实践。

6.1 权限隔离原则

每个代理的工具权限应该遵循最小权限原则(Principle of Least Privilege):只赋予完成任务所需的最小权限。

代理类型 推荐工具配置 说明
coding tools.profile: "coding" 有代码执行权限,但限制网络访问
research tools.allow: ["web_search", "web_fetch", "read"] 只有搜索和读取权限
review tools.allow: ["read"] 只读权限,不能修改任何文件
personal tools.profile: "minimal" 最小权限,仅基本对话
ops tools.exec.mode: "ask" 执行命令前需要用户确认

反面案例:给所有代理都配 tools.profile: "full"。这意味着一个负责日常聊天的 personal 代理也能执行 rm -rf / 命令。权限过宽是多代理架构中最常见的安全隐患。

6.2 模型选型策略

不同代理应该使用不同的大模型,在能力和成本之间取得平衡:

代理类型 推荐模型 理由
coding Claude Sonnet 4 / GPT-4.1 代码能力强,理解复杂逻辑
research Claude Sonnet 4 / 通义千问 需要较强的理解和总结能力
personal 通义千问 / GPT-4o-mini 日常聊天不需要最强模型
review Claude Sonnet 4 代码审查需要精确的判断力
ops GPT-4.1-mini 运维任务相对标准化

成本对比:以一个典型的工作日为例,如果所有代理都用 Claude Sonnet 4,日费用约 ¥50。通过差异化选型,personal 代理改用通义千问后,日费用降至 ¥35,节省 30%,而体验几乎没有差别。

6.3 常见陷阱与规避

陷阱一:代理过多,管理复杂

创建了十几个代理,结果自己都搞不清"这个问题应该问谁"。路由规则也越来越复杂,维护成本急剧上升。

规避:从 2 到 3 个代理开始,逐步扩展。只有当你明确感受到某个局限时,才创建新的代理。

陷阱二:记忆不同步

huawei 代理知道项目的最新进展,但 main 代理不知道。当你通过 main 代理询问"华为项目怎么样了",得到的可能是过时的信息。

规避:明确每个代理的信息边界。如果某个信息需要跨代理共享,考虑把它放在公共位置(如共享的工作区目录),或者通过子代理协作来获取。

陷阱三:忽略默认代理

没有设置 default: true 的代理,导致未匹配路由的消息无人处理,用户收不到回复。

规避:始终确保有一个默认代理(通常是 main),作为"兜底"处理所有未匹配的消息。

陷阱四:API Key 混用

多个代理共用同一个 API Key,导致成本核算回到"一笔糊涂账"的状态。

规避:每个代理使用独立的 API Key。如果使用同一个供应商,可以创建多个 Key 分别绑定。


7. 总结与进阶

7.1 本章核心知识回顾

从单代理到多代理,是一次从"工具使用者"到"系统架构师"的思维跃迁。以下是本章的核心要点:

知识模块 核心要点
代理定义 代理是拥有独立身份、工作空间和上下文的 AI 工作单元
单代理局限 上下文污染、成本模糊、公私混淆、能力僵化、并发瓶颈
划分模式 按项目、按公私、按职能三种模式,实践中常混合使用
配置结构 agents.entries 中声明代理,每个代理有独立的 model、workspace、tools
智能路由 通过 bindings 将消息来源映射到对应代理
子代理协作 sessions_spawn 动态创建临时工作者,完成任务后自动清理
安全原则 最小权限、差异化模型选型、独立 API Key

7.2 行动建议

  1. 审视现状:回顾你的使用历史,是否存在上述五大局限
  2. 从小做起:不必一步到位,先尝试创建 work 和 personal 两个代理
  3. 善用路由:配置清晰的路由规则,让消息自动流向正确的代理
  4. 持续迭代:随着需求变化,逐步细化你的代理团队

7.3 课后练习

  1. 基础题:查看你当前 OpenClaw 配置中有几个代理(openclaw agents list)。如果只有一个 main,尝试创建一个 personal 代理,为它配置不同的模型和 emoji,然后分别在两个代理中发送消息,观察回复风格的差异。

  2. 进阶题:设计一个三代理架构,满足以下需求:一个代理负责代码开发(需要 exec 和 read/write 工具),一个代理负责资料搜索(需要 web_search 和 web_fetch 工具),一个代理负责日常聊天(最小权限)。写出完整的 agents.entries 配置,包括每个代理的 tools 设置。

  3. 思考题:假设你的 coding 代理在执行一个长时间运行的编译任务,此时你通过 personal 代理问"今天天气怎么样"。这两个请求会互相影响吗?为什么?如果会影响,你会怎么设计架构来避免?


本章完

本文为《OpenClaw 实战指南》系列第 10 篇。当你成功构建起自己的多代理系统,你会发现,OpenClaw 不再只是一个问答程序,而是一个真正能融入你工作流、值得信赖的智能协作者团队。