主题
架构设计：系统长什么样？
读完这篇文档，你会理解 miniOpenClaw 的整体架构、各模块的分工配合，以及一条消息从进入到回复的完整旅程。
一、不要一上来就看"全家福"
很多技术文档喜欢一上来就甩一张复杂的架构全景图，看得人头昏脑涨。我们换个思路——像盖房子一样，一层一层往上搭。
阶段 1：消息基础设施（Day 1-3）—— 造一个"快递公司"
在做任何"智能"的事情之前，我们先解决一个基础问题：用户的消息怎么进来、怎么出去？
这就像开一家快递公司，首先要解决三件事：
📦 Day 1 Gateway（分拣中心）
所有快递（消息）都先到这里，贴上统一格式的标签，按类型分拨处理
📮 Day 2 Channel（取件方式）
上门取件（CLI）、驿站寄件（WebChat）、合作网点（Webhook）
不管从哪来的，到了分拣中心都是一样的快递单
📋 Day 3 Session（客户档案）
每个客户有自己的档案，记录所有寄件历史
同一个人在不同网点有不同的档案这个阶段结束后，我们有了一个能收发消息、管理对话的"空壳"——但它还不会"想"。
阶段 2：Agent 核心能力（Day 4-6）—— 雇一个"能干活的员工"
光有快递公司的基础设施没有用，我们需要一个"员工"来处理这些消息。这个员工就是 Agent。
🧠 Day 4 Agent（员工大脑）
收到任务 → 想一想 → 需要工具吗？→ 用工具 → 给出结果
🔧 Day 5 Tools（工具箱）
计算器、时钟、网络请求……放在工具柜里，按名字取用
📜 Day 6 Skills（技能证书）
翻译证书、编程证书……有了证书，员工就知道用什么"话术"来处理特定任务这个阶段结束后，我们有了一个能理解问题、使用工具、自动推理的 AI Agent。
阶段 3：进阶增强（Day 7-8）—— 让员工"更聪明"
基本功能有了，但员工还可以更聪明：
📓 Day 7 Memory（笔记本）
便签纸 = 短期记忆（当前对话内容，太多了自动清理旧的）
档案柜 = 长期记忆（跨对话的重要信息，持久保存）
工作清单 = SystemPromptBuilder（每次上班前整理今天的工作指南）
🤝 Day 8 MCP（跨公司合作）
甲方（miniOpenClaw）可以请乙方（外部 MCP Server）帮忙
也可以把自己的能力开放给别人用
通过标准的"合同格式"（JSON-RPC）沟通二、完整架构全景图
现在你已经理解了每个部分的角色，再看完整的架构图就不会晕了：
┌─────────────────────────────────────────────────────────────┐
│ miniOpenClaw │
│ │
│ 用户侧 │
│ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │
│ │ CLI │ │ WebChat │ │ Webhook(飞书/微信) │ │
│ │ Channel │ │ Channel │ │ Channel │ │
│ └────┬─────┘ └────┬─────┘ └────────┬───────────┘ │
│ │ │ │ │
│ └──────────────┼────────────────────┘ │
│ ▼ │
│ 消息层 ┌───────────────┐ │
│ │ Gateway │ 统一消息格式 + 路由分发 │
│ └───────┬───────┘ │
│ ▼ │
│ 会话层 ┌───────────────┐ │
│ │ Session │ 多用户多轮对话管理 │
│ └───────┬───────┘ │
│ ▼ │
│ 推理层 ┌──────────────────────────────────────────┐ │
│ │ Agent Runtime (ReAct) │ │
│ │ │ │
│ │ ┌─────────┐ ┌────────┐ ┌──────────────┐ │ │
│ │ │ Tools │ │ Skills │ │ Memory │ │ │
│ │ │ 工具系统 │ │技能系统│ │短期记忆+长期 │ │ │
│ │ └─────────┘ └────────┘ └──────────────┘ │ │
│ └──────────────────┬───────────────────────┘ │
│ ▼ │
│ 模型层 ┌───────────────┐ │
│ │ LLM Provider │ OpenAI / 兼容 API │
│ └───────────────┘ │
│ │
│ 扩展层 ┌──────────────────────────────────────────┐ │
│ │ MCP 协议支持 │ │
│ │ MCPClient ←→ 外部工具服务 │ │
│ │ MCPServer ←→ 外部 AI 客户端 │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘从上到下分为五层，每一层的职责清晰：
| 层次 | 职责 | 关键组件 |
|---|---|---|
| 用户侧 | 用户通过什么方式和 Agent 交互 | CLI、WebChat、Webhook |
| 消息层 | 统一消息格式、路由分发 | Gateway、EventBus、Router |
| 会话层 | 管理多用户多轮对话上下文 | Session、SessionManager、Storage |
| 推理层 | AI 的"大脑"，负责思考和行动 | AgentRuntime、Tools、Skills、Memory |
| 模型层 | 与 LLM（大模型）通信 | LLMProvider、OpenAIProvider |
| 扩展层 | 与外部生态对接 | MCPClient、MCPServer |
三、一条消息的完整旅程
让我们跟踪一条消息，看它从用户嘴里说出到最终收到回复的全过程：
场景：用户在网页上输入 "现在几点了？"
逐步解读：
- 用户发送：用户在网页上输入文字，通过 HTTP POST 发到 WebChat Channel
- 消息标准化：Channel 把 HTTP 请求体转成统一的
GatewayMessage格式——不管从哪来的消息，到这里都长一样 - 会话路由：SessionManager 根据用户 ID + 渠道查找（或创建）对应的 Session，里面有之前的聊天记录
- Agent 推理：AgentRuntime 拿到用户消息和历史记录，组装成一串消息发给 LLM
- 工具调用：LLM 判断需要查时间，返回"请调用 datetime_now 工具"
- 执行工具：Agent 从 ToolRegistry 找到这个工具并执行，拿到当前时间
- 再次推理：把工具结果告诉 LLM，LLM 组织语言给出最终回答
- 返回用户：回复沿着来的路原路返回，用户在网页上看到答案
四、核心设计原则
原则 1：模块化解耦——"换零件不用拆整台车"
每个模块通过定义好的接口交互，可以独立替换。
举个例子：如果你想把消息存储从"内存"换成"Redis"——
- 只需要写一个新的
RedisStorage类，实现SessionStorage接口 - 不需要改 Agent、Channel、Gateway 的任何代码
如果不这样做：所有代码混在一起，改一处动全身，维护噩梦。
原则 2：全异步设计——"一个服务员服务多桌"
整个系统使用 async/await 异步编程，一个进程可以同时处理多个用户的请求。
举个例子：用户 A 的消息正在等 LLM 回复（可能要等 3 秒）——
- 异步：在等待期间去处理用户 B 的消息，不浪费时间
- 同步：只能干等，用户 B 必须排队
原则 3：渐进式构建——"先学走再学跑"
每一章只在上一章的基础上增加一个新概念，不会一下子塞太多东西。
举个例子：Day 4 实现 Agent 时——
- 不需要理解 Tool 系统（Day 5 才学）
- 不需要理解 Skill 系统（Day 6 才学）
- 只需要理解"用户消息 → LLM → 回复"这个最简流程
原则 4：协议统一——"所有快递都用一种单子"
无论消息从 CLI、WebChat 还是 Webhook 进来，内部传输统一使用 GatewayMessage 格式。
如果不这样做：每种渠道的消息格式不一样，Agent 要写一堆 if channel == "cli" 的判断逻辑，代码又乱又难维护。
五、与真实生产系统的对比
miniOpenClaw 是教学项目，和真实的生产级 Agent 系统有哪些差异？
| 维度 | miniOpenClaw | 生产级系统 |
|---|---|---|
| 存储 | 内存 / JSON 文件 | Redis / PostgreSQL / 向量数据库 |
| 部署 | 单机运行 | Kubernetes 集群、微服务 |
| 安全 | 无认证 | OAuth / JWT / API Key 鉴权 |
| 监控 | logging 日志 | Prometheus + Grafana 全链路追踪 |
| 并发 | 单进程 asyncio | 多进程 + 消息队列 |
| 模型 | 单一 LLM Provider | 多模型路由、负载均衡、fallback |
但核心架构思想是一致的——理解了 miniOpenClaw，看真实系统的源码不会再一头雾水。
接下来读什么？
- 技术调研：了解每项技术的选型理由
- Day 1 Gateway：开始动手搭建第一个模块