前阵子接了个内部工具改造的活儿需要在 OpenClaw 里同时跑多个 Agent让它们各自负责不同环节。一开始我以为只是多写几个配置块的事真正动手才发现多 Agent 的难点根本不在“加”而在“让它们各干各的、不打架、还能互相配合”。这篇文章就把我从零到一添加多个 Agent 的完整过程、配置思路和踩过的坑整理出来给同样在折腾 OpenClaw 的朋友一个参考。如果你还没用过 OpenClaw简单说它是一个面向多智能体编排的开放框架支持通过配置文件注册不同的 Agent给每个 Agent 分配角色、工具、记忆和模型参数然后让它们在一个工作流里协同完成复杂任务。适合的场景包括内容流水线、数据处理、自动化测试、多角色对话系统等。支持命令行启动和 HTTP API 调用整体比较轻量适合个人项目和中小团队内部使用。1. 先搞清楚多 Agent 架构OpenClaw 的设计思路1.1 单 Agent 的瓶颈在哪里我们在单 Agent 模式下做的事越多越容易发现几个问题。第一是上下文碎片化一个 Agent 既要做需求拆分又要写代码还要做 review对话一长早期信息很容易被冲掉导致后面答非所问。第二是工具冲突如果一个 Agent 同时挂了代码执行工具和外部 API 工具某些场景下它会为了“完成任务”自己乱调工具流程完全不可控。第三是故障放大单 Agent 一旦在某一步跑偏整条链路就全废了定位问题还要从头翻日志。所以多 Agent 的核心价值并不是“看起来高级”而是把职责边界拉清楚让每个 Agent 只关注一件事。这件事在 OpenClaw 里做得比较舒服因为它把 Agent 这个概念做成了配置实体你可以像写简历一样定义每个 Agent 的“岗位职责”然后通过路由和编排规则把它们组合起来。1.2 三种常见多 Agent 拓扑选型多 Agent 的拓扑结构本质上是“任务怎么流动”的问题。我列一下实际中常见的三种拓扑模式任务流动方式适用场景缺点串联PipelineA 完成后把结果交给 B流程固定先后依赖强单点故障会导致整链中断并联Parallel同一任务广播给多个 Agent汇总结果需要多方意见或并发处理结果冲突时难以收敛主从Supervisor Workers主 Agent 负责拆解和分发Worker 负责执行复杂任务需要动态规划主 Agent 容易成为瓶颈OpenClaw 对这三种模式都有支持但官方文档和社区实践都比较推荐“主从模式”。原因也很简单绝大多数真实任务既有顺序依赖又有可并行部分完全串行太慢完全并行又没法兜底。主从模式允许你灵活混搭主控 Agent 拆出来的子任务可以顺序执行也可以并行派给不同 Worker。1.3 OpenClaw 推荐的主从协作模式主从模式里主控 Agent通常叫 Coordinator 或 Supervisor不直接干活它的核心职责是三件事理解用户请求、拆解为子任务、把子任务路由给对应 Worker Agent。Worker Agent 自己只保留某一类专长比如一个负责代码生成一个负责文档整理一个负责测试用例生成。这样每个 Worker 的 prompt 和工具集都可以做得很窄很专效果反而比全能的单 Agent 好很多。有个容易被忽视的点主控 Agent 的质量决定了整体上限。因为所有任务都经过它分发一旦拆解逻辑有问题Worker 再强也白搭。所以在 OpenClaw 里配置主控 Agent 时我会额外给它挂一个“任务拆分专用工具”让它能输出结构化的子任务清单而不是让它在对话里随口分配。这个细节后面实操部分会讲到。2. 动手前准备配置文件结构与 Agent 注册基础2.1 认识 OpenClaw 的配置文件格式OpenClaw 使用 YAML 作为主要配置文件格式默认入口文件通常是openclaw.yaml或项目目录下的config/openclaw.yaml。整个文件顶层结构大致是version: 2.0 project: name: my_multi_agent_demo global: message_queue: local timeout: 120 agents: - name: coordinator enabled: true ... routes: - pattern: ... target: ...其中agents区块就是注册 Agent 的地方每新增一个 Agent就往这个列表里加一项。YAML 本身的缩进规则比较严格用空格不要用 Tab这个在调试时特别容易翻车。我习惯在写完配置后先跑一遍openclaw validate让框架自己检查格式和字段合法性再启动服务。2.2 定义第一个 Agent关键字段解析一个典型的 Agent 配置块长这样agents: - name: writer description: 负责生成文章初稿 role: worker enabled: true model: provider: local name: llama-3-8b-instruct temperature: 0.7 max_tokens: 2048 tools: - search_knowledge_base - text_editor memory: type: local_vectordb collection: writer_mem system_prompt: 你是专业的内容创作者输出要求结构清晰、语言自然。 retry_policy: max_retries: 2 backoff_seconds: 5这些字段里我最想强调三个。第一个是role它决定了这个 Agent 在编排系统里的身份是 coordinator 还是 worker。OpenClaw 对两类角色有不同的调度策略写错会导致路由不生效。第二个是tools它必须以数组形式给出工具名称这些名称必须和tools区块或插件中注册过的名字完全一致大小写都不能错。第三个是memory多 Agent 场景下如果所有 Agent 共享同一个记忆库会出现信息串线所以每个 Worker 最好单独分配 collection。2.3 角色隔离与权限最小化设计多 Agent 配置里最容易出的安全问题是权限控制太粗。举个例子如果所有 Agent 都能调用“执行 Python 代码”的工具那么任何一个 Agent 被 prompt 注入攻击都能直接执行任意命令。所以在定义 Agent 时我会坚持一条原则一个 Agent 只拥有完成本职任务的最小工具集。比如数据分析 Agent 可以只挂read_csv、run_sql和plot_chart绝不挂shell_exec。文档 Agent 可以挂search_knowledge_base和text_editor但不挂任何与外部网络请求相关的工具。这样做不仅安全还能减少 Agent 的决策负担它不需要在十几个工具里挑来挑去。另外如果 OpenClaw 部署在多人共用的环境里还可以配合namespace字段隔离不同项目的 Agent 资源这个在 2.x 版本以后支持得比较好。3. 完整实操从 1 个 Agent 扩展到多个 Agent3.1 场景设定构建一个内容运营小团队为了讲清楚整个过程我用一个常见场景来做例子搭建一个“内容生产流水线”多 Agent 系统。目标是把一篇原始素材自动改写成一篇结构完整、风格自然的文章。传统单 Agent 做法是“一个人全干”我这里改成四个 Agent 协作chief_editor主控 Agent负责解读原始需求、拆解步骤、分发任务。writer负责根据素材写初稿。reviewer负责从逻辑和语法角度审核初稿返回修改意见。formatter负责把终稿整理成 Markdown 格式输出到指定目录。这个团队的协作流是chief_editor 接收素材 → 分配给 writer → writer 完成后交给 reviewer → reviewer 审核 → 如果需要修改则退回 writer否则交给 formatter → formatter 输出文件。3.2 逐个添加 Agent 的具体步骤我实际操作时不会一次性把四个 Agent 全写进配置再启动那样出问题不好定位。正确的做法是先加一个测通再加下一个再测通。第一步先加 writer 一个 Agent并在 routes 里写一条简单规则把默认请求路由给它验证它能响应。agents: - name: writer role: worker model: provider: local name: llama-3-8b-instruct tools: - text_editor system_prompt: 你是内容创作者根据素材写出结构清晰的文章。启动后手动发一条消息测试 writer 是否能正常回复。没问题后再添加 reviewer。这里有一个容易踩的坑如果只是把 reviewer 加进 agents 列表不对 routes 做调整OpenClaw 默认还是会随机或按顺序选择 Agent导致请求时而到 writer 手里时而到 reviewer 手里效果完全不可控。正确的做法是同时配置路由。在routes区块里写routes: - pattern: 写作任务 target: writer priority: 10 - pattern: 审核任务 target: reviewer priority: 10priority数字越大越优先。当多条规则都能匹配时OpenClaw 会优先走 priority 高的。这里我建议所有 Worker 的规则优先级保持一致而主控 Agent 的规则优先级最高保证入口统一。第三步是把 chief_editor 加上并让它成为唯一对外的入口。实现方式是把 chief_editor 的role设为 coordinator然后把对外路由全指向它agents: - name: chief_editor role: coordinator model: provider: local name: qwen-14b-chat tools: - task_planner system_prompt: 你是主编负责拆解任务并分发给合适的成员。同时把 chief_editor 设置为默认接收方即配一条catch-all路由routes: - pattern: .* target: chief_editor priority: 1这样任何没有匹配到具体规则的消息都会先到 chief_editor 手里由它决定下一步。3.3 启动与验证启动日志里看什么配置写完后启动命令一般是openclaw validate openclaw start --config openclaw.yaml --port 8080启动成功后日志里会逐条列出已加载的 Agent。我习惯重点看几行[INFO] Agent registered: writer (roleworker) [INFO] Agent registered: reviewer (roleworker) [INFO] Agent registered: chief_editor (rolecoordinator) [INFO] Route registered: pattern.* - chief_editor, priority1如果某个 Agent 没有出现在日志里常见原因是 YAML 缩进错误或字段拼写不对。如果出现了但路由没有注册说明 routes 里的 target 名称和 Agent 名称对不上。这里的名字是大小写敏感的Writer和writer是两个完全不同的东西。验证阶段最实用的工具是 OpenClaw 自带的 HTTP API。发送一个测试请求curl -X POST http://localhost:8080/chat \ -H Content-Type: application/json \ -d {message:根据素材写一篇短文素材OpenClaw 多 Agent 配置体验。,session_id:test-001}正常情况会先收到一条 chief_editor 的响应表示它已经开始处理随后能在日志里看到dispatch to writer表示任务被正确分发。如果看不到 dispatch则说明路由或 role 配置有问题。4. 多 Agent 通信与协作的进阶配置4.1 消息路由规则让请求找到正确的 Agent多 Agent 系统里最核心的机制就是路由。OpenClaw 的路由规则支持正则表达式、关键字匹配和优先级配置足够的规则可以让请求自动流向正确的 Worker。实际工作中我发现关键字匹配比正则更常用。因为自然语言的表达非常多样用精确正则很难覆盖。OpenClaw 的pattern字段实际上支持的是正则语法但你完全可以用简单的子串正则来模拟关键字匹配比如routes: - pattern: .*(编写|写作|初稿).* target: writer - pattern: .*(审核|检查|意见).* target: reviewer - pattern: .*(格式化|排版|markdown).* target: formatter路由规则的另一个重要细节是顺序无关因为框架会结合优先级和匹配度做综合判断。如果你发现请求总是跑到错误的 Agent不要调整规则位置而是检查 priority 和正则的具体写法。正则表达式建议先在本地用在线工具测试好再写入配置不要直接在 YAML 里猜。4.2 任务编排顺序、并行与条件分发简单的“路由匹配”只能做一对一分发要做复杂的流水线还需要在 OpenClaw 里定义 workflow。这部分是配置多 Agent 时最需要耐心的地方因为你要刻意去描述“谁先谁后、什么条件下走哪条分支”。以一个简单的编排块为例workflows: content_pipeline: steps: - name: draft agent: writer input: source_material - name: review agent: reviewer input: draft on_failure: next: draft - name: format agent: formatter input: review这个配置描述了一个顺序流程writer 产出 draft → 进入 reviewer → 如果 review 失败比如返回答复不符合要求则回到 draft 步骤重新生成 → 通过后进入 formatter。on_failure的next字段就是条件分支OpenClaw 会依据上一 Agent 输出中的status字段决定跳转。如果你有多个 Worker 可以并行处理也可以用parallel声明workflows: multi_research: steps: - name: parallel_research type: parallel agents: - data_analyst - competition_analyst gather: concat需要注意的是并联模式下结果汇总策略gather很关键。是简单拼接concat还是做投票vote取决于场景。我倾向于只在实际需要多角度输入、且结果不严重冲突的场景使用并联否则汇总那一步很容易让下游 Agent 无所适从。4.3 共享工具与独立工具的配置经验多 Agent 之间工具怎么分配也是一门学问。OpenClaw 允许你在全局区块定义工具也允许在每个 Agent 内部覆盖或追加。实践中最稳的方案是全局工具只放所有 Agent 都用得到的基础设施工具比如日志记录、会话管理、权限校验。独立工具把任务相关的工具直接挂在对应 Agent 下。举个例子如果整个系统共用一个向量知识库那我们可以把它注册为一个全局工具search_knowledge_base所有 Agent 都可以访问。但另一个“写入知识库”的工具add_document_km就只给负责维护文档的 Agent 用。否则多个 Agent 都能写知识库容易把数据搞乱。我遇到过的一个问题是两个 Worker 都挂了同一个text_editor工具但它们的 system prompt 对格式要求不同一个要求 MD一个要求纯文本结果同一个工具在两个 Agent 手里的行为逻辑不一致产出格式经常打架。后来我把全局工具里跟“产出格式”相关的参数都抽出来在 Agent 配置里用tool_parameters覆盖agents: - name: writer tool_parameters: text_editor: output_format: markdown max_line_width: 80这样同一个工具在不同 Agent 下就有了不同的默认参数协作时输出风格更统一。5. 常见问题与排查技巧5.1 Agent 之间互相“抢活”怎么办症状发送一个写作请求结果 reviewer 先响应了或者 chief_editor 没有将任务分发而是自己直接写了一篇。排查思路是三步走。第一步检查路由配置确认目标正则表达式是否写得太宽。比如我一开始写的是pattern: .*且 priority 很高那所有请求都会匹配到它其他规则就形同虚设。第二步检查role字段如果 reviewer 的 role 写成了 coordinator它就会变成主控 Agent参与任务分发而不是只做执行。第三步检查 Agent 的description和system_prompt里有没有互相矛盾的角色设定。OpenClaw 在协调模式下会把部分信息注入给主控 Agent如果描述含糊主控 Agent 自己也会困惑。5.2 配置了不生效先查这四个位置配置不生效绝大多数不是框架 bug而是下面四种情况之一现象可能原因解决方法新 Agent 启动后看不到YAML 缩进错误用openclaw validate检查路由总走到旧 Agent缓存了旧配置重启时加--no-cache参数Agent 名字对不上routes 和 agents 名称大小写不一致统一用小写命名工具不生效工具未在插件里启用检查plugins区块是否正确加载我印象最深的一次改了配置但一直不生效折腾很久才发现是框架默认缓存了编译后的配置产物在启动命令里加--no-cache就好了。这个参数确实不显眼文档里也没有加粗提示但排查时值得第一个试。5.3 资源开销与模型调度的优化建议多 Agent 最直接的代价就是资源开销。四个 Agent 如果各自独立加载一个大模型显存和推理延迟都很难看。我的做法有两个。一是给不同 Agent 配置不同规格的模型。主控 Agent 需要更强的推理能力用大一点的模型Worker Agent 任务垂直用 7B 或 8B 的小模型就够。OpenClaw 支持在 Agent 级别配置model.provider我这边是把大模型和小模型都注册到本地推理服务里然后按 Agent 分配。二是开启模型实例共享。OpenClaw 的global.model_pool配置可以让多个 Agent 复用同一个模型实例代价是单实例并发能力有限。建议配合max_concurrent_requests做限流比如设为 4避免所有请求同时打到同一个模型上造成排队。另外还有一个 token 成本技巧给每个 Worker 配一个独立的memory但是把memory.retain_count调小比如只保留最近 6 轮上下文。这样能显著降低长会话中的 token 消耗对长流水线任务尤其明显。写在最后的一点体会整套配置流程走下来我最大的感受是OpenClaw 的灵活性是把双刃剑。你可以像搭积木一样定义各种拓扑但如果一开始没有把角色边界、路由规则和工具权限想清楚后面调起来非常痛苦。我个人建议不管任务多简单都按照“定义角色 → 最小工具集 → 路由测试 → 编排串联”这个顺序来做先单点后整体不要跳步。最后再分享一个小技巧调试阶段把global.log_level设为debug然后在日志里同时关注dispatch和workflow两个关键词它们能清晰地展示出任务在 Agent 之间的流向。这个习惯帮我省下的排查时间远超做多 Agent 配置本身花的时间。