夜雨聆风我花了一个下午把它的仓库扒了一遍,核心 TypeScript 代码 53 万行,插件 27 万行,加起来 80 万行。这篇文章聊聊它的总体架构,以及我看完之后的几个判断。
先说结论:网关只是控制面,产品才是本体
OpenClaw 在 README 里写了一句很关键的话:The Gateway is just the control plane — the product is the assistant.
这句话基本就是理解整个架构的钥匙。它把整个系统拆成了两层:
上层是「渠道(Channel)」,负责对接各种聊天软件,把消息收进来、发出去 下层是「网关(Gateway)」,一个常驻的本地进程,负责路由、会话管理、调用 AI、执行工具
渠道是可插拔的,网关是唯一的。你加一个新的聊天平台,只需要写一个新的渠道插件,网关本身的逻辑一行都不用动。
这个思路和 VS Code 的「核心 + 扩展」很像,但 OpenClaw 把这件事做得更彻底。
整体架构:四层结构
我把整个系统的数据流画了张图,从用户在微信上发一条消息,到 AI 回复回来,中间经过四层:
第一层:渠道层(Channel Plugins)
这是最外面的一层,对应 extensions/ 目录下的 88 个插件。没错,88 个。不过别被吓到,里面真正是聊天渠道的大概二十多个,剩下的全是模型供应商(OpenAI、Anthropic、DeepSeek、月之暗面、xAI、Ollama……)、搜索、语音、图像生成这类能力插件。
渠道插件干的事很纯粹:
连上聊天平台(扫码登录、Bot Token、Webhook 都行) 把平台的消息格式转成统一结构 把 AI 的回复转回平台格式发出去
每个渠道插件是一个独立的 npm 包,比如 @openclaw/telegram、@openclaw/discord,运行时才被网关加载进来。
第二层:网关核心(Gateway Core)
这是整个系统的心脏,一个 WebSocket 服务,默认监听 127.0.0.1:18789。它对外提供三种能力:
渠道消息的收发中转 控制面(Control UI),也就是那个网页版的管理后台 给客户端(macOS/iOS/Android App、CLI TUI)提供 WebSocket 连接
注意默认只绑回环地址,不暴露到公网。要远程访问的话,官方推荐 SSH 隧道或者 Tailscale,安全意识是到位的。
第三层:路由与会话(Routing & Sessions)
消息进来之后,要先想清楚「这条消息该交给哪个 AI 会话处理」。
OpenClaw 的会话是按「账号 × 渠道 × 聊天窗口 × 线程」来划分的,代码在 src/routing/ 和 src/channels/session.ts。简单说:
你在微信上私聊 AI,是一个会话 你在同一个微信的某个群里 @ AI,是另一个独立会话 群里的不同讨论串(Thread)还可以再拆
这样做的好处是上下文互不污染。群聊里 A 问的事不会串到 B 的私聊里去。
第四层:智能体运行时(Agent Runtime)
真正干活的地方,代码在 src/agents/,也是整个仓库最大的一个目录,527 个 TypeScript 文件,占了核心代码量的三分之一。
这里负责:
加载系统提示词、技能(Skills)、记忆 调大模型 API 执行工具(跑命令、读写文件、上网搜索、调用其他插件) 处理流式输出、中断、重试
值得一提的一个细节:bash 工具的执行审批(Exec Approval)也在这里。AI 想跑一条命令,会先弹个确认框给用户,通过了才执行。这个设计对个人助理来说太有必要了。
插件 SDK:这套架构真正的野心
如果只看上面四层,OpenClaw 也就是个架构还不错的聊天网关。但它真正的杀招在 plugin-sdk 这件事上。
OpenClaw 给插件作者暴露了一个非常规整的 SDK,位于 src/plugin-sdk/,275 个文件。插件只能从这个公开面导入能力,比如:
openclaw/plugin-sdk/runtimeopenclaw/plugin-sdk/channel-runtimeopenclaw/plugin-sdk/media-runtime
仓库里有条硬规矩:插件不许直接 import 核心src/下的任何文件。所有跨包调用必须走 SDK 这层契约。这样做的好处是核心代码怎么重构,都不会把插件搞挂。
为了保证这个契约不被破坏,仓库里还配了两个漂移检测命令:
pnpm plugin-sdk:api:check—— SDK 公开 API 变了没 pnpm config:docs:check—— 配置项文档和实际 schema 对不对得上
这两个检查直接挂在 CI 上。说白了,是用工程手段把「插件生态不能崩」这件事给强制执行了。
几个让我印象深刻的设计
1. 单用户,不要 SaaS 那一套
OpenClaw 明确说自己是「personal, single-user assistant」。它不追求多租户、不追求高并发,反而把延迟和「像在本地跑」的体验做到了极致。这个定位很清醒——市面上的 AI 网关恨不得都做成企业级,它反着来。
2. 会话可以「贴」在线程上
在 Discord、Slack 这种有 Thread 概念的平台,OpenClaw 支持把 AI 会话绑定到某个讨论串上,代码在 src/channels/thread-bindings*。这意味着你可以在群里开十个话题,每个话题里的 AI 都是独立上下文,互不打架。
3. 启动时跑个 Boot Check
src/gateway/boot.ts 这段代码挺有意思:网关启动时会去读工作区里的 BOOT.md,里面可以写一些自然语言指令,比如「检查一下我昨晚的定时任务有没有跑成功,有问题发微信告诉我」。然后网关会真的开一个 AI 会话去执行这段话,该发消息发消息。
等于把「开机自检」这件原本很程序员的事,变成了写几行大白话。
4. 多渠道不是并列,是统一抽象
88 个插件、22 个聊天渠道,但没有哪个渠道是特殊公民。它们全都实现了同一套 channel-contract,生命周期、收发消息、健康检查都被抽象成统一接口。这就是为什么加一个新渠道,网关核心不用改。
看完之后的三个判断
第一,「AI 网关」这个品类正在分层。底层是协议适配(各种聊天软件),中层是会话和路由,上层是 Agent 运行时。OpenClaw 把这三层都做了,而且每一层都留了扩展点,这个架构是能扛事的。
第二,插件生态是它的护城河。53 万行核心代码不难抄,但 88 个插件、一套没人敢随便改的 SDK 契约、两个强制漂移检查,这些东西是时间和工程纪律堆出来的。
第三,它不适合所有人。运行 OpenClaw 需要 Node 22+,要自己解决模型 API,要自己处理账号登录(WhatsApp 扫码、iMessage 要苹果设备)。对普通用户门槛不低。但对想自己掌控数据、想折腾全平台 AI 助理的开发者来说,这可能是目前开源里最像样的选择之一。
我是一个写代码也写公众号的程序员。如果你也在玩 AI 助手,欢迎点个关注,后面我会继续拆一些有意思的开源项目。
本文基于 OpenClaw 2026.3.26 版本源码,仓库地址:github.com/openclaw/openclaw。文中提到的代码路径均可直接定位。