从零到生产级AI智能体:build-your-own-openclaw 18步完整教程全解析
从零到生产级AI智能体:build-your-own-openclaw 18步完整教程全解析
build-your-own-openclaw 是一个开源的 AI 智能体(AI Agent)教程项目,手把手教你从零搭建自己的生产级 AI 智能体。它把一个完整的智能体拆成 18 个循序渐进的步骤:从最简单的聊天循环开始,逐步添加工具调用、技能系统、对话持久化、事件驱动架构、多智能体路由、定时任务,直到并发控制与长期记忆。每一步都配有可直接运行的代码和详尽的设计讲解,是新手学习 AI Agent 架构的完整路线图。
项目概览:18 步构建你的 AI 智能体
很多人以为"AI 智能体 = 套一层 LLM API 调用",其实一个真正能用的智能体需要:会用工具、记得住上下文、能上网查资料、能在手机聊天软件上收发消息、会按定时任务自主工作,还要支持多智能体协作。这个教程项目用一个叫 Pickle 的小橘宠 🐾 作为智能体吉祥物,带你在 18 步中把这些能力逐个补齐。
整个项目采用"每步一个独立目录"的结构,每个目录里都有三样东西:
- 📘
README.md/README.zh.md—— 讲解关键组件与设计决策 - 🐍
src/mybot/—— 可直接运行的完整代码 - 📊
*.svg—— 该步骤的架构示意图
教程路线图:4 个阶段,18 个步骤
第一阶段:能干的单智能体(步骤 0-6)
让智能体学会聊天、用工具、加载技能、保存对话、上网搜索。
| 步骤 | 目录 | 学到什么 |
|---|---|---|
| 00 | 00-chat-loop/ | 一切的起点:用户输入 → LLM 响应 → 更新会话历史 |
| 01 | 01-tools/ | 给智能体装上"手":工具注册表与函数调用 |
| 02 | 02-skills/ | 用 SKILL.md 按需延迟加载扩展能力 |
| 03 | 03-persistence/ | 把对话存下来,重启后恢复会话 |
| 04 | 04-slash-commands/ | /new、/agents 等斜杠命令直接控制会话 |
| 05 | 05-compaction/ | 上下文爆了怎么办?自动压缩历史,滚动新会话 |
| 06 | 06-web-tools/ | 联网搜索 + 网页阅读,智能体想看更大的世界 |
核心机制举例:步骤 05 的 context_guard.py 用 Token 估算判断上下文是否超阈值,先截断过大的工具结果,再总结旧消息、滚动到新会话——这正是生产级智能体"永不失忆、永不爆窗"的关键。
第二阶段:事件驱动架构(步骤 7-10)
从"命令行里的玩具"升级为"可以常驻的服务"。
| 步骤 | 目录 | 学到什么 |
|---|---|---|
| 07 | 07-event-driven/ | 引入 EventBus 事件总线,解耦消息源与智能体执行 |
| 08 | 08-config-hot-reload/ | 配置热重载:改配置不用重启服务 |
| 09 | 09-channels/ | 接入 Telegram / Discord,在手机上和智能体对话 |
| 10 | 10-websocket/ | WebSocket 实时接口,以编程方式与智能体交互 |
这是全套教程里最关键的一步。eventbus.py 实现了经典的发布/订阅模型:InboundEvent(进来的消息)和 OutboundEvent(出去的回复)在 events.py 中定义,AgentWorker 订阅入站事件、执行智能体会话后发出出站事件。有了这条"事件流水线",后续每一步都只是往流水线上加新的"工人"(Worker)。
第三阶段:自主与多智能体(步骤 11-15)
让智能体"自己干活",并学会分工协作。
| 步骤 | 目录 | 学到什么 |
|---|---|---|
| 11 | 11-multi-agent-routing/ | 路由表把消息源匹配到最合适的智能体 |
| 12 | 12-cron-heartbeat/ | Cron 定时任务:智能体在你睡觉时工作 |
| 13 | 13-multi-layer-prompts/ | 多层提示词构建,注入更丰富的上下文 |
| 14 | 14-post-message-back/ | 智能体主动给你发消息,而不是被动等你问 |
| 15 | 15-agent-dispatch/ | 智能体调度:把子任务派给别的智能体 |
几个亮点:
- 🔀 分层路由:routing.py 中的
RoutingTable按"精确匹配 > 正则 > 通配符"的优先级解析消息源,匹配不到就回落到默认智能体,用/route、/bindings命令即可管理。 - ⏰ 定时任务:cron_worker.py 每分钟扫描一次
CRON.md任务定义,到点就向事件总线发布DispatchEvent。比如你对它说"每天早上发我一张猫猫图",它就自己排好了班。 - 🤝 智能体调度:subagent_tool.py 动态生成
subagent_dispatch工具,主智能体可以像"派活给同事"一样把任务丢给专业智能体。
第四阶段:生产就绪(步骤 16-17)
最后两步补齐生产级系统的两块短板:并发与记忆。
- 🚦 并发控制(16-concurrency-control/):每个智能体可配置
max_concurrency,用信号量限制同时运行的实例数,防止消息洪峰把资源打爆。 - 🧠 长期记忆(17-memory/):引入专职的 cookie 记忆智能体(定义见 cookie/AGENT.md),跨会话记住你的偏好——"记住我叫 Zane",下次新开对话它依然认识你。
快速上手:3 步跑起来
1. 克隆教程仓库
git clone https://gitcode.com/gh_mirrors/bu/build-your-own-openclaw.git
2. 配置 LLM 提供商(需要 Python 3.11+ 和 uv)
cp default_workspace/config.example.yaml default_workspace/config.user.yaml
# 编辑 config.user.yaml 填入你的 API 密钥
配置模板见 config.example.yaml,支持 OpenAI、Anthropic 等任意 LiteLLM 兼容的提供商,各提供商的完整配置示例参考 PROVIDER_EXAMPLES.md。
3. 进入步骤目录运行
cd 00-chat-loop
uv run my-bot chat
# You: Hello, who is this?
# Pickle: Meow! I'm Pickle, your friendly cat assistant. 🐾
之后每完成一步,只需 cd 到下一个步骤目录重复运行即可。建议的工作方式:先读该步骤的 README.zh.md,再对照 src/mybot/ 下的源码跑一遍,最后看看 *.svg 架构图验证自己的理解。
值得深挖的几个源码模块
| 模块路径 | 作用 |
|---|---|
| core/eventbus.py | 事件总线:发布/订阅 + 出站事件持久化与故障恢复 |
| core/routing.py | 多智能体路由表,正则匹配 + 分层优先级 |
| core/context_guard.py | 上下文守护:Token 估算、截断与压缩策略 |
| server/cron_worker.py | 定时任务调度器 |
| server/delivery_worker.py | 出站消息投递,确保消息不丢 |
| tools/subagent_tool.py | 智能体间任务调度工具 |
另外,default_workspace/ 下是智能体的"工作区":AGENTS.md 描述可用智能体与调度规则,agents/pickle/ 和 agents/cookie/ 分别是主智能体和记忆智能体的定义,skills/ 里则放着 cron-ops、skill-creator 两个开箱即用的技能。
总结:谁适合这份 AI 智能体教程?
✅ 想系统理解 AI Agent 架构的开发者——18 步覆盖从聊天循环到多智能体协作的完整链路 ✅ 已经会调 LLM API,但想知道工具调用、记忆、路由怎么设计的工程师 ✅ 想从零造一个属于自己的助手(比如接上 Telegram 的宠物猫助手)的动手派
整个教程的设计哲学很清晰:每一步只加一个新概念,且代码量保持精简。学完 18 步,你不仅拥有了一个可运行的生产级 AI 智能体,更重要的是理解了"一个智能体为什么长这样"——这比任何 API 文档都值钱。
