---
title: OpenClaw 专题：架构分析 🦞
date: "2026-02-24T16:37:11+08:00"
category: "OpenClaw"
description: 基于 v2026.3.8 源码，拆解一个自托管 AI 助手的工程骨架
tags: [AI, open-source, openclaw]
pinned: false
---

![OpenClaw](/images/openclaw-logo-text-dark.webp)

[上一篇](/zh-hans/posts/openclaw-ecosystem/)聊了生态，这一篇拆架构。

OpenClaw 的代码量不小：43 万行 TypeScript。但真正值得看的不是代码量，是它的架构选择。一个要同时接二十多个聊天平台、管几个 Agent、还能调工具的 AI 助手，它是怎么把这些东西塞到一起还不散架的？

## 0. 先认几个词

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

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

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

先看全景图：

![OpenClaw Architecture](/images/openclaw-architecture-zh-hans.svg)

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

| 谁 | 干什么 | 打个比方 |
|------|------|--------|
| **Channel（渠道层）** | 对接 WhatsApp、Telegram、Discord、飞书等 20+ 聊天平台 | 前台：负责接电话、收邮件、接待来访 |
| **Gateway（网关）** | 中央调度，管理所有会话和 Agent | 大脑：谁的消息该给谁处理、怎么回复，全在这里决定 |
| **Node（执行节点）** | 在设备上干活：拍照、录屏、跑命令 | 手和脚：大脑说「拍张照」，它去执行 |

整个系统的核心就是 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 里面跑。

### 「一切皆文本」的工作区

这是 OpenClaw 最有意思的设计之一：每个 Agent 的所有配置，都是你能直接打开编辑的文本文件：

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

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

### 每一轮对话怎么跑

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

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

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

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

| 层 | 是什么 | 打个比方 |
|------|--------|------|
| **SOUL** | 人格设定，永远不变 | 你的性格：出生就定了 |
| **TOOLS** | 当前装了哪些技能 | 你今天带了哪些工具出门 |
| **USER** | 关于你的长期记忆 | 你的老朋友记得你爱吃什么 |
| **Session** | 当前这次对话 | 此刻正在聊的话题 |

几个巧妙的机制：

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

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

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

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

## 6. 工具系统：只给 4 把刀

这是 OpenClaw 最「叛逆」的设计。

别的 AI Agent 框架恨不得内置一百个工具。OpenClaw 只给了 4 个：

| 工具 | 一句话 |
|------|------|
| **Read** | 读文件 |
| **Write** | 写文件 |
| **Edit** | 改文件 |
| **Bash** | 跑命令 |

就这？就这。

创始人的逻辑是：有了命令行（Bash），你能干任何事。想查天气？`curl` 一下。想发邮件？调个 CLI 工具。想操作数据库？`psql` 命令搞定。不需要为每个场景预制一个专用工具。

这就是 Unix 哲学：小工具、可组合、文本流。代价是什么？你需要一个足够聪明的模型，能自己想出该调什么命令。所以 OpenClaw 推荐用 Claude Opus 这个级别的模型。弱模型可能搞不定。

在这 4 个核心工具之上，还有 55 个内置 Skills（技能）和 ClawHub 技能市场。Skills 是可以安装和卸载的：相当于给你的 Agent 装 App。

**有意思的是，它故意不支持 MCP。** MCP 是 Anthropic 搞的工具协议标准，现在满世界的 AI 框架都在接。OpenClaw 偏不。Peter 原话是：「MCP 是垃圾，不能 scale。你知道什么能 scale？CLI。Unix。」替代方案是用内置的 `mcporter` 做桥接。

**更有意思的是自我扩展。** OpenClaw Agent 遇到不会干的事，会自己写一个 skill 来完成，写完自动装上。发现 skill 有 bug？自己改自己重载。这意味着你的 Agent 会在使用过程中越来越强：它在「养自己」。

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

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

```json
{
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "slack" } },
    { "agentId": "bot", "match": { "channel": "discord", "guildId": "123456" } }
  ]
}
```

翻译一下：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 个核心工具的极简路线是一场赌注。** 赌的是模型能力会持续上升，强到不需要预制工具就能「万物皆可 Bash」。如果大模型的天花板卡住了，这条路会很难走。但如果模型能力继续提升，这可能是最优雅的方案。

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

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