1. 開(kāi)工前的思路為什么需要一份多 Agent 配置指南先說(shuō)一個(gè)我自己的認(rèn)知轉(zhuǎn)變。前兩年做單 Agent 應(yīng)用說(shuō)白了就是“一個(gè)大模型 一堆工具函數(shù) 提示詞”邏輯順下來(lái)基本就完事了。那時(shí)候最頭疼的是模型輸出格式不穩(wěn)定調(diào) prompt 調(diào)到頭禿。但從去年開(kāi)始接手了幾個(gè)真正需要多智能體協(xié)作的項(xiàng)目才發(fā)現(xiàn)單 Agent 那套玩法根本撐不住——業(yè)務(wù)一復(fù)雜職責(zé)混在一起上下文互相污染一個(gè) Agent 干著干著就把另一個(gè) Agent 的活兒也干了排查起來(lái)全是幽靈問(wèn)題。多 Agent 架構(gòu)的初衷并不是“用多個(gè)模型顯得更高級(jí)”而是把復(fù)雜的任務(wù)拆成邊界清晰的子任務(wù)每個(gè) Agent 專注一件事再通過(guò)消息機(jī)制把結(jié)果串起來(lái)。這個(gè)思路和團(tuán)隊(duì)協(xié)作很像寫(xiě)代碼的人、審代碼的人、測(cè)試的人、寫(xiě)文檔的人各有分工通過(guò)會(huì)議紀(jì)要和 MR 評(píng)論來(lái)協(xié)作。如果所有人都跨界干活項(xiàng)目就會(huì)失控。OpenClaw 框架的核心價(jià)值就是把這種分工機(jī)制用代碼固化下來(lái)。但這套機(jī)制的配置門(mén)檻確實(shí)不低。我自己第一次搭多 Agent 環(huán)境的時(shí)候光看官方示例就繞了不少?gòu)澛??？蚣馨姹镜煳臋n里的參數(shù)名經(jīng)常變網(wǎng)上搜到的教程有不少還是舊版的寫(xiě)法照著配直接報(bào)錯(cuò)。所以這篇指南只解決一個(gè)問(wèn)題如何從零開(kāi)始配置一套結(jié)構(gòu)清晰、可維護(hù)、能真正跑起來(lái)的多 Agent 系統(tǒng)。我不講空泛的概念全部基于實(shí)際配置文件的寫(xiě)法、參數(shù)含義和踩坑記錄。這份指南適合三種人第一種是已經(jīng)在用 OpenClaw 跑單 Agent、想升級(jí)到多 Agent 架構(gòu)的開(kāi)發(fā)者第二種是被多 Agent 概念吸引、但面對(duì)配置文檔一頭霧水的新手第三種是團(tuán)隊(duì)里負(fù)責(zé)搭建 AI 基礎(chǔ)設(shè)施、需要給同事輸出規(guī)范配置模板的工程負(fù)責(zé)人。2. 配置前必須想清楚的三件事2.1 先畫(huà)藍(lán)圖再寫(xiě)配置很多人一上來(lái)就照抄示例配置把幾個(gè) Agent 的名字和 prompt 改一改就完事。這是最要命的做法。OpenClaw 的多 Agent 配置本質(zhì)上是描述一個(gè)“組織架構(gòu)”你在配置文件里怎么寫(xiě)系統(tǒng)就怎么運(yùn)轉(zhuǎn)。如果連分工都沒(méi)想明白配置出來(lái)的系統(tǒng)必然是一團(tuán)亂麻。我建議動(dòng)手寫(xiě)配置之前先回答三個(gè)問(wèn)題第一個(gè)問(wèn)題整個(gè)業(yè)務(wù)流程需要拆成哪幾類職責(zé)拿一個(gè)內(nèi)容創(chuàng)作場(chǎng)景舉例至少要分“選題策劃”“素材收集”“初稿撰寫(xiě)”“事實(shí)核查”“排版潤(rùn)色”這幾步。如果業(yè)務(wù)更復(fù)雜比如跨境電商運(yùn)營(yíng)可能要拆出“市場(chǎng)分析”“選品調(diào)研”“Listing 撰寫(xiě)”“客服回復(fù)”“競(jìng)品監(jiān)控”五個(gè)以上角色。第二個(gè)問(wèn)題這些職責(zé)之間是嚴(yán)格的先后順序還是部分可以并行比如“素材收集”可以在“選題”確定后立即并行啟動(dòng)但“事實(shí)核查”必須等“初稿”完成才能開(kāi)始。OpenClaw 支持串行和并行兩種編排方式配置前需要先給每個(gè) Agent 標(biāo)好依賴關(guān)系。第三個(gè)問(wèn)題哪些 Agent 之間需要共享上下文某些信息比如品牌調(diào)性、目標(biāo)用戶畫(huà)像是多個(gè) Agent 都要用到的全局變量而某個(gè) Agent 的中間輸出比如初稿又是下一個(gè) Agent 的唯一輸入。搞清楚這一點(diǎn)后面配置 memory 和 message 路由時(shí)才不會(huì)亂。這三個(gè)問(wèn)題想清楚之后建議在紙上畫(huà)一張簡(jiǎn)單的流程圖用箭頭標(biāo)出每個(gè) Agent 的輸入來(lái)源和輸出去向。這個(gè)流程圖不一定要精確到代碼級(jí)別但一定要能回答“誰(shuí)產(chǎn)出什么、誰(shuí)消費(fèi)什么”。我見(jiàn)過(guò)太多開(kāi)發(fā)者在這個(gè)環(huán)節(jié)偷懶結(jié)果配置到一半發(fā)現(xiàn)兩個(gè) Agent 之間缺一個(gè)轉(zhuǎn)換步驟或者某條消息沒(méi)人消費(fèi)不得不推倒重來(lái)。2.2 認(rèn)識(shí) OpenClaw 的核心抽象Agent、Skill、Trigger、Memory在 OpenClaw 的配置文件里有幾個(gè)核心概念必須先建立認(rèn)知。我盡量用大白話解釋后面所有配置實(shí)操都建立在這套概念上。Agent智能體是最核心的單位你可以把它理解成一個(gè)“有角色設(shè)定的工作人員”。每個(gè) Agent 有獨(dú)立的身份描述、能力邊界、工具清單和記憶空間。配置 Agent 時(shí)最關(guān)鍵的不是寫(xiě)一段很長(zhǎng)的 prompt而是把“職責(zé)邊界”描述清楚。我自己常用的寫(xiě)法是“你是負(fù)責(zé) X 的角色。你需要做 A、B、C。你不需要做 D、E。當(dāng)遇到 F 情況時(shí)你必須把任務(wù)轉(zhuǎn)交給 Y 角色?！边吔缜逦饶芰?qiáng)大更重要。Skill技能是 Agent 可以調(diào)用的具體能力相當(dāng)于給工作人員配的工具。比如“網(wǎng)頁(yè)搜索”“調(diào)用數(shù)據(jù)庫(kù)”“讀取 Excel”“生成圖片”。OpenClaw 里 Skill 可以是內(nèi)置的默認(rèn)技能也可以是通過(guò)插件擴(kuò)展的自定義技能。配置 Skill 時(shí)要注意不是每個(gè) Agent 都需要所有技能給“排版潤(rùn)色”角色一個(gè)網(wǎng)頁(yè)搜索工具反而是多余且危險(xiǎn)的。Trigger觸發(fā)器是系統(tǒng)的“事件開(kāi)關(guān)”。配置了 Trigger 之后Agent 不會(huì)默默待命而是會(huì)在特定條件下被喚醒。比如“當(dāng)收到新任務(wù)時(shí)啟動(dòng)”“當(dāng)定時(shí)任務(wù)觸發(fā)時(shí)啟動(dòng)”“當(dāng)某個(gè)外部 webhook 調(diào)用時(shí)啟動(dòng)”。在多 Agent 系統(tǒng)里Trigger 是編排流程的起點(diǎn)也是最容易被忽視但是最影響系統(tǒng)響應(yīng)效率的部分。Memory記憶是 Agent 的“信息存取空間”。不同 Agent 可以共享某些記憶空間也可以擁有私有記憶。配置 Memory 時(shí)需要明確每個(gè) Agent 能看到哪些歷史信息、不能看到哪些。信息隔離做得不好的話很容易出現(xiàn)“一個(gè) Agent 把另一個(gè) Agent 的中間狀態(tài)當(dāng)成了最終結(jié)果”之類的低級(jí)錯(cuò)誤。這四個(gè)概念的關(guān)系可以這么類比Agent 是員工Skill 是員工桌上的工具清單Trigger 是公司里的通知鈴聲Memory 是員工的筆記本和共享文檔庫(kù)。一套好的 OpenClaw 配置就是把這四類元素完整、合理地定義出來(lái)。2.3 設(shè)計(jì)原則一個(gè) Agent 至少回答四個(gè)問(wèn)題我在看了大量質(zhì)量參差不齊的多 Agent 配置之后總結(jié)出一個(gè)小原則配置任何一個(gè) Agent 之前都要確保以下四個(gè)問(wèn)題在配置文件中有明確答案缺一個(gè)這個(gè) Agent 后面運(yùn)行大概率會(huì)出問(wèn)題。第一個(gè)問(wèn)題這個(gè) Agent 的角色是什么能做什么、絕對(duì)不應(yīng)該做什么這對(duì)應(yīng)到配置里的身份描述和工具范圍。第二個(gè)問(wèn)題這個(gè) Agent 什么時(shí)候應(yīng)當(dāng)啟動(dòng)是輪詢、觸發(fā)還是消息驅(qū)動(dòng)如果觸發(fā)條件沒(méi)有明確會(huì)出現(xiàn)“該干活的不干活”或者“不該干的先搶著干了”的情況。第三個(gè)問(wèn)題這個(gè) Agent 的輸出格式是什么JSON、自然語(yǔ)言、Markdown、代碼片段下游 Agent 能否直接消費(fèi)這個(gè)輸出多 Agent 系統(tǒng)里最常見(jiàn)的連鎖故障就是上游輸出格式混亂、下游解析器直接崩潰。第四個(gè)問(wèn)題這個(gè) Agent 如果干不了或者遇到異常該向誰(shuí)求助或者如何終止很多配置里根本沒(méi)人管異常分支結(jié)果上游 Agent 一旦出問(wèn)題整個(gè)流程就掛死。之后的配置實(shí)操會(huì)反復(fù)用到這四個(gè)問(wèn)題作為校驗(yàn)標(biāo)準(zhǔn)。3. 從零開(kāi)始配置多 Agent環(huán)境準(zhǔn)備與工程結(jié)構(gòu)3.1 安裝與版本選擇的坑OpenClaw 的安裝方式不算復(fù)雜常規(guī)的操作是先把倉(cāng)庫(kù)克隆到本地然后安裝依賴。但有一個(gè)細(xì)節(jié)至關(guān)重要——版本鎖定。我見(jiàn)過(guò)不少人在配置過(guò)程中遇到詭異報(bào)錯(cuò)排查半天發(fā)現(xiàn)是版本不對(duì)最新版已經(jīng)改了某個(gè)配置項(xiàng)的寫(xiě)法但網(wǎng)上教程還在用舊版格式。我的建議非常明確首次搭建環(huán)境時(shí)用穩(wěn)定發(fā)布的 release 版本而不是直接拉取 main 分支的最新代碼。README 里通常會(huì)標(biāo)注推薦版本號(hào)按那個(gè)來(lái)。另外依賴安裝時(shí)建議使用虛擬環(huán)境創(chuàng)建獨(dú)立運(yùn)行空間避免和系統(tǒng)全局的其他 Python 包沖突。多 Agent 項(xiàng)目本身依賴就多用全局環(huán)境的話版本沖突問(wèn)題會(huì)讓你懷疑人生。安裝完成之后強(qiáng)烈建議先跑一下官方提供的最小配置文件確認(rèn)基礎(chǔ)服務(wù)能正常啟動(dòng)再去折騰多 Agent 的復(fù)雜結(jié)構(gòu)。省得后面配置出問(wèn)題時(shí)分不清是環(huán)境問(wèn)題還是配置文件問(wèn)題。3.2 推薦的目錄結(jié)構(gòu)與配置分離思路一個(gè)可維護(hù)的多 Agent 項(xiàng)目目錄結(jié)構(gòu)應(yīng)當(dāng)遵循“配置與邏輯分離”的思路。我目前比較推薦下面這種組織方式y(tǒng)our-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這種結(jié)構(gòu)的核心價(jià)值在于每個(gè) Agent 一個(gè)獨(dú)立文件改配置時(shí)的改動(dòng)范圍被限制在一個(gè)文件里不同類別的配置互相隔離定位問(wèn)題的時(shí)候能很快縮小范圍。我自己一開(kāi)始圖省事把所有 Agent 的配置堆在一個(gè)大文件里結(jié)果項(xiàng)目跑到后期每次改動(dòng)都要小心翼翼稍不注意改錯(cuò)一處就會(huì)連帶影響其他 Agent。后來(lái)我花了半天時(shí)間把配置拆分到獨(dú)立文件并按約定組織改動(dòng)體驗(yàn)立刻好了很多——改一個(gè)角色的定義完全不擔(dān)心碰到另一個(gè)角色的配置。3.3 環(huán)境變量與密鑰管理多 Agent 系統(tǒng)通常要接入各種外部服務(wù)比如大模型 API、搜索服務(wù)、數(shù)據(jù)庫(kù)。這些服務(wù)的密鑰絕對(duì)不應(yīng)該出現(xiàn)在配置文件里。正確的做法是把密鑰放在環(huán)境變量文件中比如項(xiàng)目根的 .env 文件然后在配置文件里通過(guò) ${VAR_NAME} 的占位符形式來(lái)引用。# .env 文件內(nèi)容示例 MODEL_API_KEYsk-xxxxxxxxxxxxxxxx DATABASE_URLpostgresql://user:passlocalhost:5432/yourdb SEARCH_API_KEYxxx配置文件里的引用方式model_provider: api_key: ${MODEL_API_KEY}這里有一個(gè)隱蔽的坑有些版本的 OpenClaw 加載環(huán)境變量時(shí)只讀取特定路徑下的 .env 文件。如果你把 .env 放在子目錄里運(yùn)行時(shí)可能會(huì)提示找不到變量。我在第一次配置時(shí)就踩了這個(gè)坑日志顯示“變量未定義”后來(lái)發(fā)現(xiàn)是文件路徑問(wèn)題。解決方法是把 .env 保持在項(xiàng)目根目錄并且確認(rèn)啟動(dòng)命令的工作目錄正確。密鑰管理還有一個(gè)容易被忽視的點(diǎn)如果項(xiàng)目要用 Git 做版本管理確認(rèn) .env 加入了忽略列表不要提交到倉(cāng)庫(kù)。密鑰泄露的教訓(xùn)不用多講了每次看到有人在示例代碼里貼真實(shí) key 我都替他捏把汗。4. Agent 配置文件的逐字段拆解4.1 一個(gè)最小可用的 Agent 長(zhǎng)什么樣雖然 OpenClaw 的配置項(xiàng)很多但一個(gè) Agent 要能跑起來(lái)并不是所有字段都需要手動(dòng)定義。先看一個(gè)除了“能運(yùn)行”之外不帶任何花哨功能的最小配置理解這個(gè)基礎(chǔ)結(jié)構(gòu)之后再往里加?xùn)|西# config/agents/writer.yaml name: writer description: 負(fù)責(zé)將資料整理成結(jié)構(gòu)化文章初稿的撰寫(xiě)角色。 model: provider: ${MODEL_PROVIDER} name: ${MODEL_NAME} temperature: 0.7 skills: - document_loader - text_formatter instructions: | 你是文章撰寫(xiě)角色。 你的輸入是素材收集角色的輸出。 你的輸出是完整的文章初稿。 你需要將素材整合成邏輯通順的初稿并標(biāo)注待核查事實(shí)。你也許注意到了這個(gè)最小配置里沒(méi)有寫(xiě) trigger也沒(méi)有寫(xiě) memory。原因很簡(jiǎn)單在多 Agent 體系里一個(gè) Agent 不一定需要自己擁有觸發(fā)器和獨(dú)立記憶它可以完全作為流程中的一環(huán)被其他 Agent 調(diào)用或者由協(xié)調(diào)者統(tǒng)一分配任務(wù)。初學(xué)者在配置中最容易犯的錯(cuò)誤就是給每個(gè) Agent 都塞滿所有字段結(jié)果根本分不清哪些是生效的哪些是無(wú)效的。最小配置教給你一個(gè)思維先跑通再豐富。4.2 instructions 字段的寫(xiě)法任務(wù)、邊界與協(xié)作規(guī)范不少教程把 instructions 直接等同于“提示詞”然后用寫(xiě) prompt 的方式寫(xiě)一大堆背景知識(shí)和性格設(shè)定。這個(gè)認(rèn)知需要修正。在多 Agent 場(chǎng)景下instructions 的本質(zhì)是“操作手冊(cè)”不是“角色小傳”。高可維護(hù)性的 instructions 應(yīng)當(dāng)包含以下三類內(nèi)容。第一類是任務(wù)定義。明確這個(gè) Agent 接收什么輸入、執(zhí)行什么處理、產(chǎn)出什么輸出。建議用明確的動(dòng)詞開(kāi)頭比如“接收”“解析”“生成”“校驗(yàn)”避免模棱兩可的表述。寫(xiě)“整理資料并輸出初稿”就不如寫(xiě)“讀取素材文件夾中的所有 Markdown 文件提取核心觀點(diǎn)按指定的文章大綱框架生成初稿”來(lái)得清晰。第二類是邊界聲明。明確這個(gè) Agent 不做哪些事。比如寫(xiě)作 Agent 應(yīng)當(dāng)聲明“不負(fù)責(zé)事實(shí)核查不負(fù)責(zé)最終排版遇到不確定的數(shù)據(jù)時(shí)在文中用【待核查】標(biāo)記不自行推斷”。第三類是合作規(guī)范。明確這個(gè) Agent 遇到什么情況該向誰(shuí)求助。比如“如果輸入文件格式無(wú)法解析將錯(cuò)誤信息發(fā)送給故障處理 Agent不要嘗試自行修復(fù)”。這一條看著簡(jiǎn)單但真正寫(xiě)在配置里的人少之又少。來(lái)一段我實(shí)際用過(guò)的 instructions 示例instructions: | 你是資源收集角色。你的任務(wù)是根據(jù)選題文案中的需求收集相關(guān)的公開(kāi)資料并以結(jié)構(gòu)化列表輸出。 輸入格式協(xié)調(diào)者發(fā)送的包含選題內(nèi)容的 JSON 對(duì)象。 輸出格式包含 資源標(biāo)題、來(lái)源URL、摘要、置信度 四個(gè)字段的 JSON 數(shù)組。 你不負(fù)責(zé)撰寫(xiě)正文。你不負(fù)責(zé)判斷資料的真?zhèn)沃恍枰獦?biāo)注來(lái)源。 如果某個(gè)關(guān)鍵詞在搜索后沒(méi)有返回任何結(jié)果不要編造 URL直接返回空數(shù)組并提供說(shuō)明字段。 與本任務(wù)無(wú)關(guān)的消息請(qǐng)忽略。這套寫(xiě)法跑起來(lái)之后下游 Agent 的解析成功率明顯提升原因很簡(jiǎn)單上游輸出格式固定了下游處理指定字段就行了不用猜。4.3 多模型與多 Provider 的配置策略一個(gè)經(jīng)常被拿到臺(tái)面上討論的配置問(wèn)題是多個(gè) Agent 是否可以使用不同的模型答案是肯定的而且在很多場(chǎng)景下是必要的。不同 Agent 的任務(wù)復(fù)雜度不同用同一個(gè)模型會(huì)造成資源浪費(fèi)或能力不足。我的建議是分層配置模型。復(fù)雜度低、吞吐量大的任務(wù)比如格式轉(zhuǎn)換、文本提取可以用輕量模型來(lái)跑速度快且成本低。復(fù)雜度高、需要推理能力的任務(wù)比如規(guī)劃拆解、復(fù)雜語(yǔ)義判斷給更強(qiáng)的模型。形式化的配置大概長(zhǎng)這樣# 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有一個(gè)值得留意的點(diǎn)是 temperature 這個(gè)參數(shù)。并不是所有任務(wù)都適合把 temperature 調(diào)高。規(guī)劃和分類這類任務(wù)需要穩(wěn)定性和可復(fù)現(xiàn)性temperature 低一點(diǎn)更合適。生成創(chuàng)意文案的任務(wù)可以適當(dāng)調(diào)高讓輸出更多樣化。我在配置時(shí)規(guī)劃類 Agent 的 temperature 通常不超過(guò) 0.3創(chuàng)作類 Agent 可以到 0.8。4.4 Skill 注冊(cè)與權(quán)限控制OpenClaw 里的技能有兩種來(lái)源內(nèi)置技能和你自己寫(xiě)的自定義技能。配置的核心不在怎么注冊(cè)而在于“每個(gè) Agent 該掛載哪些技能”。我給一個(gè)很直白的建議配置技能時(shí)遵循最小權(quán)限原則。給 Agent 分配技能時(shí)先問(wèn)自己“完成這個(gè) Agent 的任務(wù)真的需要這個(gè)技能嗎”不需要的技能就不要掛載。為什么因?yàn)榧寄懿恢皇悄芰σ彩枪裘婧透蓴_源。一個(gè)不需要聯(lián)網(wǎng)的 Agent 如果掛載了網(wǎng)絡(luò)搜索技能當(dāng)它的上下文里出現(xiàn)“查一下”這類詞時(shí)模型可能就會(huì)擅自觸發(fā)搜索反而拖慢處理速度。多 Agent 系統(tǒng)配置的規(guī)范其實(shí)和“公司給員工配發(fā)賬號(hào)權(quán)限”的邏輯高度一致——按需分配最小可見(jiàn)互相不越權(quán)。技能注冊(cè)示例skills: - name: document_loader config: allowed_extensions: [md, txt, docx] max_file_size: 10MB - name: web_search config: max_results: 5 timeout_seconds: 15這里也有一個(gè)值得注意的細(xì)節(jié)技能本身可以帶配置參數(shù)。同一個(gè)技能在不同 Agent 里的參數(shù)配置可以不同。比如搜索技能在素材收集 Agent 里的單次結(jié)果限制可以放寬到 10 條在事實(shí)核查 Agent 里可以設(shè)成 3 條以提升精準(zhǔn)度。5. 多 Agent 的通信與編排配置5.1 Agent 間的消息路由直接與間接多 Agent 系統(tǒng)最能體現(xiàn)設(shè)計(jì)功力的環(huán)節(jié)是通信。OpenClaw 里的通信不是“Agent 之間直接喊話”而是通過(guò)“消息總線”進(jìn)行路由。換句話說(shuō)Agent 不關(guān)心消息是誰(shuí)發(fā)的、發(fā)給誰(shuí)它只關(guān)心自己訂閱了什么類型的消息、自己發(fā)布了什么類型的消息。用行話講這是“事件驅(qū)動(dòng)的發(fā)布訂閱模式”。配置 Agent 時(shí)你需要明確兩個(gè)字段它能接收的事件類型subscribe和它能發(fā)布的事件類型publish。舉個(gè)例子name: coordinator triggers: - type: event event_name: new_task_created action: publish_new_task subscriptions: - event_name: task_completed action: track_progress這種設(shè)計(jì)的優(yōu)點(diǎn)在于解耦。增加一個(gè)新的 Agent 時(shí)不需要修改其他 Agent 的配置只要新 Agent 訂閱相應(yīng)的事件類型即可。這就像辦公室里新來(lái)了一個(gè)同事在通訊錄和郵件列表里加入它的郵箱就好不需要通知所有人改聯(lián)系方式。對(duì)應(yīng)的反例是如果配置成直接調(diào)用的方式A Agent 直接調(diào)用 B Agent 的接口那一旦 B 的接口簽名變了或者超時(shí)了A 就跟著掛。在配置層面我強(qiáng)烈推薦優(yōu)先使用事件驅(qū)動(dòng)的通信方式。5.2 串行流程與并行流程的配置區(qū)別流程編排有兩種基本形態(tài)串行和并行。先看串行的例子——一個(gè)典型的“收集資料 → 撰寫(xiě)初稿 → 核查事實(shí)”流程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這里的關(guān)鍵設(shè)計(jì)在于每個(gè) stage 的 input_event 是上一個(gè) stage 的 output_event。下游 Agent 不會(huì)因?yàn)樯嫌芜€沒(méi)完成而提前啟動(dòng)因?yàn)橛|發(fā)條件一直沒(méi)有滿足。這種模式天然避免了“消息來(lái)了但上游還沒(méi)處理完”的競(jìng)態(tài)問(wèn)題。并行的配置同樣不復(fù)雜。假設(shè)“收集資料”階段需要同時(shí)做“公開(kāi)資料搜索”和“內(nèi)部文檔檢索”之后再把結(jié)果合并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并行配置的核心問(wèn)題在于“合并等待”匯總 Agent 必須等兩個(gè)并行事件都完成后才能啟動(dòng)。在 OpenClaw 配置里通常在合并 Agent 的 trigger 上加一個(gè)條件等待多個(gè)事件同時(shí)滿足。如果你發(fā)現(xiàn)合并 Agent 經(jīng)常在只收到一個(gè)事件時(shí)就搶跑大概率是條件沒(méi)有配置完整這是最需要仔細(xì)檢查的點(diǎn)之一。5.3 Memory 共享與隔離的配置技巧多 Agent 系統(tǒng)里 Memory 配置是最容易出安全問(wèn)題、也最容易出邏輯問(wèn)題的地方。先明確一個(gè)基本規(guī)則共享的 Memory 只放全局信息私有 Memory 放過(guò)程信息。全局共享類信息包括品牌調(diào)性描述、目標(biāo)用戶畫(huà)像、項(xiàng)目基礎(chǔ)數(shù)據(jù)、通用術(shù)語(yǔ)表。這些是所有 Agent 都需要知道的放在共享 Memory 里是正確的否則每個(gè) Agent 的上下文里都缺基本信息協(xié)作就會(huì)走樣。過(guò)程信息則必須隔離。比如“writer 正在起草的文章版本”就是 writer 的私有信息其他 Agent 沒(méi)有權(quán)限訪問(wèn)。如果所有過(guò)程信息全部共享Agent 之間會(huì)互相干擾各自讀到一堆與自己無(wú)關(guān)的中間狀態(tài)導(dǎo)致判斷混亂。共享 Memory 配置示例memory: shared: - name: brand_basics type: document path: memory/shared/brand_basics.md private: - name: draft_scratchpad scope: writer type: sqlite從信息安全的角度私有 Memory 的隔離防止了任務(wù)邊界被突破。假如一個(gè)收集公開(kāi)資料的 Agent 被惡意提示詞攻擊如果它能訪問(wèn)內(nèi)部文檔的 Memory潛在風(fēng)險(xiǎn)會(huì)明顯放大。所以私有 Memory 的配置不僅是邏輯需要也是安全配置的一部分。5.4 協(xié)調(diào)者的配置調(diào)度還是演員多 Agent 系統(tǒng)是否需要一個(gè)“總指揮”Agent業(yè)界沒(méi)有統(tǒng)一答案。我個(gè)人的經(jīng)驗(yàn)是系統(tǒng)里 Agent 數(shù)量超過(guò) 3 個(gè)就值得配置一個(gè)協(xié)調(diào)者角色。協(xié)調(diào)者的作用不是把活都自己干了而是做“任務(wù)路由”——識(shí)別新進(jìn)來(lái)的任務(wù)屬于什么類型分派給對(duì)應(yīng)的執(zhí)行者監(jiān)控執(zhí)行結(jié)果判斷是否需要二次分派或終止流程。配置協(xié)調(diào)者的核心仍然在于邊界協(xié)調(diào)者不做具體的專業(yè)活只做調(diào)度決定。name: coordinator model: provider: provider-a name: powerful-model-x temperature: 0.2 instructions: | 你是任務(wù)協(xié)調(diào)者。 你的職責(zé)是接收新任務(wù)消息判斷任務(wù)類型分派給對(duì)應(yīng)的執(zhí)行角色。 你不直接撰寫(xiě)內(nèi)容也不直接執(zhí)行資料收集。 當(dāng)某個(gè)執(zhí)行角色多次報(bào)告失敗時(shí)記錄狀態(tài)并通知管理員不嘗試自行修復(fù)。協(xié)調(diào)者的存在讓整個(gè)系統(tǒng)有了一個(gè)可以追加全局邏輯的錨點(diǎn)超時(shí)重試、異常兜底、流程終止條件都可以圍繞協(xié)調(diào)者的 Trigger 和 Skill 展開(kāi)。5.5 超時(shí)、重試與最大迭代次數(shù)配置多 Agent 流程一旦跑起來(lái)最讓人提心吊膽的就是“卡死”。Agent 之間互相等待、消息丟失、循環(huán)調(diào)用這些都是真實(shí)存在的運(yùn)行風(fēng)險(xiǎn)。我在配置中會(huì)強(qiáng)制要求為每個(gè)流程設(shè)置三類保護(hù)參數(shù)。第一類超時(shí)參數(shù)。無(wú)論執(zhí)行者是外部 API 調(diào)用還是內(nèi)部處理都必須設(shè)置明確的超時(shí)時(shí)間。我通常把每個(gè) Agent 的單次執(zhí)行超時(shí)限制在 120 秒左右超過(guò)之后直接判定該節(jié)點(diǎn)失敗并觸發(fā)兜底邏輯。第二類重試參數(shù)。網(wǎng)絡(luò)請(qǐng)求類的技能比如搜索、外部 API 調(diào)用值得重試但重試次數(shù)要有限制。重試間隔用遞增策略比如第一次失敗后等 2 秒第二次等 5 秒第三次等 10 秒。不能無(wú)限重試設(shè)置最大重試 3 次是性價(jià)比最高的選擇。第三類最大迭代次數(shù)。某些 Agent 可能因?yàn)樘崾驹~設(shè)計(jì)不當(dāng)出現(xiàn)“循環(huán)生產(chǎn)”的情況。防止這一點(diǎn)可以在流程配置里設(shè)定全局最大迭代步數(shù)達(dá)到上限后強(qiáng)制終止當(dāng)前流程并生成診斷信息。下面是一個(gè)綜合的編排配置片段execution_control: global_max_steps: 20 default_timeout_seconds: 120 retry_policy: max_retries: 3 base_delay_seconds: 2 multi_delay: true這些參數(shù)看似不起眼但關(guān)鍵時(shí)刻能救命。我后來(lái)接手維護(hù)過(guò)的幾個(gè)項(xiàng)目里超過(guò)一半的“卡死”問(wèn)題都是因?yàn)闆](méi)配最大迭代次數(shù)Agent 陷入了死循環(huán)而沒(méi)有任何保護(hù)機(jī)制。6. 實(shí)戰(zhàn)配置完整示例三角色內(nèi)容生產(chǎn)系統(tǒng)6.1 系統(tǒng)結(jié)構(gòu)與任務(wù)流設(shè)計(jì)為了把前面的概念串起來(lái)我準(zhǔn)備了一個(gè)完整可落地的示例一個(gè)內(nèi)容生產(chǎn)系統(tǒng)包含三個(gè) Agent。這個(gè)系統(tǒng)解決的實(shí)際問(wèn)題是給定一個(gè)內(nèi)容選題自動(dòng)完成資料收集、初稿撰寫(xiě)、事實(shí)核查三個(gè)階段的工作最終輸出一篇帶引用來(lái)源的文本稿件。三個(gè)角色及職責(zé)如下協(xié)調(diào)者coordinator接收外部任務(wù)判斷任務(wù)類型用事件驅(qū)動(dòng)的方式把任務(wù)分派給收集者。收集者collector根據(jù)選題關(guān)鍵詞收集公開(kāi)資料輸出結(jié)構(gòu)化的資料清單。撰寫(xiě)者writer基于資料清單撰寫(xiě)初稿全文引用來(lái)源。核查者reviewer逐條核查初稿中的事實(shí)和引用輸出核查報(bào)告與可信度評(píng)分。這套系統(tǒng)的核心流程是串行加并行的混合結(jié)構(gòu)協(xié)調(diào)者分派任務(wù)收集者在收到任務(wù)后并行跑兩個(gè)搜索技能完成后再通知撰寫(xiě)者開(kāi)始工作撰寫(xiě)者完成初稿后核查者介入。6.2 Agent 配置清單與逐項(xiàng)解釋下面我給出四個(gè)角色的完整配置摘錄重點(diǎn)部分會(huì)加注釋說(shuō)明思路。首先是協(xié)調(diào)者。它的關(guān)鍵觸發(fā)條件是新任務(wù)事件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: | 你是任務(wù)協(xié)調(diào)者。你接收 task.received 事件根據(jù)任務(wù)描述判斷類型。 如果任務(wù)屬于內(nèi)容生產(chǎn)發(fā)布 task.assigned 事件并附上統(tǒng)一的 job_id。 你不執(zhí)行資料收集、不撰寫(xiě)、不核查。然后是收集者name: collector model: provider: provider-b name: lightweight-model-y temperature: 0.3 triggers: - type: event event_name: task.assigned condition: 任務(wù)類型為內(nèi)容生產(chǎn) 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: | 你是資料收集角色。根據(jù)協(xié)作者提供的選題關(guān)鍵詞執(zhí)行搜索并整理資料清單。 輸出格式為 JSON 數(shù)組字段包括 title、url、summary、confidence。 搜索無(wú)結(jié)果時(shí)不得編造 URL。 完成清單后發(fā)布 material.ready 事件。接著是撰寫(xiě)者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: | 你是撰寫(xiě)角色。讀取收集者發(fā)布的資料清單整理成完整初稿。 所有事實(shí)表述必須附上對(duì)應(yīng)的來(lái)源標(biāo)記 [n]。 如果資料不足在稿件中明確標(biāo)注信息缺口不得虛構(gòu)內(nèi)容。 完成后發(fā)布 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: | 你是事實(shí)核查角色。逐條檢查初稿中的事實(shí)陳述與來(lái)源編號(hào)。 輸出核查報(bào)告包含每條陳述的可信度評(píng)級(jí)和修改建議。 你只做核查不直接修改稿件。6.3 啟動(dòng)完整系統(tǒng)的步驟清單配置寫(xiě)完之后啟動(dòng)整個(gè)系統(tǒng)我通常按下面這五步走每一步都有明確的檢查點(diǎn)。第一步檢查配置文件的語(yǔ)法。OpenClaw 的配置文件是 YAML 格式Y(jié)AML 對(duì)縮進(jìn)極度敏感。我建議先在編輯器里安裝 YAML 校驗(yàn)插件或者用命令行的解析工具做一次語(yǔ)法校驗(yàn)確保沒(méi)有格式錯(cuò)誤?？s進(jìn)錯(cuò)誤是配置文件無(wú)法啟動(dòng)的頭號(hào)原因。第二步檢查環(huán)境變量。確認(rèn) .env 文件里引用的每個(gè)變量在實(shí)際運(yùn)行環(huán)境中都存在。一個(gè)簡(jiǎn)單的方法是啟動(dòng)時(shí)留意日志里是否有“未定義變量”的告警。第三步啟動(dòng)基礎(chǔ)服務(wù)并觀察日志。先不急著向系統(tǒng)發(fā)任務(wù)先啟動(dòng)框架觀察各 Agent 是否正常注冊(cè)、觸發(fā)器是否成功加載。這一步相當(dāng)于“開(kāi)機(jī)自檢”。第四步用一條最簡(jiǎn)單的任務(wù)做端到端測(cè)試。發(fā)送一條“請(qǐng)撰寫(xiě)一篇關(guān)于人工智能在制造業(yè)應(yīng)用的淺析文章”這樣的測(cè)試任務(wù)走一遍完整流程查看各日志節(jié)點(diǎn)的狀態(tài)流轉(zhuǎn)是否符合預(yù)期。第五步觀察并記錄正常的基線耗時(shí)。每個(gè)流程跑完之后記錄一下總耗時(shí)和各階段耗時(shí)后面做性能優(yōu)化或者排查問(wèn)題時(shí)這份基線數(shù)據(jù)是最有價(jià)值的參照。我個(gè)人的習(xí)慣是每次改完配置都會(huì)從第三步重新跑一遍強(qiáng)制形成“改動(dòng)必須驗(yàn)證”的閉環(huán)。沒(méi)有這個(gè)習(xí)慣的話改了配置不敢保證還能跑通遇到問(wèn)題也分不清是這次改動(dòng)引入的還是本來(lái)就有。7. 常見(jiàn)問(wèn)題定位與排查手段7.1 Agent 不響應(yīng)或不觸發(fā)Agent 配置好了、流程也啟動(dòng)了但某個(gè) Agent 就是不干活。這種問(wèn)題我用一句話總結(jié)排查思路先問(wèn)觸發(fā)條件再問(wèn)訂閱路由最后檢查日志。觸發(fā)條件的排查重點(diǎn)是看該 Agent 的 trigger 是否真的被定義。如果它的工作方式是被事件驅(qū)動(dòng)的檢查發(fā)布方是否真的發(fā)布了對(duì)應(yīng)事件。最笨但最有效的方法是在日志里搜索事件名如果發(fā)布端日志里沒(méi)有該事件產(chǎn)生那問(wèn)題在發(fā)布端如果有而產(chǎn)生端沒(méi)有響應(yīng)那問(wèn)題出在訂閱關(guān)系上。訂閱關(guān)系的排查重點(diǎn)在于配置中的事件名是否完全一致。OpenClaw 對(duì)事件名的匹配通常是精確匹配大小寫(xiě)、中劃線、下劃線的差異都會(huì)導(dǎo)致匹配失敗。我的經(jīng)驗(yàn)是所有事件名統(tǒng)一用[小寫(xiě)字母加下劃線]風(fēng)格避免混用不同命名風(fēng)格從根上規(guī)避這類問(wèn)題。7.2 上下游消息格式不匹配導(dǎo)致解析崩潰這是我做多 Agent 項(xiàng)目以來(lái)遇到最多的問(wèn)題也是最隱蔽的一類故障。通常的癥狀是上游 Agent 執(zhí)行正常日志里顯示輸出也正常但下游 Agent 讀取消息后解析報(bào)錯(cuò)或者輸出明顯不合理的內(nèi)容。問(wèn)題根因往往在于——上游輸出的是自然語(yǔ)言描述下游卻按嚴(yán)格的 JSON 格式去解析或者上游輸出的是 Markdown 表格下游按純文本分割邏輯解析。我從這個(gè)坑里總結(jié)出一套行之有效的規(guī)范在任何 Agent 的 instructions 里用最明確的措辭規(guī)定輸出格式并給出一個(gè)格式示例。不要只寫(xiě)“輸出 JSON 數(shù)組”而是直接附上如下示例輸出格式如下 [ {title: 示例標(biāo)題, url: https://example.com, summary: 摘要, confidence: 0.9} ] 如果你無(wú)法完成任務(wù)輸出 {error: 簡(jiǎn)短說(shuō)明}不要輸出其他內(nèi)容。示例比解釋有效一百倍。實(shí)踐下來(lái)附帶了格式示例的配置下游解析失敗率能降低一大截。如果問(wèn)題已經(jīng)發(fā)生了排查技巧是打開(kāi)日志找到消息傳遞過(guò)程中記錄的數(shù)據(jù)負(fù)載實(shí)際內(nèi)容然后對(duì)比解析器的預(yù)期格式人肉找出差異在哪里再回到配置里把示例寫(xiě)清楚。7.3 提示詞沖突與上下文污染多 Agent 系統(tǒng)的另一個(gè)高頻問(wèn)題可以概括為“上下文污染”——A Agent 的消息串進(jìn)了 B Agent 的上下文。這類問(wèn)題的場(chǎng)景很典型所有 Agent 共用同一個(gè) Memory 空間每個(gè) Agent 運(yùn)行時(shí)都把全部 Memory 內(nèi)容塞進(jìn)上下文。一旦 Agent 數(shù)量多了每個(gè) Agent 的上下文都會(huì)包含大量與自己無(wú)關(guān)的信息模型則可能被這些無(wú)關(guān)信息誤導(dǎo)。排查方向非常明確檢查每個(gè) Agent 的 Memory 配置確認(rèn)私有 Memory 是否真正隔離、公共 Memory 的內(nèi)容是否精簡(jiǎn)到了最少?！白钌佟钡臉?biāo)準(zhǔn)是——如果某些內(nèi)容不與當(dāng)前 Agent 的任務(wù)直接相關(guān)就不要出現(xiàn)在它的上下文里。配置上把大段的背景資料從一個(gè) Agent 的公共上下文里移到協(xié)作數(shù)據(jù)庫(kù)或者按需加載的外部文檔里通過(guò) Skill 讀取而非默認(rèn)塞給上下文可以有效切斷污染路徑。7.4 死循環(huán)與任務(wù)重復(fù)執(zhí)行死循環(huán)的表現(xiàn)形式是某個(gè)事件被同一個(gè) Agent 或者不同的 Agent 反復(fù)處理進(jìn)入無(wú)限重入狀態(tài)。典型例子是 A 發(fā)布了某個(gè)事件B 處理完后也發(fā)布了同樣的事件于是系統(tǒng)又認(rèn)為出現(xiàn)了新任務(wù)重新走了一遍流程。防范死循環(huán)要從配置規(guī)范上下功夫。我的做法是給所有任務(wù)事件加上唯一的 job_id 字段并且在每個(gè) Agent 的 instructions 里寫(xiě)明處理規(guī)則“如果當(dāng)前任務(wù) job_id 已被處理過(guò)直接丟棄該消息并結(jié)束流程?！绷硗馊肿畲蟮綌?shù)的配置一定要設(shè)置。它是最后的兜底即使邏輯上出了問(wèn)題導(dǎo)致死循環(huán)步數(shù)上限也能強(qiáng)制斷掉流程避免整個(gè)服務(wù)被拖垮。7.5 性能問(wèn)題事件太多、并發(fā)失控多 Agent 系統(tǒng)不需要刻意追求高性能因?yàn)闃I(yè)務(wù)場(chǎng)景大多屬于低并發(fā)的任務(wù)型處理。但有一種情況會(huì)讓人抓狂——并行分支太多事件噴發(fā)系統(tǒng)瞬間被消息淹沒(méi)。解決手段有兩個(gè)層面。第一個(gè)層面是收斂并行度在流程編排里控制并行分支的數(shù)量不要超過(guò) 5 個(gè)并行分支同時(shí)處理。第二個(gè)層面是限流OpenClaw 通常提供并發(fā)控制相關(guān)配置把同一時(shí)刻最多處理的任務(wù)數(shù)限制住讓系統(tǒng)在可控壓力下運(yùn)行。性能問(wèn)題的排查工具一般直接用日志里的事件吞吐數(shù)據(jù)來(lái)判斷。先看每秒處理了多少個(gè)事件EPC再看單個(gè) Agent 的平均處理延遲兩者配合就能定位到瓶頸節(jié)點(diǎn)。8. 配置維護(hù)與迭代建議最后分享幾個(gè)日常維護(hù)層面的建議都是我持續(xù)維護(hù)多 Agent 項(xiàng)目時(shí)覺(jué)得“早知道就好了”的點(diǎn)。第一個(gè)建議所有配置文件的修改都要留變更記錄。多 Agent 配置涉及的角色多節(jié)點(diǎn)多沒(méi)有變更記錄的話一個(gè)月后哪怕是自己回來(lái)看也說(shuō)不清當(dāng)初為什么把某個(gè)參數(shù)從 0.3 調(diào)到了 0.1。我自己的做法是配置倉(cāng)庫(kù)里維護(hù)一個(gè)簡(jiǎn)單的變更日志CHANGELOG每次改動(dòng)都寫(xiě)一行說(shuō)明——哪個(gè) Agent、哪些字段、為什么要改。這個(gè)習(xí)慣在排查問(wèn)題時(shí)價(jià)值極高。第二個(gè)建議定期檢查各 Agent 的輸出日志質(zhì)量。配置穩(wěn)定之后不能一直不管。我會(huì)每隔一段時(shí)間抽取一批日志樣本看輸出格式是否仍然規(guī)范和一致、模型是不是偷偷偏離了指令。系統(tǒng)跑著跑著出現(xiàn)輸出漂移是正?，F(xiàn)象關(guān)鍵是要及時(shí)發(fā)現(xiàn)并校準(zhǔn)。第三個(gè)建議Agent 的數(shù)量要用“加法思維”謹(jǐn)慎增加。每增加一個(gè) Agent系統(tǒng)的編排復(fù)雜度都會(huì)非線性上升。動(dòng)輒十幾個(gè) Agent 的項(xiàng)目協(xié)調(diào)成本非常高。能用簡(jiǎn)單流程解決的任務(wù)就不要為了炫技去堆 Agent。第四個(gè)建議保留一份“最小配置”作為救急方案。如果改著改著發(fā)現(xiàn)整個(gè)系統(tǒng)跑不起來(lái)了就可以回退到最小配置先恢復(fù)服務(wù)再?gòu)淖兏涗浝镎覇?wèn)題。沒(méi)有這套兜底方案線上出故障時(shí)只能干著急。這套配置體系事到如今我自己已經(jīng)從“看到配置文件就頭疼”的狀態(tài)變成了“先把架構(gòu)圖畫(huà)清楚再動(dòng)手寫(xiě)”的習(xí)慣。多 Agent 配置本身不復(fù)雜復(fù)雜的是業(yè)務(wù)邏輯的梳理和角色邊界的劃分。你只要邁過(guò)設(shè)計(jì)這關(guān)后面所有配置項(xiàng)都只是往骨架上填肉而已。希望這篇指南能幫你少走一點(diǎn)彎路把精力花在真正有價(jià)值的事情上。