OpenClaw多Agent架构实战：从单提示词到主控编排的配置指南

很长一段时间我以为只要在一份巨大的提示词里堆满角色设定就能让同一个 OpenClaw agent 同时干十种活。后果想必你也猜到了前半段还算正常一旦聊到第 30 轮它就会把文档文件夹的路径当成代码仓库的路径去操作把我整理好的文件名目录忘得一干二净。后来我把整个架构拆成了“一个主控 几个专职 agent”也就是 OpenClaw 的 multi-agent 模式问题才真正被根治。这里面有配置骨架、角色权限、会话路由和记忆隔离一大堆东西要理清。这篇教程就专门写给那些已经跑通过单 agent、现在正打算扩展成多 agent 协作体系的人。我尽量按照我自己的落地顺序来讲先讲为什么值得拆再讲配置目录怎么搭然后讲角色隔离、会话路由、记忆分区最后是我踩过的几个真实坑。如果你想直接照抄方案也可以跳过原理直接看代码块但我还是建议你回头把“为什么”读一遍。因为多 agent 真正难的不是配置语法而是你想不明白每个 agent 的职责边界到底画在哪里。1. 为什么“一主多从”才是多 agent 项目的最佳开局先说一个可能让人不太舒服的结论如果你的目标只是让 agent 会聊天、会查资料、会干点杂活那你根本不需要多 agent。单 agent 加一堆工具也能活得很好。什么时候必须拆当你开始觉得“这个 agent 怎么老是用错工具”“这个对话历史怎么越看越乱”的时候就是拆分的信号了。1.1 单 agent 单提示词的三个真实瓶颈我最早是在同一个 agent 上做“全栈”让它既管文档、又能整理文件夹、还能搜索外部资料。为了让它能区别这几种场景我在系统提示词里写了长长的分支规则。刚启动时确实很听话但对话轮数一多就露馅它会把“把今天的工作日志归档”理解成“去代码仓库里归档”因为它已经分不清当前的上下文是文档任务还是代码任务。这种问题的根源在于单 agent 的上下文窗口是共享的。文档任务和代码任务的中间结果互相污染工具调用的权限也无法细分。你不可能让同一个 agent 同时在“只能读写某个目录”的前提下又让它“只能访问某台服务器”。权限边界一旦模糊后续所有安全配置都是白搭。还有一个被大多数人忽略的问题是记忆冲突。单 agent 的长期记忆如果不做隔离它会把 A 用户闲聊时提到的名字当成 B 用户项目里的真实干系人。我见过最离谱的一次是把一个用户随口说的“想买台新笔记本”记录成了项目采购需求最后差点真去调用下单工具。从那之后我坚决不再把所有用户的对话塞进同一份记忆里。1.2 两种多 agent 组织方式我为什么选主控编排多 agent 的组织方式大体上有两条路线一种是“群聊式”几个 agent 全部订阅同一个对话流谁抢到算谁的另一种是“主控式”一个主 agent 负责承接原始请求拆解后再转给具体的专职 agent。群聊式看起来自由实际上很容易乱。多个 agent 同时响应同一个话题时你需要额外的仲裁逻辑来判断谁的回复更准确还要处理两个 agent 抢着调用同一个工具的问题。OpenClaw 虽然支持这种模式但我一般只在测试阶段用因为调试起来真的头大。主控式的好处是思路直观入口只有一个用户不需要知道身后站着几个 agent。主控 agent 的角色更像一个“客服前台”它不负责具体内容的生产只负责判断用户的意图然后把任务转给“文档处理”“数据分析”“代码审查”这些后台的专职 agent。这种模式最适合从单 agent 平滑迁移因为用户侧看到的仍然是一个统一入口。2. 骨架搭建一个 OpenClaw 多代理项目的目录与配置结构OpenClaw 的多 agent 配置并不复杂但如果你把所有 agent 塞进同一个 YAML 文件那维护成本会高到让你怀疑人生。我的建议是从一开始就按目录拆分配置让每个 agent 独立成文件再用主配置文件做聚合。2.1 目录结构让每个 agent 都是独立的“配置文件单元”我现在的项目目录长这样openclaw-project/ ├── config/ │ ├── main.yaml │ └── agents/ │ ├── coordinator.yaml │ ├── file-agent.yaml │ ├── code-agent.yaml │ └── search-agent.yaml ├── memory/ │ ├── shared/ │ └── agents/ ├── data/ │ ├── uploads/ │ └── output/ ├── logs/ │ └── agent-events.log └── .envconfig/agents 目录下每个 agent 都有自己独立的配置文件和工具清单。main.yaml 只负责定义全局默认值、路由规则和调度参数。这样做的第一个好处是你改某个 agent 的模型或工具权限时不需要去翻动一大坨共享配置也不会顺手改坏其他 agent。第二个好处是版本管理。每个 agent 的配置变更可以在 git 提交记录里清楚看到。我习惯在配置文件里写一个 version 字段一旦某个 agent 升级了模型或换了工具提交时顺手把版本号改掉。这样线上出问题时我可以很快找到是哪个版本的行为变了。2.2 主配置文件全局默认值与代理装载打开 config/main.yaml核心内容大致是这些server: host: 127.0.0.1 port: 8080 secret: ${OPENCLAW_SECRET} defaults: provider: ${OPENCLAW_PROVIDER} model: ${OPENCLAW_MODEL} temperature: 0.6 max_tokens: 4096 request_timeout: 60s agents: - name: coordinator file: agents/coordinator.yaml - name: file-agent file: agents/file-agent.yaml - name: code-agent file: agents/code-agent.yaml - name: search-agent file: agents/search-agent.yaml这里要注意两点。第一defaults里只放所有 agent 都通用的配置比如供应商、默认模型和超时时间。个别 agent 需要不同模型时在它自己的配置文件里覆盖即可。第二agents列表是注册表每个 agent 通过 file 字段指向独立配置这样主配置文件本身保持极简不会被各个 agent 的长篇工具说明塞满。启动时我一般用一条命令openclaw start ./config/main.yaml --port 8080建议把 secret、provider key 这类敏感信息统一放到 .env 文件里不要直接写在 YAML 中。OpenClaw 启动时会自动读取环境变量YAML 里的${OPENCLAW_SECRET}占位符会被正确替换。我见过有人把 API key 明文提交到 git 仓库结果整个团队都能看到这是多 agent 项目里最基础也最容易犯的安全错误。2.3 agent 自描述为什么 description 字段比你想的更重要在 OpenClaw 里每个 agent 的 description 不只是给人看的注释它参与主控 agent 的意图路由判断。主控 agent 会拿着用户输入去匹配各专职 agent 的 description匹配度高的优先转交。所以这个字段必须写成“机器可理解的自然语言”而不是“这个 agent 负责文档”。我习惯在 description 里明确三件事这个 agent 能做什么、它能访问哪些数据、它在什么情况下必须拒绝请求。# file-agent.yaml display_name: 文档处理助手 description: 负责文件上传、目录归档、格式转换、文件内容摘要。可以读取 uploads 和 output 目录不允许执行代码或访问代码仓库。仅在用户明确要求文件操作时才接收任务。这样写之后主控 agent 收到“把今天的报表转成 PDF”时能准确匹配到 file-agent收到“看看代码里有没有内存泄漏”时则不会错误地转给 file-agent。你要知道路由错了比路由不到更麻烦因为错配的任务会让专职 agent 拿它不会的工具硬干最后给你一堆错误结果。3. 每一个 agent 都是一份独立的“岗位说明书”模型、温度、工具集多 agent 的“多”不是数量上的堆砌而是身份上的隔离。子 agent 配备独立模型和工具集才能真正做到互不干扰。这一步如果偷懒后面你就要付出成倍的调试成本。3.1 模型选型的差异不是所有 agent 都该用同一个“大脑”不同 agent 的任务复杂度差异很大。我的分配逻辑是“主控 agent 用前沿模型专职 agent 按任务重量分级”。主控 agent 是唯一接触用户原始输入的角色它需要理解长句、识别意图、做任务拆解所以我给它配最大的上下文窗口和最强的推理模型。而专职 agent 的任务模式相对固定比如“把 Markdown 转成 PDF”“提取压缩包里的文件列表”这种任务用轻量模型就够了响应快不说成本还低一大截。# code-agent.yaml model: provider: ${CODE_AGENT_PROVIDER} name: ${CODE_AGENT_MODEL} temperature: 0.2 max_tokens: 8192code-agent 是典型的“重工具”类型模型不该太有“创造性”temperature 直接拉到 0.2让它只按事实干活。反过来负责文案生成的 agent我会把 temperature 调到 0.8 左右让输出更灵活。这里的原则是工具越重、行为越需要确定性temperature 越低工具越轻、输出越偏创意temperature 可以适当拉高。3.2 工具白名单比“什么都能调用”更安全的默认策略多 agent 环境里工具权限不应该继承全局。我见过默认配置里给所有 agent 都塞了网络搜索工具结果文档处理 agent 在归档时突然去搜索“最佳文件命名规范”白白浪费了一轮请求。我现在的做法是每个专职 agent 的配置里只列出它能调用的工具并且加一个明确禁止的 ignore 字段# file-agent.yaml tools: allow: - file_read - file_write - archive_list - file_convert deny: - code_exec - web_search - http_request主控 agent 则保留完整工具列表但主控更侧重“转交”它真正自己执行的工具只有会话管理和任务分配其他请求都走内部路由。你可以在日志里观察如果主控 agent 频繁直接调用了某个专用工具说明路由没写好或者你给主控配的工具太全了它懒得转交。这是个很值得警惕的信号。3.3 专属系统提示词岗位说明要写进“入职第一课”系统提示词就是每个 agent 的“入职培训”。子 agent 的系统提示词要和它的工具配置对齐不要写一堆它根本做不到的事。我写子 agent 提示词时会用“你只负责……别人不会把其他任务交给你”这样强边界的句式。这对模型有实际的引导作用当它收到一个不该它处理的任务时它会说“这不是我的职责范围”而不是硬着头皮乱搞。我还会在提示词里写清楚“收到任务后先确认自己是否有对应的工具权限没有权限就返回错误说明”这能避免很多权限报错被白白吞掉。4. 会话路由把用户请求精确分配给正确的 agent路由是整个多 agent 系统的中枢神经系统。配置得当用户根本感觉不到背后有几个分身配置不当用户会看到多个 agent 抢话或者互相踩脚。4.1 基于意图的三级路由规则我使用的是从粗到细的三级路由先看关键词再看 agent 描述匹配度最后看上下文兜底。在 OpenClaw 中我会在主配置文件里定义一个 routing 段routing: rules: - name: 文件类任务 contains: [文件, 文档, 报表, PDF, 归档] target: file-agent priority: 90 - name: 代码类任务 contains: [代码, 仓库, BUG, 接口, 报错] target: code-agent priority: 80 - name: 搜索类任务 contains: [查找, 搜索, 查一下, 最新, 资料] target: search-agent priority: 70 - name: 默认兜底 match: .* target: coordinator priority: 0关键词规则的优先级从上到下递减。这里我的经验是优先匹配“动词对象”的组合比如“把报表转成 PDF”“报表”和“PDF”都指向文件类任务非常明确。但“找一下那个文档在哪”这种句子搜索意图和文件意图同时存在我会让主控 agent 先收下再根据上下文二次判断。4.2 当规则冲突时主控 agent 的“超能力”规则的硬性关键词不可能覆盖所有口语表达。所以 OpenClaw 里永远要留一手主控 agent 在规则没有命中时可以调用一个内部函数来做出更精细的意图识别。这个函数会把输入同时发给注册的所有子 agent让每个子 agent 内部自评“这个任务像我做的吗”然后把评分最高的 agent 返回出来。internal_functions: - name: resolve_agent_by_intent input_keys: [query, context] method: self_assess这是一层软路由效果比关键词硬规则好很多但必须在性能上做保护。我给这个函数设置了最大评估次数为 3且每次评估超时 8 秒防止某个子 agent 反复思考导致整体卡死。实测下来二级软路由能兜住大约 85% 的模糊请求。4.3 会话归属同一个用户必须始终找同一个分身多 agent 环境下会话隔离是一个隐蔽的坑。如果用户在第二句说“刚才那份报表导出好了吗”系统却把这句话路由到了 search-agent那它肯定不知道“刚才那份报表”是什么。OpenClaw 的会话路由不只按消息内容匹配还要绑定用户 ID 和会话 ID。session: isolation: user_scope key_fields: [user_id, session_id] fallback_to_latest: true我建议把 session key 设为 user_id session_id 的组合并且要求在创建新会话时显式传入。如果找不到上一轮的路由目标fallback 应该回到 coordinator而不是重新随机分配。这很重要宁可让主控重复问一句“你想处理哪个文件”也不要让文件处理的中间状态丢在某个不相关的子 agent 里。5. 编排手记一旦任务被转交如何确保结果能汇回多 agent 系统里最怕的不是“任务没人接”而是“任务转了但结果回不来”。你要把整个流程当成异步事件总线来设计而不是同步的函数调用。5.1 任务转交的三种形态OpenClaw 里 agent 之间的协作我主要用过三种形态按耦合度从高到低排列第一种是同步直转主控 agent 调用子 agent 的接口后一直等结果返回。这种形态逻辑最简单适合“问题很短、答案很快”的场景比如查个天气、算个日期。缺点是子 agent 一旦超时整个请求也会超时用户体验会很差。第二种是异步任务队列主控把任务封装成一条消息推到消息队列子 agent 消费后把结果写回指定的输出主题主控再通知用户。这种形态适合耗时任务比如批量转换几十个文件、生成一份长报告。我在配置里给这种任务设置了独立队列和超时回调。第三种是事件订阅子 agent 发布“任务完成”事件主控 agent 订阅事件后主动拉取结果。这种适合子 agent 主动产生阶段性结果比如搜索 agent 一边爬资料一边向主控汇报已找到多少条。事件模式灵活但 debug 时很难追踪链路如果不是必要我建议少用。5.2 主控代理的转交示例为了让你更快理解转交闭环我给出一个最常用的异步转交配置。主控 agent 收到“把 uploads 里的报表全部导出为 PDF”之后先不直接调用文件工具而是创建一个任务并推给 file-agent。# coordinator.yaml handoff: tasks: - id: task-generate-001 agent: file-agent payload: action: convert_all source: uploads/*.md target: output/*.pdf callback: event://internal/task-complete timeout: 180sfile-agent 完成后会触发event://internal/task-complete事件主控 agent 订阅该事件后拉取生成结果再组织语言回复用户。这样做的好处是主控 agent 不需要了解 PDF 转换的具体实现它只负责“任务状态管理”。而 file-agent 也不需要知道用户说什么只负责完成一个明确的文件操作。两个 agent 的职责完全解耦任何一个升级都不影响另一个。5.3 调度缓存与失败重试异步流程一定会遇到失败。我通常给每个转交任务配置两层重试第一层是网络超时重试第二层是任务内容校验失败重试。以文件转换为例如果目标是 PDF 但源文件缺页任务会进入“需确认状态”由主控 agent 主动询问用户“源文件第 3 页是空白的是否跳过”这比让子 agent 自动瞎补一页要安全得多。另外我强烈建议把任务 ID 和用户原始请求关联起来。一旦任务失败你可以根据任务 ID 追溯出“谁在什么时候发起、请求内容是什么、处理到哪一步”。在你的生产系统里这个 ID 链就是排查问题的最关键线索。6. 记忆分区不要让档案共享变成信息泄漏多 agent 最容易被忽略的是记忆设计。很多人把 memory 一股脑交给系统默认存储结果各个 agent 的记忆互相串味。我所遵循的原则很简单全局共享的记忆越少越好agent 私有记忆要有明确的作用域。6.1 四层记忆模型我在 OpenClaw 里把记忆分成了四层每一层对应不同的读写权限和生命周期记忆层作用域生命周期典型内容热记忆单个 agent 会话2 小时当前任务的中间步骤、临时变量会话记忆单个用户 单个 agent7 天用户最近几次的交互偏好项目记忆所有 agent 共享30 天项目目录结构、命名规范、全局术语长期档案主控 agent 独享365 天用户身份偏好、历史重大决定热记忆必须是每个 agent 自己私有的。两个 agent 处理同一批文件时中间变量如果互相可见一个 agent 改了目录名另一个 agent 可能还拿着旧路径去读取最后报错都找不到原因。会话记忆按用户隔离并且只挂到真正跟用户对话过的 agent 上。用户让文件 agent 处理过发票下一次文件 agent 就会记得这个用户偏好把发票按日期命名但这种偏好不应该让代码 agent 知道否则代码 agent 会在命名变量时也去按日期命名那画面太美我不敢看。6.2 配置示例把记忆分区写进 agent 配置OpenClaw 的 memory 配置大概是这样的格式memory: store: sqlite path: ./memory/shared.db partitions: - name: hot scope: agent ttl: 2h sync: false - name: session scope: user_agent ttl: 7d sync: true - name: project scope: all_agents ttl: 30d sync: true - name: chronicle scope: coordinator_only ttl: 365d sync: true我把project这一层设计成所有 agent 都能读写的“共享白板”但写入前要走一次规范化校验。比如一个 agent 尝试写入一个不在项目术语表里的新名词主控 agent 会要求它先提出术语申请而不是直接写进共享记忆。这会稍微拖慢一点效率但对多 agent 长跑来说完全值得。共享记忆最容易烂在“谁都能写”最终变成一个四不像的大杂烩。我建议在共享记忆的写入端做一个简单的过滤器不让子 agent 把属于自己私有视角的内容塞进公共区域。如果做不到宁可把共享层只读由主控 agent 统一维护。安全永远是多 agent 系统第一优先级。6.3 记忆清理过期数据就是另一种形式的安全风险记忆不是存得越多越好。我遇到过一种情况项目冲刺阶段一堆临时任务细节被写入长期档案三个月后项目早结束了这些细节还在。某次用户只是随口问了一句“我们当时有没有讨论过某某方案”这些过期记忆就冒出来直接污染了主控的上下文。所以我每个月会跑一次记忆清洗规则很简单超过生命周期、且最近三个月从未被命中的记忆标记为待清理清理前生成一份摘要快照存到归档目录。之后如果用户重新提起相关话题我还能从归档快照中手动恢复而不是彻底丢光。7. 踩坑排查我遇到过的五个典型多 agent 事故现场配置和原理都讲完了现在来点接地气的。以下五个坑是我自己在一个模拟项目上真实踩过的每一个都花了不少时间才定位到根因。写出来算是给你省几条弯路。7.1 事故一所有 agent 同时订阅了用户消息导致抢答现象用户问“帮我看看这个文件”文件 agent 和代码 agent 同时回复一个回“好的我来读取文件”另一个回“请告诉我文件路径我来检查格式”。根因配置里给所有 agent 都加了listen: user://*这等于让每个 agent 都变成了对话入口。OpenClaw 里应该只有主控 agent 监听用户通道子 agent 只监听内部任务事件。修复把子 agent 的 listen 改成internal://task/*只接收任务消息。用户侧始终只能看到主控 agent 在回复。7.2 事故二两个 agent 之间产生了循环转交现象用户让代码 agent 修复一个 bug代码 agent 觉得问题出在文档缺失于是转给文件 agent文件 agent 又说这不是文件问题又转回代码 agent。两个 agent 互相踢皮球直到超时。根因我在路由规则里给了两个 agent 相同的handoff_keys例如都配置了“修复”“错误”导致互相匹配。修复给每个子 agent 设置严格的转交白名单。文件 agent 只允许转回主控代码 agent 只允许转回主控子 agent 之间默认不允许互相转交。N 个 agent 之间的网状调用看着灵活实际是灾难之源。多 agent 协作应该星型子 agent 之间永远只通过主控中转。7.3 事故三共享记忆把两个任务的关键信息混在一起现象文件 agent 正在做批量归档时搜索 agent 同时启动了一个资料收集任务。两个任务写共享记忆时用了同一个 keylatest_file_list结果归档任务读到了搜索任务的数据把网页链接当成文件路径去读取报了一堆错。根因共享记忆的 key 没有加入任务 ID 命名空间。修复所有共享记忆 key 必须带上任务 ID 或 agent 名前缀比如file-agent/task-001/latest_file_list。我后来直接在配置里加了命名空间模板再也没出过这种事。7.4 事故四超时时间设置过短长任务被反复重试现象一个 PDF 批量转换任务原本需要 120 秒我却把 request_timeout 设成 30 秒。30 秒一到主控认为失败立刻重试结果同一批文件被转换了两遍输出目录里出现了同名副本。根因我错误地把“网络请求超时”和“子 agent 任务执行超时”混为一谈。网络请求可以很快超时但任务执行要看实际复杂度。修复把 request_timeout 和 task_timeout 分开设置。网络层保持短超时比如 30 秒子 agent 的任务执行超时单独计算批量任务甚至允许 180 秒以上。同时给输出文件生成加上“覆盖策略”任务 ID 相同时才允许覆盖否则自动生成新文件名避免重复执行造成的数据混乱。7.5 事故五日志里看不到子 agent 的内部调用链现象用户在文件 agent 的转换结果里看到一行奇怪的错误码但日志里只有主控 agent 的会话记录完全找不到这行错误码从哪来。根因子 agent 的调试日志级别是 info而错误码是 debug 级别打出来的默认不输出到主日志。修复把每个子 agent 的日志单独落盘并统一注入task_id和相关字段。所有 agent 的输出都带同一个 trace id主控和日志系统就可以按 trace id 串联出完整的调用链。现在每次排障我都直接按 trace id 过滤日志几分钟就能定位到具体环节。8. 上生产前并发、配额、日志和发布建议多 agent 在本地跑通和在生产环境稳定运行中间隔着一大段“灰度测试”的距离。最后这部分是我觉得最容易被忽略但最值得聊的。8.1 并发控制别让一个用户占光所有算力如果没有并发限制某个用户一次性发起 30 个任务子 agent 可能瞬间被挤垮。我在主控配置里加了资源配额管理quota: per_user: max_concurrent_tasks: 5 max_requests_per_minute: 20 per_agent: max_concurrent_tasks: 3 queue_overflow: reject当用户并发超过阈值时我会让主控返回“当前任务较多请稍后再试”而不是让任务在后台无限排队。对于内部自动化任务我单独走一条不受用户配额影响的任务队列两者在配置里用不同的 token 区分。8.2 版本化的配置发布别让未经验证的 agent 直接上生产每一个 agent 切模型、改工具、调温度都应该走一次发布流程。我会在本地先跑三组 mock 任务确认行为正常后才合入主配置并且每次发布都打一个配置版本号。出现行为退化时我不去翻 git 历史找原因直接先把配置回滚到上一个稳定版本再慢慢定位问题。这比在线上一行行排查要快得多。另外新 agent 上线初期我建议先把它路由优先级调低同时打开“人工确认开关”。主控会把本该转给新 agent 的任务先转成一个预分配状态由我确认后才真正进入子 agent 执行。等观察一两天没问题再放开全自动路由。8.3 日志与审计协作型 agent 必须具备“可回放性”生产环境里多 agent 系统的日志不能只有自然语言记录还要有关键事件的结构化日志。每条日志至少包含 event_type、agent_name、task_id、duration_ms、model_name、input_tokens、output_tokens 这些字段。这样你不仅能看到“发生了什么”还能算出“每个 agent 花了多少钱、用了几秒”。我在生产环境里接了一个简单的日志轮转方案主控日志和子 agent 日志分开存每个文件按天滚动保留 30 天。对可能涉及敏感数据的请求单独打一份审计日志只记录元数据、不记录完整内容。一旦有安全质疑这份审计日志就是你的保护伞。8.4 成本保护给每个 agent 设独立的预算上限多 agent 部署后成本不是线性增长而是会“爆炸性增长”。原因是每个子 agent 都在独立消耗模型 token。搜索 agent 每天可能在找资料时消耗几千个 token文件 agent 在描述输出结果时也会消耗 token而这些你如果不看日志是完全没有体感的。我给每个 agent 设置了月度 token 预算agent月度预算超限行为coordinator100 万 token转入慢速队列file-agent200 万 token限制并发为 1code-agent300 万 token发送人工告警search-agent150 万 token退回主控手动确认超限后的动作我很少直接“拒绝服务”而是降级转慢速队列或者要求人工确认。这样既保护了预算也不至于把用户请求全部挡在门外。等月底复盘时再根据真实用量调整各 agent 的预算配比。多 agent 的路子打开之后你会发现它不只是“几个 agent 拼在一起”而是一套包含路由、记忆、权限、观测和预算的系统工程。我现在的做法依然是先让主控保持精简子 agent 按需慢慢增加。你每加一个 agent都要重新审视路由规则会不会冲突、共享记忆会不会污染、预算会不会失控。从两个 agent 开始磨合比一上来就铺开五六个分身要稳得多。这套配置逻辑我还在持续调整后面如果有新的坑和更顺手的实践我再回来更新这篇。