果酱味OpenClaw 的多 Agent 配置，写起来似乎很简单：定义几个角色、填几个 prompt、然后把它们连起来。但真正动手配过的人都知道，一套能稳定运行的多 Agent 配置，难点从来不在“会不会填 YAML”，而在“编排逻辑跟你的任务模型是否匹配”。这篇文章我不打算教你背语法，而是用一次完整的配置过程，把 OpenClaw 里 Agent、Claw、Message、Memory 这几个核心抽象串起来，讲明白每一步为什么要这样配，以及跑起来之后最容易踩的四类坑该怎么排查。如果你正准备把一套流程从单 Agent 改成多 Agent，或者已经配了配置但总是跑不稳，这篇文章应该能帮你省掉不少试错时间。
1. 别急着配 YAML：先想清楚多 Agent 到底比单 Agent 多了什么
1.1 单 Agent 上不去的三道坎
我最早做自动化任务的时候，也是先从一个模型实例加一堆工具函数开始。刚开始二三十条指令没什么问题，可任务链路一旦超过五步，问题就接踵而来。
第一道坎是上下文污染。单 Agent 的对话历史是一股脑全塞进上下文的，前一个子任务里的中间产物理论上应该被“用完即弃”，但它还留在对话里。等到处理第五个子任务时，模型已经分不清哪些是背景信息、哪些是当前结论。
第二道坎是不可中断。单 Agent 的流程是线性的，模型输出什么就直接执行什么。想插入“人工审批”环节？想在某一步做条件分流？可以，但全都得靠 prompt 里写一堆“如果……那么……”的规则，写到最后 prompt 比程序还复杂。
第三道坎是工具权限无法隔离。同一个 Agent 拿着全部工具，它可能在规划阶段就去执行了本该在执行阶段才做的操作。大模型对“工具可用”和“工具应该用”之间那条界限的把握，远没有你以为的那么稳。
1.2 多 Agent 真正解决的不是“花活”
很多人以为多 Agent 就是把一个超长 prompt 拆成几个短 prompt，让几个模型各干一段。这个理解不能说错，但它忽略了一个关键点：多 Agent 的价值不在于“字数减半”，而在于“状态隔离”。
拿内容生产举例。单 Agent 模式下，你给模型的完整指令是“先做信息检索，再写初稿，再自查修改”。这三件事挤在同一个上下文里，检索来的资料、初稿草稿、修改意见全都混在一起。改成多 Agent 之后，检索 Agent 只负责把资料整理成结构化结果；写稿 Agent 只接收那份结果，产出初稿；审稿 Agent 只看到初稿和一套评审标准，返回修改意见。每个 Agent 的上下文里都只保留自己最关心的那部分信息。
这样一来，问题就变得可控了。哪个环节出差错，日志一看便知；哪个 Agent 的提示词需要调，改完只影响它自己。更重要的是，你可以在任意两个 Agent 之间插入人工节点，“流程”就从一个黑盒变成了透明管道。
1.3 什么时候不该上多 Agent
必须说实话：多 Agent 不是银弹。如果你的任务就是“把一段 text 转成另一段 text”，中间没有任何工具依赖、没有分支条件、没有人工审批，那么强行拆成三个 Agent 只会白白增加延迟和成本，还多了一堆需要排查的调度问题。
我从实际观察里总结出来的判断标准是这样的：只要任务链路里出现下面任意一个特征，才值得考虑多 Agent——涉及两种以上工具调用；需要中间产物被多次修改；流程里存在条件分支或人工确认节点；需要不同角色使用不同的记忆范围。
如果一条都不占，老老实实用单 Agent 反而更稳。多 Agent 的配置成本，最后都要靠稳定的运行来赚回来，值不值得折腾，得先算这笔账。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 必须先建立的三个概念：Agent、Claw 和 Message
打开 OpenClaw 的配置文件，你会看到它围绕三类东西来组织。这三个概念理解到位了，配置文件怎么填都是顺理成章的事。
2.1 Agent：不是模型，而是“模型 + 人设 + 边界”的壳
Agent 是 OpenClaw 里最小的可调度单元。一个 Agent 并不等同于某个大模型，它是“模型实例 + 系统提示词 + 工具列表 + 记忆策略”的打包。
我把每个 Agent 想象成团队里的一个岗位，而不是一个人。岗位描述（系统提示词）定义了它负责什么；岗位能接触到的资源（工具列表）定义了它能做什么；岗位能查阅的资料（记忆策略）定义了它知道什么。这三个维度相互独立，又必须同时满足。最常见的配置问题，是只改了系统提示词，没有同步调整工具和记忆，结果 Agent 想做的事和它能做的事对不上。
2.2 Claw：Agent 伸出去的那只手
Claw 是 OpenClaw 里非常关键的一个抽象。它代表 Agent 与外部世界交互的“抓手”——可以是一个检索接口，可以是一个文件读写器，也可以是一个计算器或者一个待办管理 API。
叫 Claw 这个名字，我理解是想强调两件事：它像爪子一样可以灵活抓取，但要抓什么是由 Agent 决定的；同时爪子本身不具备判断力，Agent 让它抓它才抓，Agent 不调用它就闲置。所以工具权限隔离，本质上就是给每个 Agent 配置不同的 Claw 集合。
2.3 Message：Agent 之间流动的“数据包”
多 Agent 之间不共享会话，它们只通过 Message 通信。每条 Message 有发送方、接收方、主题和内容。路由规则就是根据这些字段决定消息往哪儿发的。
这点很关键：如果每个 Agent 都直接写在全局配置文件里，最后你会发现没关系。
实际使用时，我会像给网络报文定协议一样给 Message 设计主题。比如 task.new、task.result、review.pass、review.reject。主题名称一旦定下来，路由规则就围绕着主题来写，后续要加新 Agent 时也不用改旧规则。这跟代码里的接口设计是同一个道理。
三个抽象之间的关系，可以用一句话概括：Agent 是决策单位，Claw 是执行器官，Message 是通信协议。记住这句话，后面配置文件的每行配置你都能找到对应位置。
3. 第一份多 Agent 配置的完整拆解：从全局结构到最小验证
这一节我带你过一遍能实际跑通的最小配置。下面的字段名以我常用的 OpenClaw 0.5 系列版本写法为参考，你本地版本如果字段略有差异，去项目里对照一下 schema 即可，逻辑完全一致。
3.1 全局结构：models、agents、routing 三大块
yaml复制project:
name: demo_content_flow
models:
planner_model:
provider: local-compatible
base_url: "http://127.0.0.1:8080/v1"
model: "planner-7b"
temperature: 0.1
worker_model:
provider: local-compatible
base_url: "http://127.0.0.1:8080/v1"
model: "worker-7b"
temperature: 0.7
agents:
dispatcher:
model: planner_model
system_prompt: |
你是任务拆解员。你只负责分析用户请求，将其拆成可执行的子任务，
然后发给执行 Agent。你不编写最终内容，不做信息检索。
tools: []
memory: shared
executor:
model: worker_model
system_prompt: |
你是具体执行人。你会收到一个明确的子任务，直接完成它。
不要扩大任务范围，不要修改用户给的目标，不要自行添加步骤。
tools:
- claw.web_search
- claw.calculator
memory: project_only
reviewer:
model: planner_model
system_prompt: |
你是质检员。你只审查执行 Agent 返回的结果，
符合要求则返回 review.pass，不符合则返回 review.reject 并写明修改意见。
你不负责重写内容。
tools: []
memory: shared
routing:
default_start: dispatcher
rules:
- from: dispatcher
to: executor
on: task.new
- from: executor
to: reviewer
on: task.result
- from: reviewer
to: dispatcher
on: review.reject
- from: reviewer
to: __final__
on: review.pass
settings:
max_rounds: 10
timeout_sec: 120
log_level: info
这个结构总共三大块。models 定义可用的模型实例，agents 把不同的 model、system_prompt、tools、memory 组合起来，routing 规定消息流转规则。前两块是静态声明，第三块才是多 Agent 的“神经系统”。
3.2 dispatcher：负责拆解的 Agent 为什么可以不挂任何工具
配置文件里第一个 Agent 是 dispatcher，我把它的 tools 设成了空数组。有人会问：连工具都不给，它能干什么？
这正是多 Agent 配置里最反直觉的地方：调度者本来就不该亲自干活。dispatcher 的唯一产出是“任务分解结果”，它需要复用模型本身强大的归纳和分类能力，大量工具反而会诱导它在拆解阶段就去查资料、做计算，越俎代庖。让调度者保持“手无寸铁”，是一种刻意的最小权限设计。
3.3 executor：真正干活的 Agent 要怎么挂工具
executor 挂了两个 Claw：claw.web_search 用于检索，claw.calculator 用于计算。它的系统提示词里我特意写了三句“不要做什么”，比“要做什么”写得还具体——大模型对否定性约束其实很敏感，把最容易越界的行为提前切掉，后面少很多麻烦。
工具的选择遵循一个原则：宁可少配，不可多配。executor 需要 web_search 和 calculator，就只给这两个。你要是顺手把文件写入工具也塞给它，它可能在生成最终文案的中途就去写文件了，导致流程提前中断。
3.4 reviewer：质检 Agent 的安全感从哪里来
reviewer 我特意复用了 planner_model 而不是 worker_model。这里有一个考量：质检任务需要相对稳定的判断力，而不是创造性。低温度、逻辑较强的模型更适合判断“是否通过”；高温度、偏生成的模型更适合产出草稿。同一份配置里给不同 Agent 挂不同模型，通常可以更贴合它们各自的职责。
reviewer 的工具同样是空的，而且系统提示词里明确写着“只审查，不重写”。如果不写这条，reviewer 很容易一边审查一边自己动手改，把“质检”和“修改”两个动作混在一个 Agent 里完成，后面的流程控制就失去意义了。
3.5 让它跑起来：最小验证方法
bash复制openclaw run --config demo_content_flow.yaml
openclaw send --agent dispatcher --message "帮我写一篇关于本地部署开源模型的介绍"
跑起来之后，不要急着看结果，先看事件流。OpenClaw 的日志会把每一步消息流转都打出来：dispatcher 发出一条 task.new，executor 收到后开始查资料，发回 task.result，reviewer 收到后判断是否通过。如果一切正常，最终会看到消息流向 __final__，那就是一次成功的最小闭环。
我第一次跑通的时候，最深的感受是：多 Agent 的“效果”是否惊艳要取决于模型能力，但“能否跑通”完全取决于配置的逻辑自洽。只要路由规则没有死循环，工具权限不越界，记忆范围不混乱，一个最小的多 Agent 系统其实并不难搭起来。
4. 通信与编排设计：多 Agent 协作最容易出问题的一段
配置跑通之后，你就得开始面对真正的设计了。多 Agent 系统的上限，从来不是模型能力，而是通信与编排方式。这一节我讲透三种协作模式和一批调度细节。
4.1 三种协作模式：流水线、黑板、议事厅
流水线模式是最直观的，就是你上节看到的：A 完成后把消息发给 B，B 完成后再发给 C。它的优点是简单、可控，每一步都有明确的输入输出。缺点是并行度低，一旦链路中某个 Agent 失联，整条线都卡住，调试时很容易追到一个等待超时。
黑板模式是共享一块“公共区域”，每个 Agent 都可以读写。适合解决那些“谁先做都行”的任务，比如多个 Agent 同时收集不同来源的信息，统一投放到黑板上，再由汇总 Agent 读取。OpenClaw 里可以通过配置一个独立的 Agent 充当黑板，也可以把某份共享记忆当作黑板用。这种模式的优点是灵活，缺点是容易产生数据竞争，两个 Agent 同时写同一个字段时，后写的会覆盖先写的。
议事厅模式是多个 Agent 围绕同一个问题来回交换意见，直到收敛。这是效果上限最高、成本也最高的一种模式。我自己的使用体会是：两三个 Agent 讨论三到五轮还能基本收敛，一旦超过四个 Agent，讨论内容就开始发散，各种立场互相纠缠，最后很难自动达成一致。没有明确的收敛机制，谨慎采用。
4.2 调度参数：优先级、超时、重试与幂等
配置文件里的 max_rounds、timeout_sec 不是随便填的，它们的取值和你的任务复杂度直接相关。
先谈超时。executor 里如果挂了一个网络检索 Claw，单次检索可能就要十几秒，它再结合上下文生成结果，给 30 秒超时根本不够。我通常先跑一次不计时的完整流程，测出每个 Agent 的典型耗时，再给每个 Agent 分别设置超时时间。全局统一超时虽然省事，但往往导致某个快任务被慢任务拖累。
再谈重试。如果你的任务存在外部依赖，重试是必须的；但重试一定要附带任务 ID。OpenClaw 的 Message 里可以带业务字段，我只会在带 task_id 的消息上开启重试，重试时复用同一个 task_id，这样下游 Agent 即使收到重复消息，也可以通过去重逻辑避免执行两遍。不设幂等键的重试，等于把一次操作变成两次操作，后患无穷。
4.3 记忆配置：共享记忆与隔离记忆的取舍
记忆策略是我认为 OpenClaw 配置里最需要设计感的一块。它决定了 Agent 能看到多少历史信息。
配置里我给了 dispatcher 和 reviewer shared 类型记忆，executor 则用了更窄的 project_only。这么设计的原因很简单：调度者和质检者需要看到项目级上下文，才能理解任务全貌；执行者只需要看到本次子任务及相关产物，看多了反而被无关信息干扰。
很多时候出现的“多 Agent 不如单 Agent”的负面结果，根因就在共享记忆设错了。
比如你把执行 Agent 的记忆也设成 shared，它就会看到自己之前处理过的所有历史任务。一个新的子任务进来时，它的上下文里塞满了跟当前任务无关的旧消息，模型注意力被稀释，回答质量和稳定性都会直线下降。
我个人更推荐按比例处理：默认只共享“项目摘要”，把细粒度消息保留给对应 Agent 自己的独立记忆，等遇到跨 Agent 协作的任务时，再显式通过 Message 把必要信息带过去。
5. 跑起来后高频出现的四个故障：复盘完整的排查思路
这一节我不会直接丢答案，而是把每个故障的定位路径完整走一遍。排查多 Agent 问题就像拆线头，得顺着运行日志一层层往里摸。
5.1 故障一：Agent 互相等待，任务卡死
现象：流程跑到某个中间环节后，日志一直停留在“等待发送方返回结果”，直到超时。
我第一次遇到时，第一反应是网络问题，但测了网络之后发现对方接口完全正常。回去看路由规则，才发现自己配了一个环：A 完成通知 B，B 想让 C 验证，C 有一条规则是 to A 等待最终确认，而 A 又有一条规则“收到确认后通知 B”。消息在三个 Agent 之间转圈，谁也等不到最终的确认消息。
这种卡死的修复方法分两步。第一步，把路由规则画成一张有向图，人工扫一眼有没有环。第二步，如果业务流程上确实需要回环，那就给回环消息加一个“轮次计数器”，每转一圈计数加一，超过 max_rounds 时强制路由到人工处理队列，而不是继续转。
5.2 故障二：上下文越滚越大，响应质量迅速退化
现象：流程前两轮还很正常，到第四第五轮时，executor 开始重复之前提过的主张，或者直接把历史消息当成当前任务重新生成了一遍。
这个问题我见过太多次了。根因不是模型变笨，而是 executor 的记忆范围太大，把所有历史对话都装进了上下文。当相关任务消息被埋在一堆旧消息下面时，模型提取关键信息的能力就会失效。
节点的定位方法是看日志里每条 Message 的 token 统计。如果发现 executor 处理某条消息时的上下文长度已经超过它独立记忆的 70%，那基本就是记忆配置的问题。我会把 executor 的记忆改成“当前任务上下文 + 最近一轮消息摘要”，其中摘要由 dispatcher 在发送下一步任务时顺便带上，而不是让它自己全程翻旧账。
5.3 故障三：同一个任务被重复执行
现象：executor 对外部接口的调用次数统计显示，某个写操作执行了两遍，但 Message 日志里只有一条。
重复执行的头号嫌疑是重试机制。比如 executor 第一次调用外部接口时结果正常，但响应消息在返回给 reviewer 的途中因为路由规则匹配失败而丢包，触发超时重试，executor 不知情地又执行了一遍。
如果已经启用了重试，多 Agent 配置里就必须带上幂等逻辑。OpenClaw 的 Message meta 里有一个 dedup_key 字段，你可以在生成 task.new 时设置 dedup_key 为该任务的内容哈希。executor 在执行前先检查这个 key 是否处理过，处理过就直接返回上次的结果，这样无论重试几次，外部副作用都不会重复发生。排查时优先看日志里有没有 “duplicate skipped” 字样，有的话说明去重逻辑生效了，没有的话就是你根本没配置去重。
5.4 故障四：工具权限混乱，一个 Agent 越权操作
现象：日志里显示 reviewer 居然调用了一次写文件工具，影响到了生产目录。这个 Agent 在配置里根本没有那个 Claw。
这是我踩过最深的一个坑。排查时我一度以为是配置解析错误，反复看 agents.reviewer.tools，确认它确实只有空数组。后来才发现，问题出在“黑板共享”上：executor 把包含文件写入工具调用的上下文片段写进了共享记忆，而共享记忆被 reviewer 读取后，reviewer 的上下文里出现了对那个工具的引用和调用痕迹。
这种问题的本质是信息泄露导致权限越界。模型看到了共享记忆里的工具描述，就会认为自己也可以调用它。修复方案有两个层次：配置层面，共享记忆字段里过滤掉“工具调用痕迹”；架构层面，把共享记忆改成“只共享结论摘要，不共享完整交互记录”。我建议两层都做，第一层防漏，第二层兜底。
5.5 通用排查链路
以上四个故障虽然表象不同，但排查过程是共通的，我给你一套自己验证过很多次的执行顺序：
- 打开完整日志，按时间顺序从第一条 Message 开始看，不要先看报错。
- 找到消息流“应该拐弯”的那个点，在路由规则里对照这个点是否有明确转移。
- 看上下文消耗比例，是突然暴增还是稳步上升，据此判断是记忆还是路由问题。
- 检查所有重试入口，确认
dedup_key是否等于任务内容哈希。 - 最后才去怀疑模型本身。多 Agent 场景里，九成以上问题出自配置或编排，真正由模型能力引起的问题反而是少数。
6. 三个我在项目里反复用的配置模板与调参经验
前五节说的是配置逻辑，这一节直接给你能抄作业的模板。这三个模板我改过很多次参数，最终留下来的版本都比较简洁，你可以拿去做改造成你的任务。
6.1 通用双 Agent 模板：拆解 + 执行
yaml复制agents:
planner:
model: planner_model
system_prompt: |
你负责将复杂请求拆分成若干独立子任务，每次只发送一个子任务。
所有子任务之间无依赖，适合并行处理。拆分时明确输出格式。
tools: []
doer:
model: worker_model
system_prompt: |
你会收到一个独立的子任务，按步骤完成它并直接返回结果。
tools:
- claw.web_search
- claw.calculator
routing:
rules:
- from: planner
to: doer
on: task.new
- from: doer
to: planner
on: task.result
这个模板适合“先把复杂任务拆开、再逐步收集结果”的场景。真正跑起来时，我会在 planner 和 doer 后挂一个汇总 Agent，把所有结果拼成最终输出，实际是一个“拆解 - 执行 - 汇总”的三角结构。因为它结构简单，执行 Agent 只处理单步子任务，上下文保持得非常干净。
6.2 带审批节点的三 Agent 模板：执行后必须人工确认
yaml复制agents:
preparer:
model: worker_model
system_prompt: |
你负责准备候选方案，按模板输出方案 A 和方案 B。
tools: []
memory: project_only
reviewer_ai:
model: planner_model
system_prompt: |
你负责从成本、效率和风险三个维度初步评估方案，给出建议。
tools: []
memory: shared
human_审批:
mode: human
channel: approval
routing:
rules:
- from: preparer
to: reviewer_ai
on: proposal.ready
- from: reviewer_ai
to: human_审批
on: proposal.with_advice
- from: human_审批
to: preparer
on: approval.reject
注意到 human_审批 这个 Agent 的 mode: human。这类 Agent 不需要模型，它只提供一个消息通道，把待审批内容推送给真实用户，再把用户的决定投递回流程里。在多 Agent 流程中嵌人工节点，是所有成熟系统的刚需。强烈建议你把任何涉及金额、生产环境变更、对外发布的流程，都加上这样一道人工关卡。
6.3 我消耗过最多时间的一组调参与心得
第一是温度。planner 类 Agent 温度压在 0.1 以下，保证拆分稳定；executor 视任务创造性需求调到 0.3 到 0.7；质检类 Agent 永远不超过 0.2。很多多 Agent 系统表现飘忽，不是因为模型不对，而是给不同职责的 Agent 用了同一套温度。
第二是记忆上限。比起大刀阔斧地增加共享记忆，我反而会主动收缩它的范围。每个多 Agent 项目里，我都保留一个被验证过的记忆摘要策略：每次流程触发记忆写入前，先把旧摘要压缩到少于 300 字，再拼入新信息。这一步能让长任务的稳定性显著提升。
第三是日志级别。调试阶段我会把 log_level 设成 debug，看到所有 Message 流转；稳定运行后切到 info，只保留关键节点。日志不是越详细越好，详尽的日志会刷掉真正重要的错误信息，反而增加排查难度。
第四个不一定算参数，是我的习惯：每次改动配置前先复制一份备份，并记下当时的任务耗时、成功率等关键数据。多 Agent 调参与写代码最大的不同在于，改动一个 Agent 的 prompt，可能会影响整个路由链路上的行为。没有对照基线，你根本无法判断改动是变好还是变差。我在本地维护了一个简单的对照表，记录版本、改动点、平均耗时、通过率，调参效率比盲调高很多。
最后聊一点经验。多 Agent 配置的复杂度，通常是每个 Agent 增加一条路由，系统整体的行为不确定性就翻一倍。如果你刚开始接触 OpenClaw，我的建议是：从最小配置起步，把两个 Agent 跑稳了再加第三个；遇到跑不稳的情况，不要急着加 prompt 约束，先看是消息路由、工具权限、还是记忆范围的问题。配置里每多写一行，都要问自己：这行是真的在解决业务问题，还是在给前面的配置缺陷打补丁？想清楚这个，多 Agent 才能从“玩具”变成“工具”。