架构全景：从消息接收到Agent协作

架构全景：从消息接收到 Agent 协作

本节从工程角度拆解 OpenClaw 的系统架构，追踪一条消息从用户发出到收到回复的完整执行路径。你会发现 OpenClaw 不只是一个聊天机器人，而是一个围绕 Agent 构建的运行时网关系统，具备消息适配、路由分发、会话管理、多 Agent 协作等企业级能力。

你能学到什么

完成本节学习后，你将能够：

1. 说出 OpenClaw 五层架构的名称和各自职责
2. 描述一条消息从进入到回复的八个处理步骤
3. 理解路由系统的三大判断逻辑
4. 解释会话隔离的四种策略及其适用场景
5. 说明多 Agent 协作的三种模式

一、整体架构：五层设计

OpenClaw 的架构可以抽象为五个层次，每一层各司其职，层与层之间通过明确的接口通信。这种分层设计的好处是——改一层不影响其他层，加一层不破坏现有逻辑。

下面逐层展开。

1.1 用户接口层

这一层解决的问题是"用户从哪进来"。OpenClaw 需要对接的平台很多——钉钉、飞书、Telegram、WhatsApp、Discord、QQ——每个平台的消息格式都不一样。用户接口层的工作就是把这些五花八门的格式统一成一种内部表示。

所有用户操作，不管是来自命令行、网页、手机 App 还是聊天平台，最终都会收敛成统一的内部消息模型。这样后面的处理逻辑就不用关心"这条消息是从哪来的"，只需要关心"这条消息的内容是什么"。

1.2 Gateway 核心层

Gateway 是系统常驻运行的核心进程。它做的事情很基础但很关键：维持所有外部连接、接收和分发消息、动态加载配置、监控系统健康状态。

这一层的目标只有一个：让整个系统"活着"——能接消息、能回消息、能维持状态。如果这一层挂了，整个系统就瘫了。

1.3 消息处理层

这是业务逻辑流转的核心。一条消息进来之后，要经过路由判断（交给谁处理）、会话管理（加载哪些历史上下文）、Agent 执行（调用模型和工具）、出站投递（把回复发回给用户）。

后面我们会用一整节来详细拆解这一层的每个步骤。

1.4 扩展与插件层

这一层是 OpenClaw 可扩展性的来源。通道插件让你能对接新的聊天平台，技能工具系统让 AI 能做更多事情，Sub Agent 机制让多个 AI 协作完成复杂任务，MCP 桥接让 AI 能访问外部数据源。

1.5 基础设施层

最底层提供通用能力：配置管理、结构化日志、定时任务、事件总线、记忆检索、沙箱安全。这些能力被上面各层共享，是系统正常运行的地基。

二、消息的完整旅程

现在我们沿着一条消息的路径，看看它从进入到出去经历了什么。

假设一个场景：你在钉钉中发送了一条消息——"帮我整理今天的重要邮件，提炼待办，并生成一份给老板的简报"。

图：消息处理完整链路

2.1 第一步：协议适配

不同平台的消息格式差异很大。钉钉的消息结构和飞书不同，Discord 和 WhatsApp 也不同——有的叫 message_id，有的叫 thread_ts；附件、引用、线程信息的表示方式也各不相同。

OpenClaw 的解决方案是给每个外部渠道配一个专属适配器插件。适配器的职责很明确：把原始消息清洗成统一的内部对象。这样一来，后面的处理逻辑完全不需要关心消息来自哪个平台。

这个设计带来三个好处：统一抽象让所有平台消息变成相同格式；隔离差异让平台特异性不会污染核心逻辑；易扩展让新增渠道只需实现一个新的适配器。

2.2 第二步：消息收束

所有经过适配的入站消息，都会汇聚到一个统一的入口函数。这个函数做两件事：

第一，最终化上下文——补全缺失字段、标准化格式、统一上下文表示。不同渠道传来的消息可能缺少某些字段，或者字段含义有微妙差别，这一步把它们全部对齐。

第二，交给分发器——确保消息进入核心处理逻辑后能被安全处理。分发器会检查消息的完整性，防止因为数据缺失导致后续步骤出错。

2.3 第三步：路由判断

消息进入主链路后，要经过三次关键判断：

第一次判断：要不要处理？

网络抖动、Webhook 重试都可能导致同一条消息被收到两次。去重检查通过为每条消息生成幂等键来防止重复处理。如果检测到重复，直接返回缓存结果，既节省计算资源也节省 API 调用费用。

第二次判断：有没有缓存？

查询最近是否处理过相同的请求。如果是，直接返回缓存结果，提升响应速度。

第三次判断：交给哪个 Agent？

根据消息类型、会话状态、用户配置、技能触发词等规则，把消息分发给最合适的 Agent 处理。

2.4 第四步：会话管理

路由完成后，系统需要找到或创建这条消息所属的会话。会话管理做三件事：

会话隔离：每个用户、每个频道、每个线程可以有独立的会话，互不干扰。

上下文组装：加载这个会话的历史消息，连同当前消息一起组装成完整的上下文，提供给 Agent 使用。

状态持久化：实时保存会话状态，支持断点恢复。如果系统意外重启，可以从上次的位置继续处理。

2.5 第五步：Agent 执行

这是整个链路中最核心的一步。Agent 执行器加载用户配置的 Agent，注入所需的技能，然后调用 AI 模型进行推理。

执行过程中有几个值得注意的特性：

• 技能动态注入：根据任务需求，系统会动态加载相关技能的指令和脚本，不需要把所有技能都塞进上下文
• 流式输出：支持流式返回，用户可以实时看到生成进度，不用干等
• 中断恢复：如果执行过程中遇到错误，可以从断点恢复，不用从头开始

2.6 第六步：工具调用

Agent 在推理过程中可能需要调用工具——执行一段脚本、查询一个数据库、调用一个外部 API。工具系统提供统一的调用接口，同时做权限控制和审计记录。

调用流程是：Agent 决定调用 → 系统验证权限 → 执行工具 → 返回结果给 Agent → Agent 继续推理。这个循环可能执行多次，直到 Agent 认为任务完成。

2.7 第七步：响应投递

Agent 生成的回复需要按目标平台的格式要求做适配。钉钉有钉钉的格式，飞书有飞书的格式，Telegram 又有另一套。出站投递模块负责这个转换工作。

2.8 第八步：状态持久化

最后一步，系统保存本次会话的完整状态：对话历史、执行日志、记忆更新。这些数据用于支持后续的断点恢复、问题调试和长期记忆构建。

⚠️ 注意：如果你发现 OpenClaw 的响应突然变慢，首先检查会话历史是否过长。过长的上下文会消耗更多 token 和处理时间。可以通过配置限制单会话的历史长度来缓解。

三、多 Agent 协作机制

OpenClaw 的一个独特能力是支持多个 Agent 协作完成任务。当一个任务太复杂、一个 Agent 搞不定时，主 Agent 可以创建子 Agent（Sub Agent）来分工合作。

3.1 三种协作模式

3.2 实际案例

回到开头的场景："帮我整理今天的重要邮件，提炼待办，并生成一份给老板的简报"。

这条指令涉及三个独立子任务。主 Agent 会这样处理：

1. 创建子 Agent A，连接邮箱获取今天的邮件列表
2. 创建子 Agent B，对邮件内容做分析，提取待办事项
3. 创建子 Agent C，把分析结果整理成简报格式
4. 主 Agent 聚合三个子 Agent 的输出，生成最终回复

这种模式的好处是——三个子任务可以并行执行，总耗时取决于最慢的那一个，而不是三个任务的时间之和。

💡 提示：在设计多 Agent 协作时，尽量让子任务之间互不依赖，这样可以充分利用并行执行的优势。如果子任务之间有依赖关系，就需要用顺序流水线模式。

四、关键设计亮点

4.1 工程化设计

OpenClaw 不是实验性质的玩具，而是一个面向生产环境的系统。它在设计层面就考虑了幂等控制、错误处理、重试机制和监控告警。这些特性在开发阶段可能感知不到，但一旦上了生产，就是系统稳定运行的保障。

4.2 插件化架构

通道插件、技能插件、Agent 插件、中间件插件——OpenClaw 的几乎每个核心能力都可以通过插件来扩展。这意味着你不需要修改核心代码就能增加新功能。

4.3 多租户支持

企业场景下，一套 OpenClaw 实例可以服务多个团队。用户隔离、权限管理、配额管理、审计日志这些企业级特性都已内置。

本节要点

• OpenClaw 采用五层架构：用户接口层、Gateway 核心层、消息处理层、扩展与插件层、基础设施层
• 一条消息从进入到回复经历八个步骤：协议适配 → 消息收束 → 路由判断 → 会话管理 → Agent 执行 → 工具调用 → 响应投递 → 状态持久化
• 路由系统做三次判断：要不要处理、有没有缓存、交给哪个 Agent
• 多 Agent 协作支持任务分解、并行执行、顺序流水线三种模式
• 插件化架构和工程化设计是 OpenClaw 可扩展性和生产级可靠性的基础