OpenClaw 架构拆解：复杂 Agent 系统怎么分层
1. 为什么要拆 OpenClaw
OpenClaw 适合作为复杂 Agent 系统分层设计的学习对象。它不是一个简单的聊天 Demo，而是围绕多入口接入、会话管理、Agent Runtime、工具抽象、上下文管理、安全边界和评估闭环构建的工程系统。
对学习者来说，拆 OpenClaw 的价值不是背具体源码，而是理解生产级 Agent 系统如何拆层、如何解耦、如何控制复杂度。一个复杂 Agent 系统如果没有清晰分层，很容易把平台接入、会话状态、工具调用、安全审批和模型交互全部混在一起，最后变成难以调试、难以扩展、难以上线的脚本集合。
因此，这篇文章用 OpenClaw 的拆解视角，整理一套更适合学习和面试表达的 Agent 系统分层方法。
2. 核心观点：复杂 Agent 系统需要分层
普通 Agent Demo 可能只有一条很短的链路：
用户输入 → LLM → 工具调用 → 回复这类 Demo 适合验证想法，但很难承载复杂场景。因为真实系统面对的不只是"用户问一句，模型答一句"，还包括多平台入口、会话连续性、工具权限、长期记忆、失败恢复、执行记录、安全审查和质量评估。
复杂 Agent 系统需要：统一入口、多渠道适配、会话管理、任务运行时、工作空间、记忆系统、工具插件、安全控制、评估反馈。
Agent 工程的核心不是"多个角色聊天"，而是系统分层、状态流转、工具抽象、安全控制和可观测性。
3. OpenClaw 架构总览
下面这张表是当前站内对 OpenClaw 的拆解视角，不代表已经确认所有真实源码类名，也不编造源码路径。
| 层级 | 作用 | 解决的问题 |
|---|---|---|
| Gateway | 统一接入和控制入口 | 避免每个入口直接耦合 Agent Runtime |
| Channel | 适配不同平台、协议和消息格式 | 屏蔽 Telegram、Slack、Webhook、API 等差异 |
| Session | 管理当前会话上下文 | 保持多轮任务连续性和可恢复性 |
| Agent Runtime | 执行 Agent 任务 | 承接模型调用、工具调用、任务推进 |
| Workspace | 提供任务工作区 | 承载文件、中间结果、配置、临时产物 |
| Memory | 管理长期信息 | 保存稳定事实、偏好、经验和可复用上下文 |
| Skills | 提供可复用任务说明 | 让 Agent 学会特定任务的工作方式 |
| Tools | 执行具体外部操作 | 让 Agent 从回答问题升级为执行动作 |
| Plugins | 扩展系统能力 | 把外部平台、工具、搜索、媒体能力接入系统 |
| Compaction | 压缩上下文 | 控制长任务中的上下文膨胀 |
| Multi-Agent | 多 Agent 隔离和协作 | 处理职责边界、路由、权限和状态隔离 |
| Security | 安全边界 | 控制工具权限、审批、沙箱和审计 |
| Evaluation | 质量反馈 | 记录结果、失败原因、工具调用质量和改进方向 |
4. 核心运行链路
1. 外部请求进入 Gateway
Gateway 是统一入口。外部请求不应该直接进入 Agent Runtime，而是先经过统一入口做鉴权、路由、日志和基础校验。这样可以把平台接入和任务执行解耦。
2. Channel 适配不同来源
不同平台的消息格式不同，Channel 负责把它们转换成内部统一事件。这样 Agent Runtime 不需要理解每个平台的细节，只需要处理统一后的消息。
3. Session 维护会话上下文
Session 负责管理当前会话的上下文和任务连续性。同一个用户、同一个平台、同一个任务，需要落到可识别的会话里，避免状态混乱。
4. Agent Runtime 接管任务
Agent Runtime 是任务执行核心。它负责推进模型调用、工具调用、结果回填和任务结束判断，是 Agent 真正工作的地方。
5. Workspace 提供任务工作区
复杂任务不能只靠 Prompt。Workspace 用来承载文件、中间结果、代码、文档、技能和临时产物，让 Agent 有一个稳定的外部工作环境。
6. Memory 提供历史上下文
Memory 保存更长期的信息，例如稳定事实、用户偏好、任务经验和历史总结。Memory 不等于 Session，不能把所有历史无脑塞进当前上下文。
7. Skills / Tools 执行能力调用
Skills 提供完成任务的方法说明，Tools 提供具体执行能力。两者结合，让 Agent 不只是会回答，还能按照约束调用外部能力完成任务。
8. Plugins 扩展外部能力
Plugins 是系统扩展机制，可以注册工具、渠道、搜索、媒体等能力。它把外部能力接入系统，但仍然需要统一注册、权限和审计。
9. Compaction 压缩上下文
长任务会让上下文持续膨胀。Compaction 负责保留关键决策摘要、模型输出摘要、工具调用记录、状态变化记录和执行轨迹，压缩低价值历史。
10. Security 控制权限边界
Security 控制谁能触发 Agent、Agent 能访问什么工具、哪些操作需要审批、哪些内容要脱敏。安全边界必须在系统层实现，而不能只依赖 Prompt。
11. Evaluation 记录质量反馈
Agent 做完任务不代表任务成功。Evaluation 记录执行结果、失败原因、工具调用结果和质量反馈，帮助系统持续改进。
5. Gateway / Channel：统一入口与多渠道适配
Gateway 是统一接入入口。它负责把来自不同平台的请求收拢到同一个控制面中，统一处理鉴权、事件分发、健康状态、连接管理和任务入口。
Channel 负责适配不同平台、协议和消息格式。例如 Web、API、IM、Webhook 的输入格式都不同，如果让 Agent Runtime 直接处理这些差异，Runtime 会被平台细节污染，后续扩展也会变得困难。
对个人项目的启发是：未来如果要接 Web、API、IM、Webhook，最好先做统一入口和适配层。即使一开始只接一个入口，也可以在设计上保留 Gateway / Channel 的边界。
6. Session / Memory：上下文与长期记忆
Session 管理当前会话，Memory 管理更长期的信息。两者不能混为一谈。
Session 更关注当前任务的连续性：这一轮对话是谁发起的、属于哪个任务、当前执行到哪一步、是否需要继续等待用户输入。Memory 更关注跨会话可复用的信息：稳定事实、用户偏好、历史经验和长期知识。
不是所有历史都应该进入上下文。长任务中需要筛选、压缩和边界控制，否则上下文会被噪声填满，模型容易忽略关键状态。好的设计应该把 Session、Memory、Compaction 分开，而不是把所有记录都塞进一个消息数组里。
7. Agent Runtime / Workspace：任务执行核心
Agent Runtime 是任务执行核心。它承接模型调用、工具调用、任务推进、错误处理和结果生成。
Workspace 是任务过程中的工作区，用于承载文件、中间结果、代码、文档和临时产物。复杂任务不能把所有东西都塞进 Prompt，必须有外部工作空间。
Workspace 的价值在于让 Agent 有稳定的操作环境：它可以读取规则、写入中间文件、保存临时结果、引用已有文档。这样系统不会完全依赖一次对话上下文，也更容易调试和恢复。
8. Skills / Tools / Plugins：能力扩展层
Tools 是具体工具调用，例如读写文件、运行命令、查询接口、发送消息。Tools 让 Agent 从"会回答"升级为"能执行"。
Skills 是可复用能力包，用来告诉 Agent 如何完成一类任务。它更像方法论和操作说明，不是一次性的 Prompt。
Plugins 是系统扩展机制，负责把外部平台、工具、搜索、媒体等能力接入系统。三者共同组成能力扩展层：Tools 做执行，Skills 做方法沉淀，Plugins 做系统扩展。
9. Compaction：上下文压缩
长任务会导致上下文膨胀。历史消息、工具调用记录、错误信息和中间结果不断累积，如果不做压缩，模型上下文会变得越来越大、越来越噪。
Compaction 的作用是保留关键状态、压缩低价值历史。它应该保留目标、关键决策摘要、模型输出摘要、工具调用记录、状态变化记录和执行轨迹，而不是保留所有原始文本。
这对长时间运行 Agent 很关键。没有上下文压缩，长任务不是因为模型能力不足失败，而是因为上下文管理失控失败。
10. Security：安全边界
高风险工具调用需要审批。比如删除文件、修改配置、发送消息、访问敏感数据、执行命令等操作，都不应该完全自动化。
API Key、Token、隐私信息要脱敏。日志、错误信息、工具返回值都可能泄露敏感信息，所以脱敏不能只靠模型自觉，而应该由系统层处理。
工具权限要按场景控制。不同 Agent、不同入口、不同用户应拥有不同权限。不能把安全只交给 Prompt，安全边界应该在系统层实现，包括访问控制、工具策略、审批、沙箱和审计。
11. Evaluation：质量闭环
Agent 做完任务不代表任务成功。它可能调用了错误工具、遗漏关键步骤、生成了看似合理但不可执行的结果，或者消耗了过高成本。
Evaluation 需要记录执行结果、失败原因、工具调用结果和质量反馈。这样才能分析失败样本，发现流程漂移、工具失败、能力退化和高成本调用。
对生产级 Agent 来说，Evaluation 不是附加功能，而是质量闭环。没有 Evaluation，就无法证明系统是否比上一个版本更可靠。
12. Multi-Agent：协作不是自由聊天
Multi-Agent 需要职责边界。每个 Agent 应该知道自己负责什么、不负责什么、能使用什么工具、能访问什么上下文。
Multi-Agent 需要共享状态或明确的消息协议。否则多个 Agent 之间会出现信息不一致、重复执行、互相覆盖结果等问题。
Multi-Agent 还需要任务分派、结果聚合和停止条件。要避免多个 Agent 自由聊天导致流程失控。真正的多 Agent 协作是调度和状态管理问题，不是角色扮演问题。
13. 对个人项目的启发
- 先做系统分层，再做复杂功能。
- Agent Runtime 不应该直接处理所有平台适配。
- 工具调用必须标准化。
- Session 和 Memory 要分开设计。
- 长任务需要 Workspace 和 Trace。
- 高风险操作必须有安全边界。
- Multi-Agent 需要调度和状态，而不是角色扮演。
- Evaluation 是生产级 Agent 的必选项。
这些启发可以迁移到任何 Agent 项目中：先把入口、会话、运行时、工具、安全、评估分清楚，再逐步增加复杂能力。
14. 面试表达
可以这样表达：
我拆 OpenClaw 不是为了背具体源码，而是学习复杂 Agent 系统如何分层。普通 Agent Demo 可能只有用户输入、模型调用和工具调用，但生产级 Agent 系统需要 Gateway、Channel、Session、Agent Runtime、Workspace、Memory、Tools、Security、Evaluation 等模块协同工作。
我重点关注的是这些模块如何解耦：Gateway 负责统一入口，Channel 负责多平台适配，Session 和 Memory 分别管理当前上下文和长期信息，Agent Runtime 负责任务执行，Tools / Skills / Plugins 负责能力扩展，Security 负责权限边界，Evaluation 负责质量反馈。这样系统不会把所有逻辑堆到一个 Agent Loop 里。
这让我理解到生产级 Agent 的关键不是角色多，而是职责清晰、流程可控、工具可审计、状态可追踪、结果可评估。Multi-Agent 也不是多个角色自由聊天，而是有路由、有状态、有权限、有停止条件的工程系统。
15. 后续 TODO
- 补充 OpenClaw 真实源码路径和关键调用链。
- 绘制 OpenClaw 架构图。
- 对比 Hermes Agent 与 OpenClaw 的设计差异。
- 继续整理小红书 Day 4 内容。