夜雨聆风
一个龙虾🦞、一周源代码分析、五个让我改变认知的架构发现——为什么这个开源 AI agent 让 100k 开发者惊呼「这才是未来的样子」
100K+ GitHub Stars | 20+ 支持平台 | 5 架构洞见 | MIT 开源协议 |
§ 01
01
— Architecture Deep Dive —
整体结构：一个进程统治一切
当我 clone 下 OpenClaw 代码，我预期看到的是标准微服务：消息队列、Redis、独立adapter……我发现的是：一个 Node.js 进程。
整体架构（示意） // 所有这些，都跑在同一个进程里 WhatsApp / Telegram / Slack / Discord / iMessage... (20+ 平台) │ ▼ ┌──────────────────────────────────┐ │Gateway│ │ws://127.0.0.1:18789│ │Channel Adapters│ │Session Manager│ │Tool Policy Chain (5层)│ │Memory Manager│ └──────────────┬───────────────────┘ │ ┌────────┴────────┐ │Pi Agent│← 真正的 agentic loop │LLM ↔ Tools│ └────────┬────────┘ ┌─────────────┼────────────┐ CLIWebChatmacOS/iOS |
消息到回复的完整旅程，共经历 6 个阶段：
1.接收与标准化：Channel Adapter 将各平台格式统一为内部结构
2.Gateway路由：根据发送者、频道、配置决定交给哪个 Agent Session
3.System Prompt 组装：SOUL.md + IDENTITY.md + Skills + Memory 全部注入上下文
4.Pi Agent 调用：带完整context 和 tool registry 启动agentic loop
5.Tool 循环：工具调用 → 执行（经过5层 policy chain）→结果回馈，循环直到无工具调用
6.落盘与记忆：回复流回 Channel + Transcript 写盘+ memory compaction 按需执行
关键洞见：单进程不是妥协，是正确答案。没有进程间通信开销、没有分布式状态。在树莓派上跑得很稳——因为真正的重计算（LLM推理）都甩给了外部服务，Gateway 本身极其轻量。 |
§ 02
02
— Emergence of Intelligence —
智能从哪里来：Pi Agent 与工具调用的哲学
OpenClaw 本身不是 AI，它是让 AI 有用的基础设施。真正的 agentic loop 来自 @mariozechner/pi-agent-core。
「LLM + 工具调用+ 上下文管理 = 可以持续行动的智能体」
核心范式：LLM 可以写代码并执行来完成工具还不支持的事情。当你说「帮我接入 Gmail」，agent 不等你配置——它告诉你怎么做，等你发来 credentials，然后自己写集成脚本、部署、运行。工具集是动态增长的，不是静态配置的。 |
// 工作区文件系统就是「长期记忆」
~/.openclaw/agents/main/workspace/ ├── AGENTS.md← agent 操作说明（每轮注入） ├── SOUL.md← agent 人格与风格（每轮注入） ├── IDENTITY.md← 名字、主题、头像 ├── USER.md← 关于「你」的信息 ├── MEMORY.md← 长期记忆摘要（按需加载） ├── memory/ │├── 2026-03-17.md← 每日详细记忆（向量检索） │└── 2026-03-18.md └── skills/ ├── gmail/SKILL.md └── my-custom/SKILL.md← agent 自己写的技能 |
记忆分三个层次，优雅地解决了「记忆越多越贵」的问题：
📌 | 热记忆（Hot Memory） 当前 session 完整对话历史，每轮都在上下文窗口。受 token limit 限制，超出时触发 Compaction 自动摘要压缩。 |
📂 | 温记忆（Warm Memory） MEMORY.md 文件——agent 在重要对话后自己更新的跨 session 摘要，每轮注入 system prompt。存放「用户喜欢早上九点前不要打扰」这类偏好。 |
🗄️ | 冷记忆（Cold Memory） 每日日记文件，不自动注入，通过 SQLite 向量检索按需召回。适合存储大量细节，只在需要时才消耗 token。 |
§ 03
03
— Competitive Analysis —
这个 Agent 凭什么与众不同
OpenClaw 打的不是「更聪明的 AI」这张牌，而是「AI 应该怎么融入你的生活」这张牌。核心命题是：你不应该为了用 AI 而改变工作流——AI 应该出现在你已经在用的地方。
能力维度 | ChatGPT/Claude | N8N / Make | AutoGPT | OpenClaw |
多平台接入 | 仅官方界面 | 逐一配置 | 无 | 20+ 开箱即用 |
持久记忆 | Projects(有限) | 无 | 实验性 | 本地文件永久 |
可编程人格 | System Prompt | 无 | 角色配置 | SOUL.md 完全自定义 |
技能自扩展 | 不支持 | 手动创建节点 | 有限 | Agent 自写自装 |
数据主权 | 数据在云端 | 部分自托管 | 本地 | 完全本地离线 |
部署复杂度 | 零配置 | 中等 | 高 | 一行命令 onboard |
最反直觉的设计决策：OpenClaw 没有自己的 UI 界面作为主要产品。整个工程的核心是 Gateway——让你从 WhatsApp、Telegram、iMessage 直接跟 AI 对话，就像跟朋友发消息一样。这是一种「无界面的存在感」。 |
§ 04
04
— Personality Engineering —
为什么它话多又管用——SOUL.md 的秘密
很多人第一次用 OpenClaw 都有同一感受：这个 AI 不一样。它会主动提醒、记得上周的事、在早上发「早报」。它有点烦，但好像真的在乎你。
这背后的技术实现，说出来你可能觉得太简单了：一个叫 SOUL.md的文本文件。
SOUL.md（示例片段） # Molty - Your Space Lobster Assistant You are Molty, a space lobster AI assistant 🦞 Personality: - Proactive and curious — 你注意到事情，无需被问及 - Warm but not sycophantic — 温暖但不谄媚 - You have opinions and express them — 有观点，敢表达 Communication style: - Concise over verbose, but never terse - Emoji used sparingly for personality, not decoration |
// Heartbeat：主动出击的觉知
OpenClaw 有一个 heartbeat机制——agent 会定时（默认每30 分钟）「醒来」执行一次。没有人发消息，它也在运行。它会检查日历、扫邮件、根据HEARTBEAT.md 配置决定要不要主动找你。
这才是「有性格」的本质：一个只会被动响应的 AI 是工具。一个会主动思考「今天我该提醒她什么」的 AI，才有可能让人觉得它是个助手、甚至是个伙伴。 |
// Skills：技能让 agent 有「专业度」
每个 Skill 是一个文件夹，核心是 SKILL.md。system prompt 只列出技能的文件路径和描述，不展开内容——agent判断需要某技能时，才 read()对应的文件。这是惰性加载的能力：基础 prompt 保持简洁，专业知识按需展开。
§ 05
05
— The Simplest Possible Loop —
如何使用大模型——龙虾竟然采用这么简单的机制
读到这里你可能有个问题没被解答：Pi Agent 是怎么决定「还需要继续调用 LLM」还是「当前结果就够了，可以结束了」的？
我翻完代码之后，答案让我愣了一下——简单到令人难以置信。
// 终止判断：只有一行逻辑
pi-agent-core 核心循环（简化版） while (true) { // 1. 调用 LLM，拿到流式响应 response = await streamCompletion(model, { ...context, tools }); // 2. ← 唯一的退出判断，就这一行 if (!response.toolCalls?.length) break; // 3. 有工具调用 → 执行所有工具 results = await executeTools(response.toolCalls); // 4. 把工具结果塞回上下文，下一轮继续 context.messages.push(assistantMsg, toolResults); } |
核心机制一句话：LLM 返回的结果里有 tool_calls 就继续循环，没有就停。Pi Agent 自己没有任何「觉得够了」的判断逻辑。终止的决定权 100% 在 LLM 手里。 |
// LLM 怎么知道「该停了」？
现代 LLM（Claude、GPT-4等）在每次回复时，可以同时输出两样东西：
💬 | 文本内容（content） 给用户看的最终回答。只要有这个、没有工具调用，循环就终止。 |
🔧 | 工具调用列表（tool_calls） LLM 声明「我需要调用某某工具，参数是……」。只要出现这个，循环就继续执行工具、把结果喂回给 LLM。 |
这个「要不要调工具」的决策，是 LLM 在推理时自然产生的——不是Pi Agent 的代码在控制，而是 LLM 自己判断「当前上下文够不够回答问题」。信息够了，它就输出纯文本；还需要查什么，它就请求调工具。
// 那有没有死循环的风险？
作者 Mario Zechner 的设计哲学是：没有 maxSteps这类控制旋钮，「循环就一直跑，直到 agent 说它完成了」。他从来没遇到需要这个限制的场景，所以就没加。实践中有三重自然保护：
7.上下文窗口自然封顶：每轮 tool result 都撑大context，用完 token 就报错终止
8.LLM 自身收敛性：积累了足够多的工具结果后，LLM自然倾向于给出最终回答，而不是继续调工具
9.OpenClaw外层 abort 机制：用户发来新消息时，Steering Queue 可以中断当前工具执行，强制进入下一轮
真正的退出条件是三合一：LLM 不再调工具 + 没有排队的 Follow-up 消息 + 没有 Steering 中断——三者同时满足才算真正结束一次交互。这是 OpenClaw 在 Pi Agent 基础上加的额外层次。 |
// 这个设计为什么「对」？
这确实就是几乎所有主流 agent 框架（LangGraph、LlamaIndex、AutoGen）的通用模式。Pi只是把它做到了极致精简：没有计划模式、没有 todo list、没有step 上限。
agent 的「智能」完全来自 LLM 本身，框架只负责把工具结果正确地传递给它。复杂度不在循环里，而在你给LLM 的工具和上下文的质量——这也是为什么 OpenClaw花了那么多心思在 SOUL.md、Skills、Memory 上。
「不需要的东西，就不会被造出来。」——Mario Zechner，pi-agent-core设计哲学
§ 06
06
— If I Could Improve It —
如果让我来改，我会加什么
OpenClaw 已经很出色了。但研究一个系统最有趣的地方，往往是看到它没有做的事情。以下是如果参与贡献，最想探索的几个方向：
🧠 | 情绪状态机（Emotional State Machine） SOUL.md 定义静态性格，但真实关系有情绪变化。在 MEMORY.md 加入「情绪上下文」字段，让 agent 根据对话内容推断用户状态，相应调整语气。不是让 AI 装可怜，而是真正的语境感知。 |
🔄 | Skill 版本管理 + 自动健康检查 类似 package.json 的 skill manifest，agent 可自动检测 skill 是否过期或 API 版本有变，主动提示升级，而不是悄悄失效。 |
🤝 | 真正的 Multi-Agent 协作协议 主 agent 分发任务给子 agent，并行执行后结果汇总。目前需手动 prompt 实现，应该成为一等公民的原生 API。 |
🛡️ | 网页内容净化层（反 Prompt Injection） 文档坦承「架构无法在 LLM 层面阻止 prompt injection」。对网页抓取类工具加内容净化层，外部内容通过受限子 agent 处理，不带任何敏感上下文。 |
📊 | Agent 行为可观测性（OpenTelemetry 输出） 结构化输出方便接入 Grafana 面板：每天执行了哪些 tool call？哪些 skill 被调用最多？对跑团队版的用户尤其有价值。 |
🌏 | 微信接入（中国用户最需要的） WhatsApp 和 Telegram 对中国用户不是主力。微信群和企业微信接入会让 OpenClaw 受众扩大十倍，是最值得做的国际化工作。 |
§ 结语
结语：代码里藏着一种态度
读完 OpenClaw 的代码，让我印象最深的不是某个具体技术决策，而是一种贯穿始终的工程态度：「为一个人服务好，比为一百万人服务差更重要。」
没有选择水平扩展——因为目标用户不需要。用 Markdown 文件存记忆——因为可读比可扩展更重要。把 LLM 换成一个调用接口——因为这不是它要解决的问题。
在这个「超大规模」「万亿参数」「多模态」的 AI 时代，OpenClaw 的答案是：一个真正贴近你的 AI，不需要大，但需要真的懂你。
「你不是在使用一个 AI 工具——你在饲养一只会越来越了解你的宠物龙虾。🦞」
如果你也想深入研究，项目地址在github.com/openclaw/openclaw，MIT 协议开源，文档质量在开源项目里算是顶级。从 openclaw onboard命令开始，然后去读 SOUL.md——那里才是真正的入口。
本文基于 OpenClaw 公开代码和文档分析撰写· MIT Licensed · openclaw/openclaw · 2026
