build-your-own-openclaw：用 18 个可运行步骤拆开一个 AI Agent 的骨架
A step-by-step guide to build your own AI agent.
秒懂
- 它是什么？
- 这个仓库不是拿来直接用的框架，而是一套渐进式教程：从 00-chat-loop 到 17-memory，每一步都带 README 和可运行代码。它的价值在于把 agent 的各个部件拆开给你看，但正因为是教学产物，它并不适合当作生产依赖直接引入。
- 适合谁用？
- 如果你是想弄清 agent 内部到底由哪些部件组成、并愿意跟着代码一步步改的工程师，这个仓库值得按顺序走一遍，重点看 07-event-driven 的重构和 16-concurrency-control 的并发处理。如果你需要的是一个能直接装进生产系统的 agent 框架，它不是，因为每一步都是教学切片，没有发布版本，也没有稳定性承诺。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 70 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是「看不懂 agent 内部」这个问题
大多数 agent 框架的问题是，你调用一个接口，它返回一个结果，中间发生了什么被封装掉了。调试的时候你只能猜。这个仓库反过来走：它把 agent 拆成 18 个独立步骤，每一步只增加一个概念，并且每一步都是可以单独运行的代码库。README 里写的是「18 progressive steps」，每个步骤配一份 README.md 讲关键组件和设计决策，外加一份可运行的代码。
目标读者很明确：已经会写 Python、用过 LLM API、但想搞清楚「工具调用」「会话持久化」「事件驱动」这些词在代码里长什么样的工程师。仓库还给出了一个参考实现 pickle-bot，用来对照教程里的抽象。如果你只是想快速搭一个能用的机器人，这个仓库的路径太长了，它教的是构造方法，不是交付产品。
四个阶段对应四种能力边界
教程把 18 步分成四个阶段，这个划分本身透露了作者对 agent 复杂度的理解。
第一阶段是 00 到 06，目标是做出一个「能用的单 agent」：聊天循环、工具、技能、持久化、斜杠命令、上下文压缩、网络工具。这一阶段的边界是单进程、单会话，所有状态都在本地。
第二阶段是 07 到 10，把架构重构成事件驱动。README 的说法是「for scalability and multi-platform support」。07 把 agent 从 CLI 里拿出来，08 做配置热重载，09 接入 channels 让你从手机对话，10 加 WebSocket 做程序化交互。这一步是整条教程里改动最大的一次，前面写好的调用方式在这里会被打散成事件。
第三阶段是 11 到 15，处理自主性和多 agent：路由、cron heartbeat、多层 prompt、回发消息、agent 之间的派发。第四阶段只有 16 和 17 两步，16 是并发控制，17 是记忆。
值得注意的是后面阶段的命名方式。16 的标题是「Too many Pickle are running at the same time?」，17 是「Remember me!」。这种口语化标题说明作者把教程当成讲解而不是规范文档来写，好处是易读，代价是你不能指望从标题直接推断出技术范围。
技能系统的核心是一个约定文件名 SKILL.md
02-skills 这一步用 SKILL.md 来扩展 agent 的能力。从仓库结构能确认的是这个文件名的存在，以及它被放在「扩展 agent」这个语义下。
按常见做法推断，这应该是一个放在某个目录里、由 agent 在运行时读取的 Markdown 文件，内容描述某项技能的用途和调用方式。但必须说清楚：仅凭 README 无法确认加载路径、解析规则、是否支持多个 SKILL.md、以及技能和 01-tools 里的工具是什么关系。这是教程类仓库的典型问题，概念讲清楚了，实现细节要你自己去读那一步的代码。
如果你打算照搬这套机制，先去 02-skills 目录里确认三件事：SKILL.md 的查找目录是硬编码还是可配置，解析失败时是报错还是静默跳过，以及技能描述最终是以什么形式进入 prompt 的。第三点最关键，因为它直接决定 token 消耗和模型的实际行为。
上手只需要一条 cp 和一份 config.user.yaml
README 给出的启动流程很克制。第一步复制示例配置：
cp default_workspace/config.example.yaml default_workspace/config.user.yaml
第二步编辑 config.user.yaml 填入 API key。README 指向 LiteLLM providers 文档，说明底层走的是 LiteLLM 做多provider 适配，另有一份 PROVIDER_EXAMPLES.md 给出具体例子。第三步是「follow each steps, read and try it out」，也就是按目录顺序进入各步骤。
这里有几个从材料里能确认的约束。config.user.yaml 和 config.example.yaml 分离，意味着用户配置不会被覆盖，这是 08-config-hot-reload 能成立的前提。配置文件位于 default_workspace 目录下，说明 workspace 是一个有明确边界的目录概念，17-memory 很可能也落在同一层级。
无法确认的部分：每个步骤是否共用同一份 config.user.yaml，还是各自有独立的配置；依赖是 requirements.txt 还是 pyproject.toml；Python 版本要求。这些都要在进入具体步骤目录时自己看。
教学切片不是生产依赖，这一点必须讲清楚
仓库没有检索到任何 release。这不是疏漏，而是这类项目的定位使然：它的产物是 18 份互相独立的代码库，不是一份有版本号的库。
由此带来几个实际限制。第一，没有版本约束，你无法 pin 到一个稳定点，因为根本不存在版本。第二，18 个步骤之间的代码是重复的而不是继承的，你在 00 里改的东西不会自动出现在 17 里，想学完再合并成一个项目，需要自己动手做整合。第三，作为教程，它不会处理生产环境里那些不体面的问题：密钥轮换、限流退避、错误上报、审计日志。16-concurrency-control 处理的是「同时跑太多」这个具体场景，这不等于完整的并发治理。
最容易被误判的一点是第二阶段。07-event-driven 之后架构确实更适合扩展，但事件驱动本身引入了新的调试难度，事件丢失、顺序错乱、重放这些问题在教程规模下不会暴露，到了真实负载下才会。如果你的场景是单用户、低频调用，第二阶段的重构带来的复杂度可能超过收益，停在 06 反而是更理性的选择。
和直接读一个成熟框架的源码相比
一个自然的替代路径是直接读一个已经在用的 agent 框架的源码，比如 LangChain 或类似的编排库。两者的差别在信息组织方式上。
成熟框架的源码是围绕功能组织的，你要理解工具调用，得在多个模块之间跳转，因为抽象层是为复用设计的。这个仓库是围绕难度曲线组织的，00 到 06 每一步只引入一个新概念，代码量被刻意压到最小。对初学者来说，后者更容易建立心智模型。
但代价也在这里。成熟框架会处理边界情况，教程不会。你从 00-chat-loop 学到的是「一个 while 循环加一次 API 调用」，这个模型在遇到流式响应、超时重试、多轮工具调用嵌套时会立刻不够用。所以更合理的用法是两者结合：先用这个仓库建立骨架认知，再去读成熟框架的对应模块，看它们怎么补上那些边界。反过来，先读框架源码再看这个教程，收获会小很多，因为框架的抽象层会掩盖掉你想看的那个简单版本。
维护成本与 MIT 许可的实际含义
仓库采用 MIT 许可，最后推送时间在 2026 年 7 月。MIT 意味着你可以把代码拿去做任何事，包括闭源商用，只需要保留版权声明和许可文本。
但许可宽松不等于零成本。这个仓库的代码是教学素材，你把它复制进项目之后，维护责任完全转移到你这边。上游不会为你的分支修 bug，因为它本身不是库。另外，仓库里引用的 OpenClaw 是独立项目，教程只是教你构建它的轻量版本，两者的代码和许可需要分别确认，不能因为教程是 MIT 就假定 OpenClaw 也是。
升级成本这块，这个仓库基本不存在传统意义上的升级。没有 release，就没有从 1.0 升到 2.0 这件事。真正的成本在于跟随上游变化：如果 LiteLLM 改了 provider 接口，或者 02-skills 的 SKILL.md 约定发生调整，你需要自己判断哪些步骤受影响。对教学项目来说，这种漂移是常态。
如果你的团队打算基于这套结构做内部培训，MIT 允许你 fork 并改造，这是它最实际的用途。但改造之后请把版本管理补上，因为原仓库没有提供。
什么情况下该走完全部 18 步
判断标准其实很具体：你是否需要理解 11 到 15 这几个步骤背后的机制。
如果你的场景是单个用户对着一个 CLI 或一个聊天窗口说话，那么 00 到 06 已经覆盖了全部需要，后面的多 agent 路由、cron heartbeat、agent 派发都是多余的复杂度。硬走完只会让你在无关的抽象上花时间。
如果你的场景确实需要定时任务、需要多个 agent 分工、需要从手机或 WebSocket 接入，那么 07 到 15 就是必须理解的，因为这些问题在没有事件驱动架构的时候会变成一堆散落的定时器和状态判断。这时候按顺序走完，比直接抄一个成熟框架更容易看清每个决策的来龙去脉。
16 和 17 单独看。并发控制和记忆是任何规模下都会遇到的问题，即使你只做到 06，这两步里的思路也值得读，只是要自己判断能不能移植回单进程结构。
最后一件事：动手之前先跑通 00-chat-loop，确认你的 LiteLLM provider 配置在 config.user.yaml 里能正常工作。这一步不通，后面 17 步都是空转。
编辑结论
如果你是想弄清 agent 内部到底由哪些部件组成、并愿意跟着代码一步步改的工程师，这个仓库值得按顺序走一遍，重点看 07-event-driven 的重构和 16-concurrency-control 的并发处理。如果你需要的是一个能直接装进生产系统的 agent 框架，它不是，因为每一步都是教学切片，没有发布版本，也没有稳定性承诺。动手前先确认两件事：default_workspace/config.example.yaml 是否覆盖你要用的 LiteLLM provider，以及你能否接受 SKILL.md 这种约定式扩展带来的隐式行为。
社区笔记