拆解 OpenClaw 源码：1000 行代码复刻 AI Agent 核心架构

“没有记忆的 AI 只是函数映射，有记忆 + 主动唤醒的 AI，才是会演化的’生命系统'”

OpenClaw 简直是当下所有做 AI Agent 的创业公司应该参照的最佳实践。

Github源码: openclaw-mini

过去一年见过太多 Agent 项目，打开源码一看，核心就是个 while 循环：

没记忆，没上下文管理，没主动性。用户问一句答一句，关掉窗口什么都没了。本质还是个聊天框，只是多了几个工具调用。

OpenClaw 不一样。它的架构里藏着几个被忽视的设计：

• 长期记忆：跨会话的信息持久化
• 按需上下文：不是把所有东西塞给 LLM，而是分层加载
• 上下文压缩：对话太长时自动摘要，支持无限对话
• 主动唤醒：Agent 能自己检查任务、主动推进工作

这些加在一起，才让 Agent 从”工具”变成”劳动力”。

我把这套架构提炼成 1000 行左右的极简版本，叫 openclaw-mini。目的是让更多人能学到这些设计，应用到自己的项目里。

先说结论。

一个没有长期记忆的 AI，只是一个瞬间的函数映射：输入 → 输出，然后遗忘。

一个有记忆、有上下文管理、有主动唤醒能力的 AI，才是一个动态演化的系统。它能记住之前做过什么，能根据项目规范调整行为，能在你不说话的时候继续推进任务。

市面上 99% 的所谓智能体，本质还是被动触发的聊天框。”主动唤醒”才是从”工具”进化到”劳动力”的分水岭。不解决自主性，再多的技能封装也只是玩具。

OpenClaw 的设计解决了这些问题。下面逐个拆解。

问题：Agent 重启后如何恢复对话？

常见做法是 JSON 存会话。问题：写入要先读全量再写回；文件写一半崩了，整个文件废掉。

OpenClaw 方案：JSONL 格式，每行一条消息。

追加写入 O(1)，坏一行不影响其他行。 能实时监控。

设计启示：持久化不只是”存起来”。要考虑写入性能、容错、可观测。

问题：如何让 Agent 记住跨会话的信息？

很多项目的做法：存向量库，每次对话前检索一遍塞进 prompt。

OpenClaw 方案（）：

1. SQLite-vec 做向量语义搜索
2. BM25 做关键词搜索
3. 混合排序

更关键的是，记忆不是被动注入，而是工具化调用：

LLM 自己判断什么时候需要查记忆。不是每次都注入一堆可能无关的内容。

设计启示：记忆系统的关键不是”存了多少”，而是”什么时候用、怎么用”。被动注入会污染上下文，工具化调用让 LLM 按需获取。

问题：如何注入项目级规范而不污染每次对话？

很多项目的做法：把 README、代码库、所有配置全塞给 LLM。结果 token 爆炸，LLM 反而迷失在噪音里。

OpenClaw 方案：文件化的上下文结构，分层按需加载。

不是把所有文件都塞进去：

• 主 Agent 加载完整上下文
• 子代理只允许 + ，避免污染
• 超长文件按 head + tail 截断并加标记

设计启示：上下文管理的核心是减法而不是加法。塞得越多，LLM 越难聚焦。

工具返回结果经常很长。读一个大文件，几万字符。全塞进去会爆。

OpenClaw 的做法：soft trim，保留头尾各 1500 字符，中间截断。

LLM 通常能从头尾推断完整内容。

对话长了之后，历史消息会超出上下文窗口。怎么办？

OpenClaw 的做法：当历史消息超过 75% 上下文窗口时，触发摘要压缩。

摘要作为特殊消息插入对话开头：

这样 Agent 能继续之前的工作，支持无限长对话。

设计启示：上下文管理是三层机制——加载、裁剪、压缩。缺一不可。

问题：如何让用户自定义 Agent 能力？

传统做法：

加一个技能要改代码。

OpenClaw openclaw 方案：声明式定义，技能是一个 Markdown 文件。

技能文件放目录里，热加载，用户可以自己写。匹配到触发词后，Markdown 内容注入 system prompt。

设计启示：技能系统的核心是”声明式 + 热加载”。让用户能扩展，而不是改代码。

这是最被低估的设计。

问题：大多数 Agent 是被动的。用户不说话，它就不动。

OpenClaw 方案：Heartbeat 机制，让 Agent 能主动做事。

架构分两层：

Agent 可以：

• 定期检查 HEARTBEAT.md 里的待办
• 后台命令跑完主动汇报
• 在设定的时间窗口内主动推进任务

关键设计决策：

设计启示：主动唤醒是 Agent 和聊天框的分水岭。没有自主性，再多的技能封装也只是等人喂食的宠物。

这两个系统加在一起，构成了一个闭环反馈：

• Memory 让 Agent 能记住过去
• Context 让 Agent 能理解当前项目
• Session 让 Agent 能恢复对话
• Heartbeat 让 Agent 能主动行动

这才是一个完整的 Agent 架构。

代码全中文注释，每个设计决策都解释了为什么。

2026 年了，还在写套壳聊天框？

OpenClaw 的设计值得每个做 Agent 的人学习：

1. 会话持久化 – JSONL 格式，追加写入
2. 长期记忆 – 工具化调用，按需检索
3. 上下文管理 – 加载、裁剪、压缩三层机制
4. 技能扩展 – 声明式定义，用户可自定义
5. 主动唤醒 – 从工具到劳动力的分水岭

这些不是锦上添花，是 Agent 架构的基础设施。

把这套设计学会，去构建一个真正的 AI Agent，而不是基于 web2.0 思维的 copilot。