OpenClaw 架构：自托管 AI 助手的工程骨架 🦞

上一篇聊了生态，这一篇拆架构。

OpenClaw 的代码量不小：43 万行 TypeScript。但这篇文章不看代码量，看复杂性怎么被分配。一个自托管 AI 助手要同时处理二十多个聊天入口、多个 Agent、工具调用和权限边界；架构问题不是“功能怎么塞进去”，而是“哪些复杂性应该留在运行时，哪些应该推给模型、CLI 和策略层”。

0. 先认几个词

如果你没有系统架构背景，也没关系。先记住 6 个词，后面会顺很多：

• 架构：系统如何分层、每层分别负责什么。
• Channel / 渠道层：负责和外部聊天平台“说同一种协议”的适配层。
• Gateway / 网关：中央调度者，负责路由消息、管理会话和 Agent。
• Node / 执行节点：真正去拍照、跑命令、操作设备的执行端。
• workspace / 工作区：Agent 的配置、记忆、技能和会话文件所在的本地目录。
• sandbox / 沙箱：把高风险操作隔离起来的受限执行环境。

1. 3 层架构：Channel → Gateway → Node

先看全景图：

你可以把 OpenClaw 想成一家公司的 3 个部门：

整个系统的核心就是 Gateway：一个常驻运行的进程，默认只监听本机（127.0.0.1:18789），不对外网开放。想远程访问？走 Tailscale 隧道，不直接暴露端口。这个设计叫「Loopback-First」，安全上很讨巧：什么端口都不开，就没有攻击面。

为什么只用一个进程不搞分布式？原因很实际：WhatsApp 协议要求同一时间只能有一个设备在线，你搞两个进程反而会打架。与其为了「架构正确」多搞一堆协调逻辑，不如老老实实一个进程管到底。对绝大多数个人用户来说，够用了。

2. 一条消息的旅程

你在 Telegram 上跟你的 OpenClaw 说了一句「帮我查下明天北京天气」，发生了什么？

第 1 步：接入。 Telegram 适配器收到消息，把 Telegram 格式的数据翻译成 OpenClaw 内部统一格式。不管消息从哪个平台来，翻译完都长一个样。

第 2 步：验身份、找路由。 你是谁？允不允许跟 Agent 说话？如果是陌生人，先弹一个配对码让主人批准。通过后，路由引擎决定这条消息交给哪个 Agent。

第 3 步：组装上下文。 从磁盘读出你之前的聊天记录，加载 Agent 的性格设定（SOUL.md）、行为规则（AGENTS.md），再从记忆库里语义搜索相关内容。组装成一份完整的「大脑简报」。

第 4 步：问大模型。 这份简报发给 Anthropic、OpenAI、DeepSeek、MiniMax、GLM、Qwen、Gemini 等大模型提供商（你配了哪个就用哪个），模型一个字一个字地流式吐出回复。

第 5 步：执行工具。 如果模型说「我需要跑个命令查天气」，运行时会拦截这个请求，根据安全策略决定在哪里执行（管理员的命令直接跑，陌生人的命令丢到 Docker 沙箱里跑），然后把结果喂回给模型继续生成。

第 6 步：回复。 最终答案按 Telegram 的格式要求（字数限制、Markdown 规则等）拆好，发回给你。聊天记录写入磁盘。

整个链路中，真正慢的是第 4 步：等大模型吐第一个字。其他步骤基本都是毫秒级。

3. 渠道适配层：一次开发，到处说话

OpenClaw 对接了二十多个聊天平台，但不是每个平台都从零写一套。它抽象了一层「适配器」，每个平台的适配器只负责四件事：

• 登录：WhatsApp 扫二维码、Telegram 填 Bot Token、iMessage 用 macOS 原生能力：各平台各的规矩
• 翻译进来的消息：不管是文字、图片、回复还是表情，统统翻译成内部统一格式
• 管门禁：谁能私聊、群里要不要 @才回复、哪些群允许
• 翻译出去的回复：把 Agent 的回复适配成各平台能显示的格式

内置的有六个大平台（WhatsApp、Telegram、Discord、Slack、Signal、iMessage），其他三十多个（飞书、LINE、Matrix、Mattermost 等）通过插件接入。

这层抽象最大的好处是：Agent 完全不需要知道消息来自哪个平台。你在 WhatsApp 上聊的 Agent 和在 Telegram 上聊的是同一个，逻辑完全复用。渠道只是「传话筒」，换一个传话筒不影响说话的人。

4. Agent 运行时与工作区

Agent 运行时的内核来自 Pi-mono（一个开源编程 Agent），嵌入在 Gateway 里面跑。

「一切皆文本」的工作区

这里的关键设计是：每个 Agent 的所有配置，都落在可以直接打开编辑的文本文件里：

1
workspace/
2
├── AGENTS.md          # 定义 Agent 是谁、怎么做事（相当于简历+工作手册）
3
├── SOUL.md            # 灵魂设定：性格、价值观（写好就不该改）
4
├── USER.md            # 记录用户信息：你叫什么、喜好是什么
5
├── MEMORY.md          # 长期记忆：Agent 主动记下的重要事情
6
├── HEARTBEAT.md       # 定时任务：比如每天早上报天气
7
├── memory/            # 日记本
8
│   └── YYYY-MM-DD.md  # 每天一页，只追加不修改
9
├── skills/            # 技能包
10
└── sessions.json      # 会话记录

没有数据库，没有专用管理界面，纯文本文件。想改 Agent 性格？打开 SOUL.md 改两行就行。想看它记住了什么？打开 MEMORY.md 直接看。这种「你能看到它的全部大脑」的透明感，是很多封闭 AI 产品做不到的。

每一轮对话怎么跑

1. 分清身份：你是管理员直聊、朋友私聊、还是群里有人 @了它？不同来源，安全等级不同
2. 组装记忆：读聊天记录、加载性格和规则、搜索相关的长期记忆，拼成一份完整上下文
3. 问大模型：发给配置的模型，支持 fallback：主力模型挂了自动切备用
4. 干活+记住：执行工具调用，更新聊天记录

上下文的组装不是把所有东西一股脑塞进去。不相关的技能不加载、不需要的工具不注入：省 token 就是省钱。

5. 4 层记忆：让 AI 真的「记住你」

普通聊天机器人关掉窗口就失忆了。OpenClaw 不会。它有 4 层记忆，从最深层的「我是谁」到最浅层的「刚才聊了啥」：

几个巧妙的机制：

每日日记。 每天的对话会自动写进 memory/2026-03-12.md（只追加，不覆盖）。下次开聊时，Agent 会自动翻看今天和昨天的日记，保持连续感：「你昨天说要买的那本书，买了吗？」

自动抢救记忆。 聊得太长，上下文快塞满了怎么办？OpenClaw 会偷偷在后台跑一个隐形轮次，把重要信息存进 MEMORY.md，然后压缩掉旧内容。你察觉不到这个过程，但关键信息不会丢。这个机制叫 Pre-Compaction。

语义搜索。 你说「之前聊过的那个部署问题」，它能从记忆里搜出来：不是靠关键词精确匹配，而是靠语义理解。底层是向量搜索（SQLite-vec）+ 传统关键词搜索（BM25）双管齐下。

跨平台认人。 你在 Telegram 上跟它聊了半小时，切到 WhatsApp 继续聊，它认得你。同一个人在不同平台的 ID 会被链接到同一个身份，共享同一份记忆。但群聊的记忆是隔离的：你在群里说的话，不会泄露到私聊里。

6. 工具系统：复杂性转移到 CLI

OpenClaw 的工具系统很克制。

很多 AI Agent 框架会预置大量专用工具。OpenClaw 只保留 4 个核心工具：

这条路线的前提是：命令行已经封装了大量现实世界能力。查天气可以调用 curl，发邮件可以调用 CLI，查数据库可以走 psql。系统不为每个场景预制工具，而是把通用执行接口交给模型。

代价也很明确：模型必须知道该调用什么命令、如何组合命令、什么时候停止。复杂性没有消失，只是从工具清单转移到了模型能力、CLI 生态和权限策略。

在这 4 个核心工具之上，还有 55 个内置 Skills 和 ClawHub 技能市场。Skills 负责把高频流程封装起来，避免每次都从 Bash 层重新规划。

MCP 被放在旁路，而不是主路径。 MCP 是 Anthropic 推出的工具协议标准，很多 AI 框架都在接入。OpenClaw 的主路径选择 CLI/Unix，并用内置的 mcporter 做桥接。这不是单纯反标准，而是把工具生态的中心放在命令行可组合性上。

自我扩展把能力沉淀成 skill。 OpenClaw Agent 遇到不会做的事，可以生成 skill、安装、再在发现问题时修改重载。关键不在“自动变强”，而在临场解决方案能否沉淀成可复用流程。

7. 多 Agent 路由：一个大脑，多个人格

一个 Gateway 可以同时跑好几个 Agent，各管各的。路由规则长这样：

1
{
2
  "bindings": [
3
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
4
    { "agentId": "work", "match": { "channel": "slack" } },
5
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
6
  ]
7
}

翻译一下：WhatsApp 私人号来的消息给「家庭助手」处理，Slack 的给「工作助手」，Discord 某个服务器的给「社区机器人」。三个 Agent 完全隔离：各自有自己的性格、记忆、技能和安全策略。

8. 安全：3 道门

你的 Agent 跑在你自己的服务器上，能执行命令、读写文件：安全当然是大事。OpenClaw 的安全模型分 3 道门：

第一道门：你是谁？（私聊配对） 陌生人给你 Agent 发消息，Agent 不会直接回。它会发一个 6 位配对码，你在已认证的渠道里确认了，对方才能用。这是默认行为：关掉就意味着任何知道你号码的人都能白嫖你的 API 额度。

第二道门：VIP 通道（白名单）。 信任的人可以直接加到白名单里（allowFrom），跳过配对直接聊。

第三道门：群里别瞎回（群组规则）。 群聊里 Agent 默认只在被 @ 时才回复，不会对着群里每条消息都冒泡：既省 token，又不扰民。

再往下还有纵深防御：工具权限五层过滤、Docker 沙箱隔离（陌生人的命令在沙箱里跑）、安全审计命令（openclaw security audit）。这些层是独立的：配对码泄露了？沙箱还在。沙箱被绕过了？工具策略还限制着能调什么。

9. 几个判断

单进程不是偷懒，是务实。 对个人用户来说，一个进程管到底比搞分布式靠谱得多。这个架构的天花板在哪？大概是同时在线的消息量超过单机处理能力的时候：对绝大多数人来说，这一天不会来。

渠道抽象层是最值钱的一层。 二十多个平台的差异全封装在适配器里，Agent 完全不操心消息从哪来。想加一个新平台？写个适配器就行，Agent 逻辑一行不改。这个解耦做得非常干净。

安全设计是认真的，但落地仍有差距。 架构上从身份、沙箱到工具策略做了纵深防御。但 Kaspersky 审计发现了 512 个漏洞（8 个严重级别），说明蓝图画得好和实际安全之间，隔着持续的工程投入。

4 个核心工具的路线是一场复杂性转移。 它赌的不是“工具越少越好”，而是模型能力、CLI 生态和权限策略加在一起，能比大量预制工具更可扩展。如果模型能力不足，Bash 会变成风险入口；如果权限收得住，这条路线会把工具系统做得很薄。

最终的检验标准不是架构有多漂亮，而是跑得稳不稳。 这篇分析基于源码静态阅读。实际效果：高并发下的 Gateway 稳定性、沙箱真的能不能防住攻击、跨渠道认人的边界情况：需要更多真实使用数据来验证。

架构只是骨架，生产环境才是考场。