主题
miniOpenClaw —— 从零构建一个 Python AI Agent 框架
一个面向编程新手的 AI Agent 教学项目——用 8 天时间，从第一行代码开始，理解 AI Agent 框架的完整架构与实现原理。
写在前面
如果你用过 ChatGPT、文心一言、通义千问，你已经体验过"聊天机器人"了。但你有没有想过：
- 为什么它们只能"聊天"，不能帮你查天气、下订单？
- 为什么它们经常"失忆"，不记得你上次说了什么？
AI Agent（智能体）就是为了解决这些问题而存在的。它在"聊天机器人"的基础上，加了工具（能动手做事）、记忆（能记住你）、技能（能切换模式）。
miniOpenClaw 就是带你从零搭建这样一个 AI Agent 框架——不用任何 AI 框架，只用基础 Python 库。
建议阅读顺序
第一步：理解全局（先看设计文档）
| 顺序 | 文档 | 内容 | 预计时间 |
|---|---|---|---|
| 1 | 需求分析 | 我们要做什么、为什么做、名词解释 | 15 分钟 |
| 2 | 架构设计 | 系统长什么样、各部分怎么配合 | 20 分钟 |
| 3 | 技术调研 | 为什么选这些技术、有哪些备选方案 | 15 分钟 |
第二步：逐章学习（边读边动手）
| 章节 | 主题 | 核心类比 | README | 设计文档 |
|---|---|---|---|---|
| Day 1 | Gateway 消息协议 | 快递分拣中心 | README | design |
| Day 2 | Channel 适配器 | 快递取件方式 | README | design |
| Day 3 | 会话管理 | 银行客户档案 | README | design |
| Day 4 | Agent 运行时 | 新员工上班 | README | design |
| Day 5 | 工具系统 | 员工工具箱 | README | design |
| Day 6 | 技能系统 | 技能证书 | README | design |
| Day 7 | 记忆系统 | 员工笔记本 | README | design |
| Day 8 | MCP 协议 | 跨公司合作 | README | design |
第三步：可视化体验（辅助理解）
每章配有交互式前端页面，无需 API Key 即可体验各模块的运行原理（详见下方"可视化学习页面"）。
架构总览
┌─────────────────────────────────────────────────────────┐
│ miniOpenClaw │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ CLI │ │ WebChat │ │ Webhook (飞书/微信) │ │
│ │ Channel │ │ Channel │ │ Channel │ │
│ └────┬─────┘ └────┬─────┘ └────────┬─────────────┘ │
│ │ │ │ │
│ └──────────────┼────────────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Gateway │ 统一消息格式 + 路由分发 │
│ └───────┬───────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Session │ 多用户多轮对话管理 │
│ └───────┬───────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Agent Runtime (ReAct) │ │
│ │ │ │
│ │ 用户输入 → LLM 推理 → 工具调用? → 执行 → 回答 │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ ┌─────────────────┐ │ │
│ │ │ Tools │ │ Skills │ │ Memory │ │ │
│ │ │ 工具系统 │ │ 技能系统 │ │ 短期记忆+长期记忆│ │ │
│ │ └─────────┘ └──────────┘ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ LLM Provider │ OpenAI / 兼容 API │
│ └───────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ MCP 协议支持（可选） │ │
│ │ MCPClient: 连接外部 MCP Server │ │
│ │ MCPServer: 暴露内置工具给外部客户端 │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘技术栈
| 技术 | 用途 | 为什么选它 |
|---|---|---|
| Python 3.11+ | 编程语言 | AI 生态最完善、学习门槛低 |
| asyncio | 异步编程 | 一个进程服务多个用户 |
| websockets | WebSocket 服务端 | 实时双向通信 |
| aiohttp | HTTP 服务端 | 异步原生的 Web 框架 |
| httpx | HTTP 客户端 | 现代异步 HTTP 客户端 |
| Pydantic v2 | 数据校验 | 自动格式检查、序列化 |
| OpenAI SDK | LLM 调用 | 官方 SDK、兼容性好 |
| tiktoken | Token 计数 | 精确计算 LLM 上下文长度 |
详细的选型分析见 技术调研文档
项目结构
miniOpenClaw/
├── docs/ # 顶层设计文档
│ ├── 01-requirements.md # 需求分析（先读这个！）
│ ├── 02-architecture.md # 架构设计
│ └── 03-tech-research.md # 技术调研
├── miniclaw/ # 核心库代码
│ ├── gateway/ # Day 1: Gateway 与消息协议
│ ├── channel/ # Day 2: Channel 适配器
│ ├── session/ # Day 3: 会话管理
│ ├── agent/ # Day 4: Agent 运行时
│ ├── tools/ # Day 5: 工具系统
│ ├── skills/ # Day 6: 技能系统
│ ├── memory/ # Day 7: 记忆与上下文
│ └── mcp/ # Day 8: MCP 协议
├── day1-gateway/ # 第 1 章：README + 示例 + 设计文档
├── day2-channel/ # 第 2 章
├── day3-session/ # 第 3 章
├── day4-agent/ # 第 4 章
├── day5-tools/ # 第 5 章
├── day6-skills/ # 第 6 章
├── day7-memory/ # 第 7 章
├── day8-mcp/ # 第 8 章
├── web/ # 可视化学习页面
│ ├── index.html # 总入口（章节导航）
│ ├── day1-gateway.html # Day 1 交互演示
│ ├── ... # Day 2-8 交互演示
│ ├── css/style.css # 公共样式
│ └── js/utils.js # 公共工具函数
├── pyproject.toml # 项目配置
├── requirements.txt # 依赖列表
└── .env.example # 环境变量模板快速开始
1. 安装依赖
bash
cd /data/workspace/learnNote/miniOpenClaw
pip install -r requirements.txt2. 配置环境变量
bash
cp .env.example .env
# 编辑 .env 文件，填入你的 OpenAI API Key
# 没有 Key 也没关系，部分示例提供了 Mock 模式3. 运行示例
每一章都有独立的示例可以运行：
bash
# Day 1: 启动 Gateway 服务
python day1-gateway/example/main.py
# Day 5: 体验工具系统
python day5-tools/example/main.py
# Day 4: 与 Agent 对话（需要 API Key，或使用内置 Mock 模式）
python day4-agent/example/main.py4. 运行测试
bash
# 运行所有测试
pytest --cov=miniclaw
# 运行特定章节的测试
pytest day1-gateway/ -v可视化学习页面
每个章节配备了交互式前端页面，无需 API Key 即可体验各模块的运行原理：
bash
cd web
python -m http.server 8000
# 浏览器访问 http://localhost:8000| 页面 | 交互内容 |
|---|---|
| Day 1 | 构造 GatewayMessage、EventBus 注册/触发、Router 路由分发 |
| Day 2 | 模拟 CLI / WebChat / Webhook 多渠道输入，观察统一消息转换 |
| Day 3 | 创建/查找会话、追加消息、TTL 过期清理、存储对比 |
| Day 4 | ReAct 循环可视化（简单问答 / 单工具 / 多工具三种场景） |
| Day 5 | 注册内置/自定义工具、生成 JSON Schema、模拟工具调用 |
| Day 6 | 加载技能目录、关键词匹配、手动/自动激活 |
| Day 7 | 短期记忆窗口裁剪、长期记忆保存/搜索、SystemPromptBuilder 分层构建 |
| Day 8 | MCP 握手流程、工具发现/调用、RemoteTool 代理 |
设计原则
- 不依赖 Agent 框架：不使用 LangChain、AutoGen 等，从零理解核心原理
- 全异步设计：统一使用
async/await，适应高并发场景 - 模块化解耦：各模块通过接口交互，可独立测试和替换
- 渐进式构建：每章在前一章基础上扩展，逐步构建完整系统
- 新手友好：每个概念都配有生活类比和逐行代码讲解
学完之后
完成 8 天学习后，你将：
- 理解 AI Agent 的完整架构（从消息接收到推理回复的每个环节）
- 掌握 Python asyncio 异步编程的实际应用
- 具备框架设计能力（抽象基类、注册模式、发布订阅等设计模式）
- 能独立扩展系统（写新工具、新技能、新渠道）
- 看懂 LangChain 等主流框架的源码（理解它们"在帮你做什么"）