OpenClaw 源码架构设计剖析:一只＂龙虾＂如何撑起 24 万 Star 的 AI Agent 帝国

大家好，我是锋哥。

“当别人还在讨论 AI Agent 能不能用的时候，OpenClaw 已经悄悄住进了你的 WhatsApp、Telegram、Discord……它就像一个全平台在线的超级管家，而你甚至不需要给它发工资。”

一、开篇：这只龙虾到底是何方神圣？
二、架构全景图：五脏六腑一览无余
三、Gateway-First：把”大门”修得比”大脑”还重要
四、消息路由管道：一条消息的奇幻漂流
五、五大平面架构：分而治之的艺术
六、插件系统：乐高式的无限可能
七、Channel Adapter 模式：一个接口统一天下
八、记忆架构：让 AI 不再是”金鱼脑”
九、工具执行引擎：Agent 的瑞士军刀
十、代码组织与工程实践
十一、设计哲学启示录
十二、总结

一、开篇：这只龙虾到底是何方神圣？

如果你还没听过 OpenClaw，那你可能错过了 2025-2026 年开源世界最耀眼的明星之一。

OpenClaw 是一个自托管（self-hosted）、本地优先（local-first）的个人 AI 助手平台。它的核心使命很简单却又很疯狂：让你的 AI 助手同时”活”在 18+ 个聊天平台上——WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Teams、Matrix……你能想到的，它基本都支持。

来看一组让人窒息的数据：

指标	数值
GitHub Stars	241,000+ ⭐
代码文件数	4,885 个
代码 Token 数	680 万
支持的聊天平台	18+ 个
内置工具	60+ 个
插件扩展	38+ 个
主要语言	TypeScript (90%)

它的前身叫 Clawdbot（短暂改名过 Moltbot），最终定名 OpenClaw——一只霸气的开源龙虾。

🦞 冷知识：为什么叫”Claw”（爪子）？因为这个项目像龙虾的钳子一样，牢牢”夹住”了所有聊天平台，让你无处可逃（不是）。

二、架构全景图：五脏六腑一览无余

在深入每个模块之前，我们先来一张”全身 CT 扫描”，看看 OpenClaw 的整体架构长什么样：

是不是有种看到”星际战舰控制面板”的感觉？别慌，我们一层一层剥洋葱。

三、Gateway-First：把”大门”修得比”大脑”还重要

传统思路 vs OpenClaw 思路

大多数 AI Agent 框架的设计思路是这样的：

“先有 AI 大脑，再包一层 API，最后套几个聊天平台适配器。”

而 OpenClaw 完全反过来：

“先修一座坚不可摧的大门（Gateway），AI 大脑只是门里面的一个住户（Plugin）。”

这就是所谓的 Gateway-First Architecture（网关优先架构）。

为什么这么设计？

打个比方：传统架构就像一个天才科学家坐在实验室里，你想找他聊天得自己翻山越岭走到他面前。而 OpenClaw 的架构更像是在城市中心建了一个超级邮局，不管你是发邮件、发微信、发电报还是放信鸽，所有消息都汇聚到这个邮局，然后统一转交给科学家。

这样做有三个核心好处：

Presence（存在感）成为一等公民：Agent 不再是被动等待调用的工具，而是一个持续在线、随时可达的”数字人格”
平台无关性：新增一个聊天平台，只需要写一个 Channel Plugin，不需要动核心代码
故障隔离：某个平台出问题不会影响其他平台，就像邮局的一个窗口排队太长，不影响隔壁窗口

核心代码入口

Gateway 的核心启动逻辑在 packages/gateway 中，它本质上是一个跑在 127.0.0.1:18789 上的 Node.js 进程，通过 WebSocket 和 HTTP 双协议对外服务。整个 Gateway 被设计为一个可以用 launchd（macOS）或 systemd（Linux）管理的守护进程——7×24 小时不打烊。

四、消息路由管道：一条消息的奇幻漂流

当你在 Telegram 上给 AI 助手发了一条”帮我查一下明天的天气”，这条消息会经历一段怎样的旅程呢？

消息生命周期

关键机制：Lane/Queue 并发模型

这里有一个特别精妙的设计：sessionKey + Lane + Queue 并发控制系统。

简单说就是：同一个用户的消息排队串行处理（避免上下文混乱），不同用户的消息并行处理（提高吞吐量）。这就像银行的叫号系统——你自己的业务得一件一件办，但银行不会因为你在办业务就让别人都等着。

Run/Attempt 重试机制

每个消息处理被包装成一个 Run，Run 内部可以包含多个 Attempt（尝试）。如果当前 LLM 提供商超时或出错，系统可以自动切换到备选提供商重试，对用户完全透明。

五、五大平面架构：分而治之的艺术

OpenClaw 的架构师把整个系统切分成了五个清晰的平面（Surface），每个平面各司其职，互不干扰：

为什么要分五个平面？

这个设计的核心思想可以用一句话概括：

“如果这些平面保持独立，那么事故就是可修补的。”

想象一下，如果你的 AI 助手的工具执行模块出了 Bug（比如文件操作异常），在传统的单体架构中，可能整个系统都要重启。而在 OpenClaw 的五平面架构中，工具平面（Surface B）的问题不会影响消息路由（Surface A），更不会影响消息投递（Surface E）——用户可能只是暂时用不了某个工具，但聊天功能完全正常。

这就像城市的基础设施：供电系统坏了不影响供水，供水系统检修不影响交通。每个系统独立运行，独立维护。

六、插件系统：乐高式的无限可能

OpenClaw 的插件系统是整个项目最让人拍案叫绝的设计之一。它采用了 基于能力（Capability-based） 的插件模型。

插件分类

插件生命周期

传统的插件系统通常采用”钩子（Hook）”模式——给你几十个生命周期钩子，你爱挂哪挂哪。OpenClaw 不这么玩。它让插件注册自己的能力类型，系统根据需要动态调度。

这就像招聘：传统方式是”来了先坐下，等我叫你的时候你再动”（被动钩子）。OpenClaw 的方式是”告诉我你会什么，需要的时候我来找你”（能力声明）。

插件目录结构

src/├── plugin-sdk/          # 公共插件契约（Plugin API）├── plugins/             # 插件发现、验证、加载、注册│   ├── loader.ts        # 插件加载器│   ├── registry.ts      # 插件注册表│   └── validator.ts     # Manifest 校验器└── channels/            # 内置通道实现    ├── whatsapp/    ├── telegram/    ├── discord/    ├── slack/    └── ...

核心保持精简，可选功能全部以插件形式发布（通常是 npm 包），这使得 OpenClaw 的核心代码量控制在合理范围内，同时拥有无限的扩展能力。

七、Channel Adapter 模式：一个接口统一天下

18 个聊天平台，各有各的 API 风格、消息格式、认证方式……如何用一套代码优雅地搞定？

答案是 Channel Adapter Pattern（通道适配器模式）。

适配器四大职责

一条消息的”翻译”过程

假设 Agent 生成了一段 Markdown 格式的回复：

**明天天气预报**- 🌤️ 北京：晴，25°C- 🌧️ 上海：小雨，18°C

这段内容到达 Channel Adapter 后，会根据目标平台进行”本地化翻译”：

平台	转换结果
WhatsApp	`明天天气预报\n• 🌤️ 北京：晴，25°C\n• 🌧️ 上海：小雨，18°C`
Discord	转换为 Embed 卡片，带有标题和字段
Telegram	`<b>明天天气预报</b>\n• 🌤️ 北京：晴，25°C\n• 🌧️ 上海：小雨，18°C`
Slack	转换为 Block Kit 格式

这种设计的美妙之处在于：Agent 只需要说”人话”（Markdown），怎么翻译成各平台的”方言”，是 Channel Adapter 的事情。 Agent 本身完全不需要知道自己在和哪个平台对话。

八、记忆架构：让 AI 不再是”金鱼脑”

AI Agent 最大的痛点之一就是记忆。你今天跟它聊了半天，明天它就全忘了——活脱脱一条金鱼。

OpenClaw 设计了一套非常务实的三层记忆架构来解决这个问题：

三层记忆金字塔

设计亮点：文件为王，数据库为仆

这是 OpenClaw 记忆系统最精妙的设计哲学：

“数据库是为文件服务的——文件才是正本。”

所有的记忆数据以 Markdown 文件 的形式存储：

~/.openclaw/├── MEMORY.md              # 核心记忆（精选事实）└── memory/    ├── 2026-04-10.md       # 每日对话日志    ├── 2026-04-11.md    ├── 2026-04-12.md    └── 2026-04-13.md

为什么不直接用数据库？ 因为 Markdown 文件有三个数据库无法比拟的优势：

人类可读：打开文件就能看到 AI 记住了什么，不需要写 SQL
版本控制：直接用 Git 管理，记忆的每次变更都有据可查
可调试性：出了问题？grep 一下就行，不需要连数据库

SQLite 和向量索引只是为了加速检索——就像图书馆的索引卡片，真正的知识在书里，卡片只是帮你更快找到对的那本书。

混合检索策略

检索记忆时，OpenClaw 同时使用两种搜索方式，然后加权融合：

向量搜索（70%权重）：通过 Embedding 计算语义相似度，擅长理解”意思相近”的查询
关键词搜索（30%权重）：使用 BM25 算法做精确匹配，擅长找特定名称、日期等

为什么不只用一种？因为单纯的向量搜索可能在精确查询时翻车（”我的 API Key 是什么？”），而单纯的关键词搜索理解不了语义（”上次我们讨论的那个方案”）。两者结合，才能覆盖各种场景。

九、工具执行引擎：Agent 的瑞士军刀

OpenClaw 内置了 60+ 个工具，这些工具是 Agent 与现实世界交互的桥梁。

工具执行流程

工具策略引擎（Tool Policy Engine）

这是安全层面最重要的设计。OpenClaw 不会让 Agent 为所欲为——每个工具调用都要经过策略引擎的审查：

Gateway 将所有入站消息视为不可信输入，对于未知联系人默认进入配对模式（Pairing Mode），需要 Gateway 所有者确认才能建立信任关系。这就像你家的智能门锁——陌生人敲门，门锁会先给你发通知，由你决定开不开门。

十、代码组织与工程实践

Monorepo 结构

OpenClaw 使用 pnpm monorepo 管理代码，主要包的组织方式如下：

技术栈一览

技术	用途
TypeScript	核心逻辑、Gateway、CLI、插件
Swift	macOS/iOS 原生客户端
Kotlin	Android 原生客户端
pnpm	包管理与 Monorepo
tsdown	TypeScript 打包
SQLite	本地向量索引与缓存
Node.js ≥22	运行时环境

测试策略

OpenClaw 采用测试文件就近放置的策略——测试文件 *.test.ts 直接放在对应源文件旁边，而不是统一放在 __tests__ 目录。这样做的好处是：看到一个模块就能立刻找到它的测试，不需要在项目里来回跳转。

十一、设计哲学启示录

读完 OpenClaw 的源码，我总结了几条值得所有开发者学习的设计哲学：

1. “存在感” > “智能”

Presence beats Intelligence.

传统的 AI 框架拼命追求模型有多聪明、推理有多强。OpenClaw 的观点是：你再聪明，用户找不到你有什么用？

先解决”随时随地可达”的问题，再去优化”回答有多好”的问题。这个优先级排序看似简单，实际上颠覆了整个 Agent 框架的设计范式。

2. 网关即产品，AI 是插件

The Gateway is the product. The AI brain is a plugin.

这个理念太反直觉了。但仔细想想，确实如此——用户体验的好坏，80% 取决于消息能不能及时到达、多平台能不能无缝切换、会话能不能持续保持。这些都是 Gateway 的活儿。

3. 文件优先，数据库为仆

Files are canonical. Databases serve the files.

在这个人人追求数据库、向量库、图数据库的时代，OpenClaw 选择用最朴素的 Markdown 文件作为记忆的”真相之源”。不是因为技术落后，而是因为可调试性和透明性在生产环境中的价值被严重低估了。

4. 分面即可修

If surfaces stay distinct, incidents become patchable.

五大平面的分离不是为了架构图好看，而是为了出事故时能快速定位和修复。好的架构不是不出问题的架构，而是出了问题能迅速搞定的架构。

5. 适配器吃掉复杂性

Channel Adapters eat complexity for breakfast.

18 个平台的差异性被完美封装在各自的 Adapter 里，核心代码完全不需要知道 WhatsApp 和 Discord 的区别。这是关注点分离（Separation of Concerns） 的教科书级实践。

十二、总结

OpenClaw 的成功不是因为它用了多前沿的技术，而是因为它在正确的地方做了正确的设计决策：

🎯 先解决分发（Distribution），再解决智能（Intelligence）
🧩 用插件化消灭复杂性，而不是用代码堆砌功能
📝 用人类可读的文件格式降低系统的认知门槛
🏗️ 用清晰的平面分离确保系统的可维护性

如果你正在设计自己的 AI Agent 系统，OpenClaw 的架构绝对值得深入研究。它不会教你怎么写更聪明的 Prompt，但它会教你怎么建一座经得起时间考验的大厦。

毕竟，一只龙虾能扛起 24 万颗星星，靠的不是蛮力，而是一副好骨架。🦞

最近锋哥录制了一些AI编程视频教程

高清视频+源码+领取。

扫描下方公众号【小锋学AI 】回复：888，

可获取下载链接

👇👇👇

👆长按上方二维码 2 秒

回复「888」即可获取