OpenClaw多Agent协作踩坑全记录：从翻车到跑通

好的，作为一位深耕AI工具领域多年的老手，我来帮你把这篇“翻车实录”重新梳理一遍，让它读起来更像是一位过来人的经验之谈，而不是机器生成的配置指南。 --- 最近折腾OpenClaw的多Agent团队协作功能，想搭建一个AI写作团队：运营主管阿强、研究员阿亮、写手阿文、审核员阿严，四个Bot协作写文章。想法很美好，但配置过程堪称“翻车现场”。今天就把这趟从怀疑人生到最终跑通的全过程掰开揉碎讲讲，帮后来人避开那些暗坑。 ## 一、先说说我要做什么 简单来说，就是我只跟阿强对话，由他自动协调其他三个Bot完成一篇完整的文章写作流程。 听起来很酷对吧？但配置过程中的每一步都藏着让你想摔键盘的陷阱。 ## 二、踩坑实录 ### 坑1：跨Agent通信权限没开（最隐蔽的坑） 现象是阿强收到任务后，只回了一句“好的，我立即协调团队”，然后就石沉大海。其他Bot毫无反应。 查日志才发现报错信息： ``` 需要设置 tools.sessions.visibility=all 才能向其他团队成员发送消息 ``` 问题出在`openclaw.json`中漏了一个关键配置。默认情况下，Agent只能看到自己的会话，压根儿不知道还有其他Bot的存在。 解决方案是在`openclaw.json`的`tools`部分加上这条配置： ```json "tools": {"sessions": {"visibility": "all"}} ``` 这个配置在官方文档里其实有写，但很多教程都一笔带过。栽过跟头的人才知道它有多重要——没有它，多Agent协作就是个空壳。 ### 坑2：文件路径错乱（最折腾的坑） 调度看起来正常了，但阿亮说大纲已经保存，阿文却抱怨找不到文件。查看日志的瞬间直接被逗笑： ``` 阿亮保存到：~/.openclaw/workspace/openclaw-camp-article/outline.md 阿文去读取：~/.openclaw/agents/writer/workspace/workspace/openclaw-camp-article/outline.md ``` 注意看，阿文的路径里多了个`workspace/workspace`，成了嵌套路径！ 原因在于每个Agent有自己的`workspace`目录，我让阿亮保存文件时用了相对路径`workspace/...`，结果不同Agent解析出来的路径千差万别。 解决方案很干脆：所有Agent共享的文件，必须使用绝对路径。例如： ``` ~/.openclaw/workspace/openclaw-camp-article/outline.md ``` 而不是： ``` workspace/openclaw-camp-article/outline.md ``` 经验之谈：SOUL.md里所有的文件路径都老老实实用`~/.openclaw/workspace/...`开头，确保大家都能找到同一个文件。 ### 坑3：agentToAgent.allow配错了（最无语的坑） 想开启Agent间的直接通信，配置了`agentToAgent`，但怎么都不生效。当时配的是这个： ```json "agentToAgent": {"enabled": true, "allow": ["sessions_list", "sessions_send", "sessions_history"]} ``` 看出问题了吗？我把工具名填进`allow`字段了！ 正确的配置应该是这样： ```json "agentToAgent": {"enabled": true, "allow": ["manager", "researcher", "writer", "reviewer"]} ``` `allow`字段应该填的是Agent的ID，不是工具名。配置项的命名确实容易产生误导——它指的是允许哪些Agent之间进行通信，而不是允许使用哪些工具。 ### 坑4：全局tools.deny误伤友军（最坑的坑） 我在`openclaw.json`的根目录配置了全局限制： ```json "tools": {"deny": ["write", "edit", "exec", "apply_patch"]} ``` 本想限制一下阿强的写入权限，结果所有Agent都不能写文件了——阿文连文章都保存不了。 原因在于`tools.deny`放在根目录会影响到全部Agent。如果想要单独限制某个Agent，必须在该Agent的配置里添加： ```json { "id": "manager", "name": "阿强", "tools": { "allow": ["sessions_list", "sessions_send", "sessions_history", "read"], "deny": ["write", "edit", "exec", "apply_patch", "bash"] } } ``` 权限控制要精确到Agent级别，千万别图省事搞全局限制，否则最后连自己一起坑。 ### 坑5：以为能看到所有Bot的回复（最天真的坑） 我天真地以为配置了4个Bot，就能看到4个窗口同时输出。结果只收到阿强的回复，其他Bot仿佛凭空消失了。 真相是：这本身就是正常现象。`sessions_send`的工作方式就是后台通信。阿强通过`sessions_send`向阿亮发送消息，阿亮在自己的后台会话里处理，回复也是直接给阿强，而不是给你。 最终你只能看到阿强汇总后的结果，其他Bot的对话过程在后台一闪而过。如果想要“过程清晰可见”，需要使用`sessions_spawn`（子智能体）方式，这属于后续进阶教程的内容了。 ## 三、跑通后的效果 搞定所有坑之后，整个协作流程是这样的： 我给阿强发送需求： ``` 你好，我需要写一篇介绍OpenClaw的文章 要求： - 主题：OpenClaw是什么，为什么现在这么火 - 目标读者：零基础小白 - 字数：2000左右 - 风格：通俗易懂 请协调团队完成。 ``` 大约10分钟后，阿强回复： ``` ✅ 任务完成！ 执行摘要： 阶段1：资料搜集（阿亮）- 已完成 阶段2：撰写初稿（阿文）- 已完成 阶段3：质量审核（阿严）- 已完成 阶段4：修改定稿（阿文）- 已完成 成果文件： - 终稿：~/.openclaw/workspace/openclaw-camp-article/final.md [文章内容...] ``` 所有中间产物（大纲、初稿、审核报告）都保存在共享目录里，想看随时都能查看。下面是整个过程实录： **1、给阿强下达任务需求** **2、研究员-阿亮收到任务** 阿亮收到任务开始干活，然后将交付物转给写手-阿文。 **3、写手-阿文收到任务** 先是收到了阿强分配的任务，先读取风格指南，等待阿亮的大纲。 等到阿亮的大纲后开始写作，完成后转交给审核员-阿严来审核。 **4、审核员-阿严收到写手阿文的文章** **5、写手-阿文收到阿严的审核意见，开始优化** **6、运营主管-阿强收到所有成员的进展状态已完成** **7、我收到阿强的汇报消息** **8、协作过程中产生的会话记录** 每个Bot都有sessions记录产生，证明协作过程中他们之间确实有通话记录，感兴趣的话可以点进去查看详情。 以上只是一个团队协作的雏形，后续改造成子Agent协作后，过程会更加直观，灵活性也会更高。 ## 四、核心配置清单 如果你也想搭建这样一个团队，下面是经过验证的完整配置方案： ### 1. openclaw.json 关键部分 ```json { "agents": { "list": [ { "id": "manager", "name": "阿强", "workspace": "~/.openclaw/agents/manager/workspace", "agentDir": "~/.openclaw/agents/manager/agent", "tools": { "allow": ["sessions_list", "sessions_send", "sessions_history", "read"], "deny": ["write", "edit", "exec", "apply_patch", "bash"] } }, { "id": "researcher", "name": "阿亮", "workspace": "~/.openclaw/agents/researcher/workspace", "agentDir": "~/.openclaw/agents/researcher/agent" }, { "id": "writer", "name": "阿文", "workspace": "~/.openclaw/agents/writer/workspace", "agentDir": "~/.openclaw/agents/writer/agent" }, { "id": "reviewer", "name": "阿严", "workspace": "~/.openclaw/agents/reviewer/workspace", "agentDir": "~/.openclaw/agents/reviewer/agent" } ] }, "bindings": [ { "agentId": "manager", "match": { "channel": "telegram", "accountId": "manager" } }, { "agentId": "researcher", "match": { "channel": "telegram", "accountId": "researcher" } }, { "agentId": "writer", "match": { "channel": "telegram", "accountId": "writer" } }, { "agentId": "reviewer", "match": { "channel": "telegram", "accountId": "reviewer" } } ], "tools": { "sessions": { "visibility": "all" } } } ``` ### 2. SOUL.md 文件路径规范 所有文件路径都使用绝对路径： ``` - 大纲：~/.openclaw/workspace/openclaw-camp-article/outline.md - 初稿：~/.openclaw/workspace/openclaw-camp-article/draft-v1.md - 审核报告：~/.openclaw/workspace/openclaw-camp-article/review-v1.md - 终稿：~/.openclaw/workspace/openclaw-camp-article/final.md ``` ## 五、小结 这趟踩坑之旅让我深刻明白了几个道理： 1. **文档要看全：** `tools.sessions.visibility`这种关键配置，很多教程都是一笔带过，但它恰恰是能否玩转多Agent的核心开关。 2. **路径要用绝对：** 相对路径在多Agent场景下就是一颗定时冲击波，不知道什么时候就会炸得你晕头转向。 3. **配置要精确到Agent级别：** 全局配置省事一时爽，排查火葬场。每个Agent的权限和能力需要独立定义。 4. **预期要对齐：** `sessions_send`本质上就是“后台协作”模式，看不到中间过程是正常的，别因为这个怀疑配置出了问题。 现在我的AI写作团队已经能稳定运转了。从给阿强下达任务到拿到最终稿件，全程大约10分钟，比自己一个人从头折腾到完要快得多。 如果你也在玩OpenClaw的多Agent功能，希望这篇踩坑记录能帮你少走一些弯路。