1. 开工前的思路：为什么需要一份多 Agent 配置指南
先说一个我自己的认知转变。前两年做单 Agent 应用，说白了就是“一个大模型 + 一堆工具函数 + 提示词”，逻辑顺下来基本就完事了。那时候最头疼的是模型输出格式不稳定，调 prompt 调到头秃。但从去年开始，接手了几个真正需要多智能体协作的项目，才发现单 Agent 那套玩法根本撑不住——业务一复杂，职责混在一起，上下文互相污染，一个 Agent 干着干着就把另一个 Agent 的活儿也干了，排查起来全是幽灵问题。
多 Agent 架构的初衷并不是“用多个模型显得更高级”，而是把复杂的任务拆成边界清晰的子任务，每个 Agent 专注一件事，再通过消息机制把结果串起来。这个思路和团队协作很像：写代码的人、审代码的人、测试的人、写文档的人，各有分工，通过会议纪要和 MR 评论来协作。如果所有人都跨界干活，项目就会失控。OpenClaw 框架的核心价值，就是把这种分工机制用代码固化下来。
但这套机制的配置门槛确实不低。我自己第一次搭多 Agent 环境的时候，光看官方示例就绕了不少弯路。框架版本迭代快，文档里的参数名经常变，网上搜到的教程有不少还是旧版的写法，照着配直接报错。所以这篇指南只解决一个问题：如何从零开始，配置一套结构清晰、可维护、能真正跑起来的多 Agent 系统。我不讲空泛的概念，全部基于实际配置文件的写法、参数含义和踩坑记录。
这份指南适合三种人：第一种是已经在用 OpenClaw 跑单 Agent、想升级到多 Agent 架构的开发者；第二种是被多 Agent 概念吸引、但面对配置文档一头雾水的新手；第三种是团队里负责搭建 AI 基础设施、需要给同事输出规范配置模板的工程负责人。
2. 配置前必须想清楚的三件事
2.1 先画蓝图，再写配置
很多人一上来就照抄示例配置，把几个 Agent 的名字和 prompt 改一改就完事。这是最要命的做法。OpenClaw 的多 Agent 配置本质上是描述一个“组织架构”，你在配置文件里怎么写，系统就怎么运转。如果连分工都没想明白，配置出来的系统必然是一团乱麻。
我建议动手写配置之前，先回答三个问题：
第一个问题，整个业务流程需要拆成哪几类职责？拿一个内容创作场景举例，至少要分“选题策划”“素材收集”“初稿撰写”“事实核查”“排版润色”这几步。如果业务更复杂，比如跨境电商运营，可能要拆出“市场分析”“选品调研”“Listing 撰写”“客服回复”“竞品监控”五个以上角色。
第二个问题，这些职责之间是严格的先后顺序，还是部分可以并行？比如“素材收集”可以在“选题”确定后立即并行启动，但“事实核查”必须等“初稿”完成才能开始。OpenClaw 支持串行和并行两种编排方式，配置前需要先给每个 Agent 标好依赖关系。
第三个问题，哪些 Agent 之间需要共享上下文？某些信息（比如品牌调性、目标用户画像）是多个 Agent 都要用到的全局变量；而某个 Agent 的中间输出（比如初稿）又是下一个 Agent 的唯一输入。搞清楚这一点，后面配置 memory 和 message 路由时才不会乱。
这三个问题想清楚之后，建议在纸上画一张简单的流程图，用箭头标出每个 Agent 的输入来源和输出去向。这个流程图不一定要精确到代码级别，但一定要能回答“谁产出什么、谁消费什么”。我见过太多开发者在这个环节偷懒，结果配置到一半发现两个 Agent 之间缺一个转换步骤，或者某条消息没人消费，不得不推倒重来。
2.2 认识 OpenClaw 的核心抽象：Agent、Skill、Trigger、Memory
在 OpenClaw 的配置文件里，有几个核心概念必须先建立认知。我尽量用大白话解释，后面所有配置实操都建立在这套概念上。
Agent（智能体）是最核心的单位，你可以把它理解成一个“有角色设定的工作人员”。每个 Agent 有独立的身份描述、能力边界、工具清单和记忆空间。配置 Agent 时，最关键的不是写一段很长的 prompt，而是把“职责边界”描述清楚。我自己常用的写法是“你是负责 X 的角色。你需要做 A、B、C。你不需要做 D、E。当遇到 F 情况时，你必须把任务转交给 Y 角色。”边界清晰比能力强大更重要。
Skill（技能）是 Agent 可以调用的具体能力，相当于给工作人员配的工具。比如“网页搜索”“调用数据库”“读取 Excel”“生成图片”。OpenClaw 里 Skill 可以是内置的默认技能，也可以是通过插件扩展的自定义技能。配置 Skill 时要注意：不是每个 Agent 都需要所有技能，给“排版润色”角色一个网页搜索工具反而是多余且危险的。
Trigger（触发器）是系统的“事件开关”。配置了 Trigger 之后，Agent 不会默默待命，而是会在特定条件下被唤醒。比如“当收到新任务时启动”“当定时任务触发时启动”“当某个外部 webhook 调用时启动”。在多 Agent 系统里，Trigger 是编排流程的起点，也是最容易被忽视但是最影响系统响应效率的部分。
Memory（记忆）是 Agent 的“信息存取空间”。不同 Agent 可以共享某些记忆空间，也可以拥有私有记忆。配置 Memory 时需要明确每个 Agent 能看到哪些历史信息、不能看到哪些。信息隔离做得不好的话，很容易出现“一个 Agent 把另一个 Agent 的中间状态当成了最终结果”之类的低级错误。
这四个概念的关系可以这么类比：Agent 是员工，Skill 是员工桌上的工具清单，Trigger 是公司里的通知铃声，Memory 是员工的笔记本和共享文档库。一套好的 OpenClaw 配置，就是把这四类元素完整、合理地定义出来。
2.3 设计原则：一个 Agent 至少回答四个问题
我在看了大量质量参差不齐的多 Agent 配置之后总结出一个小原则：配置任何一个 Agent 之前，都要确保以下四个问题在配置文件中有明确答案，缺一个，这个 Agent 后面运行大概率会出问题。
第一个问题：这个 Agent 的角色是什么，能做什么、绝对不应该做什么？这对应到配置里的身份描述和工具范围。
第二个问题：这个 Agent 什么时候应当启动？是轮询、触发还是消息驱动？如果触发条件没有明确，会出现“该干活的不干活”或者“不该干的先抢着干了”的情况。
第三个问题：这个 Agent 的输出格式是什么？JSON、自然语言、Markdown、代码片段？下游 Agent 能否直接消费这个输出？多 Agent 系统里最常见的连锁故障就是上游输出格式混乱、下游解析器直接崩溃。
第四个问题：这个 Agent 如果干不了或者遇到异常，该向谁求助或者如何终止？很多配置里根本没人管异常分支，结果上游 Agent 一旦出问题，整个流程就挂死。
之后的配置实操会反复用到这四个问题作为校验标准。
3. 从零开始配置多 Agent：环境准备与工程结构
3.1 安装与版本选择的坑
OpenClaw 的安装方式不算复杂，常规的操作是先把仓库克隆到本地，然后安装依赖。但有一个细节至关重要——版本锁定。我见过不少人在配置过程中遇到诡异报错，排查半天发现是版本不对：最新版已经改了某个配置项的写法，但网上教程还在用旧版格式。
我的建议非常明确：首次搭建环境时，用稳定发布的 release 版本，而不是直接拉取 main 分支的最新代码。README 里通常会标注推荐版本号，按那个来。另外依赖安装时建议使用虚拟环境创建独立运行空间，避免和系统全局的其他 Python 包冲突。多 Agent 项目本身依赖就多，用全局环境的话，版本冲突问题会让你怀疑人生。
安装完成之后，强烈建议先跑一下官方提供的最小配置文件，确认基础服务能正常启动，再去折腾多 Agent 的复杂结构。省得后面配置出问题时分不清是环境问题还是配置文件问题。
3.2 推荐的目录结构与配置分离思路
一个可维护的多 Agent 项目，目录结构应当遵循“配置与逻辑分离”的思路。我目前比较推荐下面这种组织方式：
your-project/ ├── config/ │ ├── agents/ │ │ ├── coordinator.yaml │ │ ├── researcher.yaml │ │ ├── writer.yaml │ │ └── reviewer.yaml │ ├── skills/ │ │ ├── web_search.yaml │ │ └── document_loader.yaml │ ├── triggers/ │ │ ├── on_task_created.yaml │ │ └── daily_report.yaml │ └── memory/ │ ├── shared_context.yaml │ └── private_notes/ ├── custom_skills/ │ └── my_company_skill/ ├── logs/ └── .env这种结构的核心价值在于：每个 Agent 一个独立文件，改配置时的改动范围被限制在一个文件里；不同类别的配置互相隔离，定位问题的时候能很快缩小范围。
我自己一开始图省事，把所有 Agent 的配置堆在一个大文件里，结果项目跑到后期，每次改动都要小心翼翼，稍不注意改错一处就会连带影响其他 Agent。后来我花了半天时间把配置拆分到独立文件并按约定组织，改动体验立刻好了很多——改一个角色的定义，完全不担心碰到另一个角色的配置。
3.3 环境变量与密钥管理
多 Agent 系统通常要接入各种外部服务，比如大模型 API、搜索服务、数据库。这些服务的密钥绝对不应该出现在配置文件里。正确的做法是把密钥放在环境变量文件中（比如项目根的 .env 文件），然后在配置文件里通过 ${VAR_NAME} 的占位符形式来引用。
# .env 文件内容（示例） MODEL_API_KEY=sk-xxxxxxxxxxxxxxxx DATABASE_URL=postgresql://user:pass@localhost:5432/yourdb SEARCH_API_KEY=xxx配置文件里的引用方式：
model_provider: api_key: ${MODEL_API_KEY}这里有一个隐蔽的坑：有些版本的 OpenClaw 加载环境变量时只读取特定路径下的 .env 文件。如果你把 .env 放在子目录里，运行时可能会提示找不到变量。我在第一次配置时就踩了这个坑，日志显示“变量未定义”，后来发现是文件路径问题。解决方法是把 .env 保持在项目根目录，并且确认启动命令的工作目录正确。
密钥管理还有一个容易被忽视的点：如果项目要用 Git 做版本管理，确认 .env 加入了忽略列表，不要提交到仓库。密钥泄露的教训不用多讲了，每次看到有人在示例代码里贴真实 key 我都替他捏把汗。
4. Agent 配置文件的逐字段拆解
4.1 一个最小可用的 Agent 长什么样
虽然 OpenClaw 的配置项很多，但一个 Agent 要能跑起来，并不是所有字段都需要手动定义。先看一个除了“能运行”之外不带任何花哨功能的最小配置，理解这个基础结构之后再往里加东西：
# config/agents/writer.yaml name: writer description: 负责将资料整理成结构化文章初稿的撰写角色。 model: provider: ${MODEL_PROVIDER} name: ${MODEL_NAME} temperature: 0.7 skills: - document_loader - text_formatter instructions: | 你是文章撰写角色。 你的输入是素材收集角色的输出。 你的输出是完整的文章初稿。 你需要将素材整合成逻辑通顺的初稿，并标注待核查事实。你也许注意到了，这个最小配置里没有写 trigger，也没有写 memory。原因很简单：在多 Agent 体系里，一个 Agent 不一定需要自己拥有触发器和独立记忆，它可以完全作为流程中的一环被其他 Agent 调用，或者由协调者统一分配任务。
初学者在配置中最容易犯的错误，就是给每个 Agent 都塞满所有字段，结果根本分不清哪些是生效的，哪些是无效的。最小配置教给你一个思维：先跑通，再丰富。
4.2 instructions 字段的写法：任务、边界与协作规范
不少教程把 instructions 直接等同于“提示词”，然后用写 prompt 的方式写一大堆背景知识和性格设定。这个认知需要修正。在多 Agent 场景下，instructions 的本质是“操作手册”，不是“角色小传”。
高可维护性的 instructions 应当包含以下三类内容。
第一类是任务定义。明确这个 Agent 接收什么输入、执行什么处理、产出什么输出。建议用明确的动词开头，比如“接收”“解析”“生成”“校验”，避免模棱两可的表述。写“整理资料并输出初稿”就不如写“读取素材文件夹中的所有 Markdown 文件，提取核心观点，按指定的文章大纲框架生成初稿”来得清晰。
第二类是边界声明。明确这个 Agent 不做哪些事。比如写作 Agent 应当声明“不负责事实核查，不负责最终排版，遇到不确定的数据时，在文中用【待核查】标记，不自行推断”。
第三类是合作规范。明确这个 Agent 遇到什么情况该向谁求助。比如“如果输入文件格式无法解析，将错误信息发送给故障处理 Agent，不要尝试自行修复”。这一条看着简单，但真正写在配置里的人少之又少。
来一段我实际用过的 instructions 示例：
instructions: | 你是资源收集角色。你的任务是根据选题文案中的需求，收集相关的公开资料，并以结构化列表输出。 输入格式：协调者发送的包含选题内容的 JSON 对象。 输出格式：包含 资源标题、来源URL、摘要、置信度 四个字段的 JSON 数组。 你不负责撰写正文。你不负责判断资料的真伪，只需要标注来源。 如果某个关键词在搜索后没有返回任何结果，不要编造 URL，直接返回空数组并提供说明字段。 与本任务无关的消息请忽略。这套写法跑起来之后，下游 Agent 的解析成功率明显提升，原因很简单：上游输出格式固定了，下游处理指定字段就行了，不用猜。
4.3 多模型与多 Provider 的配置策略
一个经常被拿到台面上讨论的配置问题是：多个 Agent 是否可以使用不同的模型？答案是肯定的，而且在很多场景下是必要的。不同 Agent 的任务复杂度不同，用同一个模型会造成资源浪费或能力不足。
我的建议是分层配置模型。复杂度低、吞吐量大的任务（比如格式转换、文本提取），可以用轻量模型来跑，速度快且成本低。复杂度高、需要推理能力的任务（比如规划拆解、复杂语义判断），给更强的模型。形式化的配置大概长这样：
# config/agents/coordinator.yaml name: coordinator model: provider: provider-a name: powerful-model-x temperature: 0.2 # config/agents/formatter.yaml name: formatter model: provider: provider-b name: lightweight-model-y temperature: 0.1有一个值得留意的点是 temperature 这个参数。并不是所有任务都适合把 temperature 调高。规划和分类这类任务需要稳定性和可复现性，temperature 低一点更合适。生成创意文案的任务可以适当调高，让输出更多样化。我在配置时，规划类 Agent 的 temperature 通常不超过 0.3，创作类 Agent 可以到 0.8。
4.4 Skill 注册与权限控制
OpenClaw 里的技能有两种来源：内置技能和你自己写的自定义技能。配置的核心不在怎么注册，而在于“每个 Agent 该挂载哪些技能”。
我给一个很直白的建议：配置技能时遵循最小权限原则。给 Agent 分配技能时，先问自己“完成这个 Agent 的任务，真的需要这个技能吗？”不需要的技能就不要挂载。为什么？因为技能不只是能力，也是攻击面和干扰源。一个不需要联网的 Agent 如果挂载了网络搜索技能，当它的上下文里出现“查一下”这类词时，模型可能就会擅自触发搜索，反而拖慢处理速度。
多 Agent 系统配置的规范，其实和“公司给员工配发账号权限”的逻辑高度一致——按需分配，最小可见，互相不越权。
技能注册示例：
skills: - name: document_loader config: allowed_extensions: [md, txt, docx] max_file_size: 10MB - name: web_search config: max_results: 5 timeout_seconds: 15这里也有一个值得注意的细节：技能本身可以带配置参数。同一个技能在不同 Agent 里的参数配置可以不同。比如搜索技能在素材收集 Agent 里的单次结果限制可以放宽到 10 条，在事实核查 Agent 里可以设成 3 条，以提升精准度。
5. 多 Agent 的通信与编排配置
5.1 Agent 间的消息路由：直接与间接
多 Agent 系统最能体现设计功力的环节是通信。OpenClaw 里的通信不是“Agent 之间直接喊话”，而是通过“消息总线”进行路由。换句话说，Agent 不关心消息是谁发的、发给谁，它只关心自己订阅了什么类型的消息、自己发布了什么类型的消息。
用行话讲，这是“事件驱动的发布订阅模式”。配置 Agent 时，你需要明确两个字段：它能接收的事件类型（subscribe）和它能发布的事件类型（publish）。举个例子：
name: coordinator triggers: - type: event event_name: new_task_created action: publish_new_task subscriptions: - event_name: task_completed action: track_progress这种设计的优点在于解耦。增加一个新的 Agent 时，不需要修改其他 Agent 的配置，只要新 Agent 订阅相应的事件类型即可。这就像办公室里新来了一个同事，在通讯录和邮件列表里加入它的邮箱就好，不需要通知所有人改联系方式。
对应的反例是：如果配置成直接调用的方式，A Agent 直接调用 B Agent 的接口，那一旦 B 的接口签名变了或者超时了，A 就跟着挂。在配置层面，我强烈推荐优先使用事件驱动的通信方式。
5.2 串行流程与并行流程的配置区别
流程编排有两种基本形态，串行和并行。先看串行的例子——一个典型的“收集资料 → 撰写初稿 → 核查事实”流程：
pipeline: - stage: research agent: collector output_event: research_completed - stage: writing agent: writer input_event: research_completed output_event: draft_ready - stage: review agent: reviewer input_event: draft_ready output_event: review_completed这里的关键设计在于：每个 stage 的 input_event 是上一个 stage 的 output_event。下游 Agent 不会因为上游还没完成而提前启动，因为触发条件一直没有满足。这种模式天然避免了“消息来了但上游还没处理完”的竞态问题。
并行的配置同样不复杂。假设“收集资料”阶段需要同时做“公开资料搜索”和“内部文档检索”，之后再把结果合并：
parallel_group: - agent: web_collector output_event: public_research_done - agent: internal_collector output_event: internal_research_done merge: agent: merge_agent input_events: [public_research_done, internal_research_done] output_event: merged_research_done并行配置的核心问题在于“合并等待”：汇总 Agent 必须等两个并行事件都完成后才能启动。在 OpenClaw 配置里，通常在合并 Agent 的 trigger 上加一个条件，等待多个事件同时满足。如果你发现合并 Agent 经常在只收到一个事件时就抢跑，大概率是条件没有配置完整，这是最需要仔细检查的点之一。
5.3 Memory 共享与隔离的配置技巧
多 Agent 系统里 Memory 配置是最容易出安全问题、也最容易出逻辑问题的地方。先明确一个基本规则：共享的 Memory 只放全局信息，私有 Memory 放过程信息。
全局共享类信息包括：品牌调性描述、目标用户画像、项目基础数据、通用术语表。这些是所有 Agent 都需要知道的，放在共享 Memory 里是正确的，否则每个 Agent 的上下文里都缺基本信息，协作就会走样。
过程信息则必须隔离。比如“writer 正在起草的文章版本”就是 writer 的私有信息，其他 Agent 没有权限访问。如果所有过程信息全部共享，Agent 之间会互相干扰，各自读到一堆与自己无关的中间状态，导致判断混乱。
共享 Memory 配置示例：
memory: shared: - name: brand_basics type: document path: memory/shared/brand_basics.md private: - name: draft_scratchpad scope: writer type: sqlite从信息安全的角度，私有 Memory 的隔离防止了任务边界被突破。假如一个收集公开资料的 Agent 被恶意提示词攻击，如果它能访问内部文档的 Memory，潜在风险会明显放大。所以私有 Memory 的配置不仅是逻辑需要，也是安全配置的一部分。
5.4 协调者的配置：调度还是演员
多 Agent 系统是否需要一个“总指挥”Agent，业界没有统一答案。我个人的经验是：系统里 Agent 数量超过 3 个，就值得配置一个协调者角色。
协调者的作用不是把活都自己干了，而是做“任务路由”——识别新进来的任务属于什么类型，分派给对应的执行者；监控执行结果，判断是否需要二次分派或终止流程。配置协调者的核心仍然在于边界：协调者不做具体的专业活，只做调度决定。
name: coordinator model: provider: provider-a name: powerful-model-x temperature: 0.2 instructions: | 你是任务协调者。 你的职责是接收新任务消息，判断任务类型，分派给对应的执行角色。 你不直接撰写内容，也不直接执行资料收集。 当某个执行角色多次报告失败时，记录状态并通知管理员，不尝试自行修复。协调者的存在让整个系统有了一个可以追加全局逻辑的锚点：超时重试、异常兜底、流程终止条件，都可以围绕协调者的 Trigger 和 Skill 展开。
5.5 超时、重试与最大迭代次数配置
多 Agent 流程一旦跑起来，最让人提心吊胆的就是“卡死”。Agent 之间互相等待、消息丢失、循环调用，这些都是真实存在的运行风险。我在配置中会强制要求为每个流程设置三类保护参数。
第一类：超时参数。无论执行者是外部 API 调用还是内部处理，都必须设置明确的超时时间。我通常把每个 Agent 的单次执行超时限制在 120 秒左右，超过之后直接判定该节点失败并触发兜底逻辑。
第二类：重试参数。网络请求类的技能（比如搜索、外部 API 调用）值得重试，但重试次数要有限制。重试间隔用递增策略，比如第一次失败后等 2 秒，第二次等 5 秒，第三次等 10 秒。不能无限重试，设置最大重试 3 次是性价比最高的选择。
第三类：最大迭代次数。某些 Agent 可能因为提示词设计不当出现“循环生产”的情况。防止这一点，可以在流程配置里设定全局最大迭代步数，达到上限后强制终止当前流程并生成诊断信息。
下面是一个综合的编排配置片段：
execution_control: global_max_steps: 20 default_timeout_seconds: 120 retry_policy: max_retries: 3 base_delay_seconds: 2 multi_delay: true这些参数看似不起眼，但关键时刻能救命。我后来接手维护过的几个项目里，超过一半的“卡死”问题都是因为没配最大迭代次数，Agent 陷入了死循环而没有任何保护机制。
6. 实战配置完整示例：三角色内容生产系统
6.1 系统结构与任务流设计
为了把前面的概念串起来，我准备了一个完整可落地的示例：一个内容生产系统，包含三个 Agent。这个系统解决的实际问题是：给定一个内容选题，自动完成资料收集、初稿撰写、事实核查三个阶段的工作，最终输出一篇带引用来源的文本稿件。
三个角色及职责如下：
- 协调者（coordinator）：接收外部任务，判断任务类型，用事件驱动的方式把任务分派给收集者。
- 收集者（collector）：根据选题关键词收集公开资料，输出结构化的资料清单。
- 撰写者（writer）：基于资料清单撰写初稿，全文引用来源。
- 核查者（reviewer）：逐条核查初稿中的事实和引用，输出核查报告与可信度评分。
这套系统的核心流程是串行加并行的混合结构：协调者分派任务，收集者在收到任务后并行跑两个搜索技能，完成后再通知撰写者开始工作，撰写者完成初稿后核查者介入。
6.2 Agent 配置清单与逐项解释
下面我给出四个角色的完整配置摘录，重点部分会加注释说明思路。
首先是协调者。它的关键触发条件是新任务事件：
name: coordinator model: provider: provider-a name: powerful-model-x temperature: 0.2 triggers: - type: event event_name: task.received action: route_task skills: - task_router instructions: | 你是任务协调者。你接收 task.received 事件，根据任务描述判断类型。 如果任务属于内容生产，发布 task.assigned 事件，并附上统一的 job_id。 你不执行资料收集、不撰写、不核查。然后是收集者：
name: collector model: provider: provider-b name: lightweight-model-y temperature: 0.3 triggers: - type: event event_name: task.assigned condition: "任务类型为内容生产" skills: - web_search - document_loader subscriptions: - event_name: task.assigned action: collect_material publishes: - event_name: material.ready memory: private: - name: collected_list scope: collector instructions: | 你是资料收集角色。根据协作者提供的选题关键词，执行搜索并整理资料清单。 输出格式为 JSON 数组，字段包括 title、url、summary、confidence。 搜索无结果时不得编造 URL。 完成清单后发布 material.ready 事件。接着是撰写者：
name: writer model: provider: provider-a name: powerful-model-x temperature: 0.7 triggers: - type: event event_name: material.ready skills: - text_formatter memory: private: - name: draft_scratchpad scope: writer instructions: | 你是撰写角色。读取收集者发布的资料清单，整理成完整初稿。 所有事实表述必须附上对应的来源标记 [n]。 如果资料不足，在稿件中明确标注信息缺口，不得虚构内容。 完成后发布 draft.ready 事件。最后是核查者：
name: reviewer model: provider: provider-a name: powerful-model-x temperature: 0.1 triggers: - type: event event_name: draft.ready skills: - source_validator subscriptions: - event_name: draft.ready action: verify_facts publishes: - event_name: review.done instructions: | 你是事实核查角色。逐条检查初稿中的事实陈述与来源编号。 输出核查报告，包含每条陈述的可信度评级和修改建议。 你只做核查，不直接修改稿件。6.3 启动完整系统的步骤清单
配置写完之后，启动整个系统我通常按下面这五步走，每一步都有明确的检查点。
第一步，检查配置文件的语法。OpenClaw 的配置文件是 YAML 格式，YAML 对缩进极度敏感。我建议先在编辑器里安装 YAML 校验插件，或者用命令行的解析工具做一次语法校验，确保没有格式错误。缩进错误是配置文件无法启动的头号原因。
第二步，检查环境变量。确认 .env 文件里引用的每个变量在实际运行环境中都存在。一个简单的方法是启动时留意日志里是否有“未定义变量”的告警。
第三步，启动基础服务并观察日志。先不急着向系统发任务，先启动框架，观察各 Agent 是否正常注册、触发器是否成功加载。这一步相当于“开机自检”。
第四步，用一条最简单的任务做端到端测试。发送一条“请撰写一篇关于人工智能在制造业应用的浅析文章”这样的测试任务，走一遍完整流程，查看各日志节点的状态流转是否符合预期。
第五步，观察并记录正常的基线耗时。每个流程跑完之后，记录一下总耗时和各阶段耗时，后面做性能优化或者排查问题时，这份基线数据是最有价值的参照。
我个人的习惯是，每次改完配置都会从第三步重新跑一遍，强制形成“改动必须验证”的闭环。没有这个习惯的话，改了配置不敢保证还能跑通，遇到问题也分不清是这次改动引入的还是本来就有。
7. 常见问题定位与排查手段
7.1 Agent 不响应或不触发
Agent 配置好了、流程也启动了，但某个 Agent 就是不干活。这种问题，我用一句话总结排查思路：先问触发条件，再问订阅路由，最后检查日志。
触发条件的排查重点是看该 Agent 的 trigger 是否真的被定义。如果它的工作方式是被事件驱动的，检查发布方是否真的发布了对应事件。最笨但最有效的方法是在日志里搜索事件名，如果发布端日志里没有该事件产生，那问题在发布端；如果有而产生端没有响应，那问题出在订阅关系上。
订阅关系的排查重点在于配置中的事件名是否完全一致。OpenClaw 对事件名的匹配通常是精确匹配，大小写、中划线、下划线的差异都会导致匹配失败。我的经验是，所有事件名统一用[小写字母加下划线]风格，避免混用不同命名风格，从根上规避这类问题。
7.2 上下游消息格式不匹配导致解析崩溃
这是我做多 Agent 项目以来遇到最多的问题，也是最隐蔽的一类故障。
通常的症状是：上游 Agent 执行正常，日志里显示输出也正常，但下游 Agent 读取消息后解析报错或者输出明显不合理的内容。问题根因往往在于——上游输出的是自然语言描述，下游却按严格的 JSON 格式去解析；或者上游输出的是 Markdown 表格，下游按纯文本分割逻辑解析。
我从这个坑里总结出一套行之有效的规范：在任何 Agent 的 instructions 里用最明确的措辞规定输出格式，并给出一个格式示例。不要只写“输出 JSON 数组”，而是直接附上如下示例：
输出格式如下： [ {"title": "示例标题", "url": "https://example.com", "summary": "摘要", "confidence": 0.9} ] 如果你无法完成任务，输出 {"error": "简短说明"}，不要输出其他内容。示例比解释有效一百倍。实践下来，附带了格式示例的配置，下游解析失败率能降低一大截。
如果问题已经发生了，排查技巧是：打开日志，找到消息传递过程中记录的数据负载实际内容，然后对比解析器的预期格式，人肉找出差异在哪里，再回到配置里把示例写清楚。
7.3 提示词冲突与上下文污染
多 Agent 系统的另一个高频问题可以概括为“上下文污染”——A Agent 的消息串进了 B Agent 的上下文。
这类问题的场景很典型：所有 Agent 共用同一个 Memory 空间，每个 Agent 运行时都把全部 Memory 内容塞进上下文。一旦 Agent 数量多了，每个 Agent 的上下文都会包含大量与自己无关的信息，模型则可能被这些无关信息误导。
排查方向非常明确：检查每个 Agent 的 Memory 配置，确认私有 Memory 是否真正隔离、公共 Memory 的内容是否精简到了最少。“最少”的标准是——如果某些内容不与当前 Agent 的任务直接相关，就不要出现在它的上下文里。
配置上，把大段的背景资料从一个 Agent 的公共上下文里移到协作数据库或者按需加载的外部文档里，通过 Skill 读取而非默认塞给上下文，可以有效切断污染路径。
7.4 死循环与任务重复执行
死循环的表现形式是：某个事件被同一个 Agent 或者不同的 Agent 反复处理，进入无限重入状态。典型例子是 A 发布了某个事件，B 处理完后也发布了同样的事件，于是系统又认为出现了新任务，重新走了一遍流程。
防范死循环要从配置规范上下功夫。我的做法是给所有任务事件加上唯一的 job_id 字段，并且在每个 Agent 的 instructions 里写明处理规则：“如果当前任务 job_id 已被处理过，直接丢弃该消息并结束流程。”
另外，全局最大迭代步数的配置一定要设置。它是最后的兜底，即使逻辑上出了问题导致死循环，步数上限也能强制断掉流程，避免整个服务被拖垮。
7.5 性能问题：事件太多、并发失控
多 Agent 系统不需要刻意追求高性能，因为业务场景大多属于低并发的任务型处理。但有一种情况会让人抓狂——并行分支太多，事件喷发，系统瞬间被消息淹没。
解决手段有两个层面。第一个层面是收敛并行度，在流程编排里控制并行分支的数量，不要超过 5 个并行分支同时处理。第二个层面是限流，OpenClaw 通常提供并发控制相关配置，把同一时刻最多处理的任务数限制住，让系统在可控压力下运行。
性能问题的排查工具，一般直接用日志里的事件吞吐数据来判断。先看每秒处理了多少个事件（EPC），再看单个 Agent 的平均处理延迟，两者配合就能定位到瓶颈节点。
8. 配置维护与迭代建议
最后分享几个日常维护层面的建议，都是我持续维护多 Agent 项目时觉得“早知道就好了”的点。
第一个建议：所有配置文件的修改，都要留变更记录。多 Agent 配置涉及的角色多，节点多，没有变更记录的话，一个月后哪怕是自己回来看，也说不清当初为什么把某个参数从 0.3 调到了 0.1。我自己的做法是，配置仓库里维护一个简单的变更日志（CHANGELOG），每次改动都写一行说明——哪个 Agent、哪些字段、为什么要改。这个习惯在排查问题时价值极高。
第二个建议：定期检查各 Agent 的输出日志质量。配置稳定之后，不能一直不管。我会每隔一段时间抽取一批日志样本，看输出格式是否仍然规范和一致、模型是不是偷偷偏离了指令。系统跑着跑着出现输出漂移是正常现象，关键是要及时发现并校准。
第三个建议：Agent 的数量要用“加法思维”谨慎增加。每增加一个 Agent，系统的编排复杂度都会非线性上升。动辄十几个 Agent 的项目，协调成本非常高。能用简单流程解决的任务，就不要为了炫技去堆 Agent。
第四个建议：保留一份“最小配置”作为救急方案。如果改着改着发现整个系统跑不起来了，就可以回退到最小配置先恢复服务，再从变更记录里找问题。没有这套兜底方案，线上出故障时只能干着急。
这套配置体系事到如今，我自己已经从“看到配置文件就头疼”的状态，变成了“先把架构图画清楚再动手写”的习惯。多 Agent 配置本身不复杂，复杂的是业务逻辑的梳理和角色边界的划分。你只要迈过设计这关，后面所有配置项都只是往骨架上填肉而已。希望这篇指南能帮你少走一点弯路，把精力花在真正有价值的事情上。
