多智能体这个词这两年已经被说烂了但真正能跑通、能交付、能上线的东西其实不多。我见过太多团队卡在同一个地方Demo很惊艳一上真实业务就崩不是智能体之间互相丢消息就是工具调用上下文错乱最后只能回到纯单线程的LLM调用多智能体沦为PPT里的装饰词。我最近基于开源项目 OpenClaw 从零搭了一套多智能体协作系统从需求拆分、环境搭建、工具注册、任务编排到最终部署跑通完整走了一遍流程。这篇文章把全流程拆开揉碎写清楚包括代码、配置、踩坑记录和优化思路给那些想真正落地多智能体的人一个可以直接抄作业的参考。先放一个最简单的 OpenClaw 效果让你对这个框架的体量有个直观感受。下面是一个两个智能体接力协作的例子import openclaw openclaw.tool def search_web(keyword: str) - str: 检索外部信息返回文本片段 return f搜索结果: {keyword} - 相关文档段落... planner openclaw.Claw(nameplanner, modellocal-qwen) writer openclaw.Claw(namewriter, modellocal-qwen) result planner.run(查找多智能体框架的常用工具设计并交给后续智能体整理成方案) print(result.tool_calls) print(result.output)这个例子麻雀虽小五脏俱全一个工具函数被注册两个 Claw 实例按顺序接力最后输出结果。OpenClaw 的设计核心就是让这种工具注册 多角色协作 上下文透传的流程变得轻量可控不需要自己写一堆消息队列和状态管理代码。1. 为什么要用多智能体以及 OpenClaw 的定位1.1 单智能体做不到的事才需要多智能体很多场景其实单次 LLM 调用就够了比如写一段文案、翻译一句话、做一次文本分类。这种需求上多智能体纯属自找麻烦。真正的多智能体需求通常有三个共同特征第一任务需要多种能力组合但能力之间耦合度低。比如市场调研 数据分析 报告生成这三件事让一个模型从头做到尾上下文会越拖越长最后生成的报告可能前后矛盾。第二不同环节需要不同的系统提示词和参数配置。规划智能体需要低温、严谨、强指令遵循创意写作智能体需要高温、发散、风格自由。你没法在一个模型调用里同时满足这两种极端参数。第三用户需要看到过程而不仅仅是结果。多智能体系统天然会产生中间决策、子任务记录和协作轨迹这些内容对业务方理解系统行为、排查错误非常重要单智能体在这方面的黑盒特性反而成短板。1.2 OpenClaw 到底是个什么东西OpenClaw 是一个轻量级多智能体编排框架核心思路是每个智能体是一个 Claw 实例Claw 之间可以互相调用、共享工具、传递上下文。它提供了一套统一的工具注册机制、一个共享内存系统以及一个可扩展的钩子系统Hook。和市面上那种动辄几百 MB 依赖、需要独立服务端的企业级多智能体平台不同OpenClaw 走的是嵌入式、可编程、本地优先的路线。它不强制你用一个中心化控制器去管理所有智能体而是让智能体彼此像服务一样发现和调用。这对中小团队或者个人开发者非常友好不需要微服务架构不需要独立的消息中间件一个 Python 进程里就能跑完整套协作逻辑。我选择 OpenClaw 的另一个原因是它的可观测性做得比较直接。框架内置了调用链记录从某个 Claw 收到任务开始到它决定调用哪个工具、再到把结果传回对话上下文每一步都有日志。这个特性在调试多智能体系统时几乎等于救命稻草因为多智能体系统最难查的问题就是某个中间步骤到底发生了什么导致最终结果跑偏。1.3 用表格对比常见方案的差异方案定位上手难度可控性适合场景纯手写 LLM 循环自己维护对话历史、工具调用、路由逻辑高最高需要对每个细节完全掌控企业级多智能体平台图形化编排、可视化监控、服务端部署中中团队协作、非编程人员参与OpenAI Assistants 这类托管 API云上托管、快速集成低低快速验证、标准场景OpenClaw嵌入式、可编程、本地优先低-中高需要定制协作流程、本地数据敏感、离线环境OpenClaw 的可控性来自它的透明性所有协作逻辑都是普通 Python 代码没有隐藏的平台魔法。出问题的时候你可以直接打断点调试这和黑盒平台完全不同。2. 环境准备与安装过程2.1 环境要求与虚拟环境创建OpenClaw 的依赖比较克制核心库只依赖 Python 3.10 以上版本、一个 HTTP 客户端和一个文件锁库。GPU 不是必须的但如果你跑本地大模型推荐至少 16GB 显存用 API 方式接入则完全不需要 GPU。我习惯先建虚拟环境再安装避免污染系统 Pythonpython3 -m venv .venv source .venv/bin/activate pip install openclaw安装完成后可以用命令行验证claw --version这一步正常的话说明核心框架已经就绪。之后还需要一个基础依赖包用于工具函数开发pip install pydantic requestspydantic 用于定义工具函数的输入输出结构requests 用于在工具函数里发起外部 HTTP 调用这两项是后续开发中最常用的。2.2 模型接入配置OpenClaw 本身不绑定任何特定模型供应商。它通过一个统一的模型后端接口来对接各类推理服务无论是云端 API 还是本地部署的模型都可以通过同一套配置接入。推荐使用 YAML 文件管理模型配置因为多智能体场景下往往需要为不同智能体配置不同模型。下面是一个典型的配置model_backends: local_qwen: type: openai_compatible base_url: http://127.0.0.1:8000/v1 api_key: unused model_name: qwen2.5-7b-instruct cloud_default: type: openai model_name: gpt-4o-mini temperature: 0.3这里的关键点是 type 字段。OpenClaw 为兼容 OpenAI 接口的服务提供了一条通用适配路径也就是说任何支持 OpenAI 风格接口的模型服务都可以通过同一个 type 接入。你既可以用本地推理框架启动的服务也可以用云上 API配置文件差别只是 base_url 和 model_name。配置完成后可以用一个小脚本确认智能体能正常对话import openclaw claw openclaw.Claw(nametest, modellocal_qwen) print(claw.chat(你好请回复收到))如果返回结果正常说明模型链路打通。这个环节虽然简单但千万别跳因为后续所有智能体协作都建立在这条链路上模型配置错误是后面各种诡异问题的第一大来源。2.3 工具函数注册机制OpenClaw 真正的威力在工具系统。工具函数就是一个普通 Python 函数加上openclaw.tool装饰器之后自动变成可被智能体调用的武器。框架会从函数的类型注解和 docstring 中提取结构信息自动生成给模型看的工具描述。下面是一个典型工具函数的完整写法import requests import openclaw openclaw.tool def fetch_weather(city: str) - str: 获取指定城市的实时天气信息。参数 city 为城市名例如 上海。 url fhttps://api.example.com/weather?city{city} resp requests.get(url, timeout5) data resp.json() return f{city}当前天气: {data[condition]}, 温度 {data[temperature]} 度openclaw.tool会自动完成三件事解析函数签名生成 JSON Schema、将 docstring 转换为模型可读的语义描述、在智能体决定调用该工具时自动完成参数绑定和结果回传。我测试过工具描述的详细程度对模型调用准确率影响非常大。函数名和 docstring 写得含糊模型就会出现幻觉参数或者干脆不调用工具。比如上面这个例子docstring 里写明city 为城市名模型才知道怎么填参数。建议把参数取值范围、返回值格式都写清楚。3. 核心概念与协作机制拆解3.1 Claw 实例的本质带上下文的小型独立代理一个 Claw 实例本质上是一个具备独立系统提示词、独立模型配置、独立对话历史的小型代理。它不是一个常驻进程而是一个轻量对象你可以随时创建、销毁、重新组合。我通常用一个类比来理解它Claw 有点像公司里的一个职员。每个职员有自己岗位说明书系统提示词、自己的笔记本对话历史、自己的工具箱注册的工具集合。一个任务要交给不同职员协作完成时你只需要安排好流程让笔记本在合适的时候传给下一个人。在多智能体场景中这意味着你不需要在一条超长上下文里塞入所有信息而是让信息在合作者之间精准流转。规划智能体只需要知道任务目标和可用的资源列表检索智能体只需要知道查询条件写作智能体只需要拿到前两步的成果物。各自上下文短、专注度高产出质量自然就上来了。3.2 共享状态让多个 Claw 读写同一片内存Claw 之间协作最关键的问题是状态共享。OpenClaw 内置了一个共享内存系统每个 Claw 都可以通过claw.memory读写结构化数据。planner openclaw.Claw(nameplanner, modellocal_qwen) analyzer openclaw.Claw(nameanalyzer, modellocal_qwen) # planner 写入中间结果 planner.run(分析这个项目需求并归纳为三个可执行任务) shared_tasks planner.memory.get(tasks) print(shared_tasks) # analyzer 读取同一份状态继续干活 analyzer.run(基于共享状态中的任务列表输出技术方案)共享状态存储在当前进程的内存中适合单机协作场景。如果涉及分布式部署OpenClaw 也提供了钩子机制允许你把状态同步到 Redis 或数据库这部分内容后续在优化章节展开。3.3 钩子系统在关键节点插入自定义逻辑钩子系统是 OpenClaw 扩展性的核心。它允许你在智能体运行的各个阶段插入自定义函数包括智能体收到任务前、模型返回响应后、工具调用前、工具返回后。最典型的应用场景是日志监控和内容过滤。比如我想记录每个智能体调用了什么工具可以这样实现import openclaw openclaw.hook(before_tool_call) def log_tool_call(claw_name: str, tool_name: str, args: dict): print(f[{claw_name}] 准备调用 {tool_name}, 参数: {args}) return args # 返回原始参数继续执行 claw openclaw.Claw(nameaudit, modelcloud_default) claw.attach_hook(log_tool_call)我实际项目中用钩子做过两件非常重要的事。第一件是敏感信息过滤在工具调用前检查参数里是否包含手机号或身份证格式的字符串如果命中直接阻断并返回预设的告白信息。第二件是耗时监控统计每个工具的执行时间超过阈值的调用自动记录到慢操作日志里。钩子系统的设计很聪明因为它在不改动核心代码的前提下提供了干预能力。对于生产环境这比直接改框架源码要安全可靠得多。4. 完整落地做一个信息收集与报告生成的多智能体系统4.1 需求拆解与架构设计我以行业信息调研 分析报告生成为例完整走一遍落地流程。这个场景非常典型需要外部检索能力、需要结构化输出能力、需要多阶段协作而且结果必须可复现、可调试。整体架构分三层。第一层是协调层由一个 Coordinator 智能体负责任务拆解、进度推进和结果汇总。第二层是执行层包括一个 Researcher 智能体负责调用检索工具收集资料一个 Analyst 智能体负责对资料进行结构化分析一个 Writer 智能体负责将分析结果写成报告。第三层是基础层包含检索工具、存储工具和配置文件。选择这种架构而不是一个超长提示词的单一模型是因为调研任务的结果质量和过程可控性同样重要。三个执行智能体各司其职上下文窗口都不会太长同时每一步的中间产物都被记录后续可以回溯是哪一步出错导致最终结果偏差。4.2 代码实现从工具到智能体再到主流程第一步定义工具函数。这一步我通常会先把所有外部能力抽象成函数再注册给框架。import requests import openclaw openclaw.tool def search_docs(keyword: str, limit: int 5) - list: 在内部知识库中检索与 keyword 相关的文档返回最多 limit 条结果的标题和摘要。 resp requests.post(https://search.internal/solr/query, json{q: keyword, rows: limit}, timeout10) docs resp.json()[docs] return [{title: d[title], summary: d[content][:200]} for d in docs] openclaw.tool def save_report(filename: str, content: str) - str: 将最终报告保存为本地 Markdown 文件返回文件路径。 with open(freports/{filename}, w, encodingutf-8) as f: f.write(content) return freports/{filename}这里有两个值得注意的设计细节。search_docs的返回值是结构化的列表而不是纯文本字符串这样后续智能体可以直接基于结构化字段做分析不需要从一大段文本里重新抽取信息。save_report接收 content 参数时不做任何加工完全信任上游传入的字符串这要求 Writer 智能体在调用前必须生成完整内容避免半截输出。第二步创建智能体并配置角色。coordinator openclaw.Claw( namecoordinator, modelcloud_default, system_prompt你是一个严谨的项目协调者。你的任务是将用户需求拆解为执行步骤分配给合适的智能体并汇总最终结果。每一步都必须明确记录关键信息输出要结构化。, temperature0.1 ) researcher openclaw.Claw( nameresearcher, modelcloud_default, system_prompt你是一个研究助理。你的任务是基于指定关键词反复调用 search_docs 工具获取资料并将资料整理为带来源摘要的要点列表。不要主观评价内容质量只做客观归纳。, temperature0.0 ) writer openclaw.Claw( namewriter, modellocal_qwen, system_prompt你是一个分析报告写作者。你会收到一组资料要点需要将其扩展为结构清晰、语言严谨的调研报告包括背景说明、核心发现、潜在风险和建议四个部分。报告语言为中文。, temperature0.4 )可以看到三个智能体用了两个不同的模型。Coordinator 和 Researcher 用云端模型做高精度指令跟随Writer 用本地模型做文本生成这个组合在成本和质量之间取得了不错的平衡。第三步实现协作流程。协作的核心是前序智能体的输出作为后序智能体的输入。我们用共享内存来传递中间状态def run_research_pipeline(topic: str): # 阶段一协调者拆解任务 coord_result coordinator.run( f用户希望调研主题: {topic}。请设计检索关键词集合不超过三个。 ) keywords parse_keywords(coord_result.output) coordinator.memory.set(keywords, keywords) # 阶段二研究者检索资料 research_notes [] for kw in keywords: note researcher.run(f检索关键词: {kw}将结果整理为要点列表) research_notes.append(note.output) researcher.memory.set(notes, research_notes) # 阶段三写作者生成报告 final_report writer.run( f以下是从知识库检索得到的资料要点:\n{format_notes(research_notes)}\n f请基于这些要点撰写一份主题为《{topic}》的调研报告。 ) # 阶段四调用保存工具落盘 path save_report(filenamefreport_{datetime.now():%Y%m%d}.md, contentfinal_report.output) return path这段代码展示了多智能体最核心的编排模式任务在智能体之间像接力棒一样传递每个智能体只处理自己负责的环节最终汇总为完整产出。parse_keywords和format_notes是辅助函数用于将模型的自由文本输出解析为程序可用的数据结构。4.3 执行结果与过程分析跑完整个流程后你会得到一个完整的 Markdown 调研报告文件。但比结果更重要的是过程日志。OpenClaw 在每次运行时都会输出类似下面的记录[coordinator] 收到任务: 用户希望调研主题: 开源法律合规平台 [coordinator] 调用工具: none [coordinator] 输出: 1. 开源许可证合规; 2. 法律风险案例; 3. 合规自动化工具 [researcher] 收到任务: 检索关键词: 开源许可证合规 [researcher] 调用工具: search_docs({keyword: 开源许可证合规, limit: 5}) [researcher] 工具返回: [{title: GPL协议使用边界, ...}, ...] [writer] 收到任务: 以下是从知识库检索得到的资料要点... [writer] 调用工具: save_report({filename: report_20250115.md, ...})观察真实执行过程最明显的收益是每个环节都在做减法Coordinator 不做检索、Researcher 不做写作决策、Writer 不需要理解检索逻辑只需要面向结构化输入做生成。这种职责分离让单个智能体失败时系统整体的恢复成本非常低。如果报告质量差只需要调整 Writer 的系统提示词如果检索结果不相关只需要调整 Researcher 的检索循环策略完全不需要重写整个流程。5. 常见问题与排查技巧实录5.1 模型配置失效导致智能体静默失败症状智能体调用 run 之后直接返回空字符串没有任何报错。排查过程先检查模型后端单独调用是否正常发现命令行直接给模型发请求是好的。再看 OpenClaw 配置发现模型名称打错了模型服务端根本不认识这个名称但框架在初始化时没有做模型存在性校验导致运行阶段才静默失败。解决方法在配置里添加模型名称同时写一个单独的连通性测试脚本在启动流程前自动跑一次。这个脚本在 CI 里跑也很有用。5.2 工具函数参数绑定错误症状智能体明确调用了工具但报缺少必需参数或参数类型错误。原因分析框架依赖函数签名来生成工具描述但如果函数的参数名不够自解释模型可能填错参数名。比如参数命名为kw模型可能不知道应该传什么。解决方法工具函数参数名一定要用完整、直白的命名。与其叫kw不如叫keyword。除此之外给 docstring 里每个参数加一行格式说明模型会参考这个信息做参数绑定。实测下来docstring 写清楚的工具调用成功率能提升 20 个百分点以上。5.3 多个智能体状态不同步症状A 智能体写入共享内存的数据B 智能体读取时是空的。原因分析OpenClaw 的共享内存默认绑定到一个 Claw 实例。如果你在代码里创建了两个不同作用域的 Coordinator 实例或者在不同线程里分别初始化它们的共享内存不是同一片空间。解决方法确保整个流程中使用的是同一个 Claw 实例引用把实例作为全局单例管理。如果跨线程协作需要在初始化时显式指定同一个共享存储后端比如SharedMemory(scopeglobal)。这一点在写服务端应用时尤其需要留意因为每次请求都会重新创建框架实例很容易出现状态隔离问题。5.4 我一直遇到的几个常见坑的速查表问题根本原因处理方式智能体一直在调用同一个工具不退出系统提示词里没说明何时停止在提示词中加如果需要的信息已获取请停止调用工具并直接输出结果输出的一半是数据库字段名模型被工具返回的原始结构带偏在工具里就把返回内容格式化为自然语言或可视化 Markdown 结构生成报告前后观点不一致上下文被截断或中间信息丢失在流程中加验证智能体读取最终报告与原始要点核对一致性5.5 调试多智能体系统的效率工具如果你和我一样需要频繁调试多智能体系统强烈建议把下面三样东西做成标配第一给每个智能体设置独特的名字这样看日志时能一眼分辨消息来源。第二在钩子里自动记录每个智能体收到的原始输入和最终输出这样可以随时回放某个智能体的完整执行历史。第三用官方提供的本地调试面板它能把调用链可视化展示出来查看总耗时和各步骤耗时非常方便。生产环境不一定需要面板但开发调试阶段它简直是效率神器。6. 优化方向与落地边界6.1 性能瓶颈与成本意识多智能体系统最大的开销不是工具调用而是大模型的多次推理。一个包含 4 个智能体的流程每个智能体平均 2 次模型调用整体就是 8 次推理如果某个智能体需要多轮反思或重试这个数字会翻倍甚至翻三倍。控制成本的办法有几个我实际测试过都有明显效果。第一能用小模型处理的环节绝不用大模型比如关键词提取、文本分类这类任务用参数量较小的模型就能做得很好。第二工具函数里可以做数据预裁剪只把真正必要的信息传给模型减少输入 token。第三给每个智能体限定最大调用轮数超过后强制输出当前结果而不是无限循环。第四对部分确定性较强的环节直接跳过模型调用比如简单的日期格式化、字符串拼接用普通 Python 代码处理比让模型处理又快又省钱。6.2 什么时候不应该用多智能体这一点非常重要。多智能体不是银弹它引入的复杂度是实打实的更多模型调用更多失败点更多需要调试的协作逻辑。我见过有人为了一个关键词提取任务搭建了三个智能体的系统纯属本末倒置。适合用多智能体的场景有个共同特征任务本身可以自然切分为多个独立环节且每个环节需要不同的知识领域或不同的处理逻辑。比如技术调研报告、竞品分析、客户工单分类流转、代码审查流程等。不适合的场景包括一次对话就能完成的简单问答、对延迟极度敏感的实时交互、上下文共享需求极高的任务。最后一个尤其需要注意如果所有智能体都需要频繁访问同一份大规模数据那共享上下文的成本会高到让你怀疑人生不如直接用单模型加长上下文更省事。6.3 扩展方向异步协作与外部存储OpenClaw 的默认模式是同步编排流程会阻塞等待每个智能体返回。但实际业务中有些任务不需要即时结果可以在后台跑完再通知用户。框架提供了异步运行接口只需要把 run 换成 arun然后在合适时机获取结果。如果需要跨服务部署或持久化状态可以接管共享内存接口。比如把共享内存的读写实现改为操作 Redis 键值模式这样多个 OpenClaw 进程可以共享同一份运行时状态。这个扩展方向的收益很大相当于把多智能体系统从单进程扩展到了分布式架构而核心代码不用重写只需要替换存储后端。我在实际项目中就做过类似的尝试让任务队列在服务端进程 A 里运行同时另一个进程 B 处理结果校验和归档两者通过同一个 Redis 共享状态协调。整体上代码改动很小但系统的吞吐和可靠性提升明显。最后分享一个我个人体会最深的点多智能体系统不要追求智能要追求可控。很多人一上来就想把所有能力塞给智能体让它们自由发挥结果得到一堆失控的输出。真正生产可用的多智能体系统每一个智能体的职责边界、每一步的输入输出结构、每一条工具调用的规则都是事先约定好的。OpenClaw 这套框架的价值不在于让智能体变聪明而在于让聪明的模型在一个有边界的框架内各司其职。你越早接受多智能体本质上是一种工程分工模式这句话就越容易做出真正能落地的系统。