先看全貌——OpenClaw的四层架构

本系列不讲怎么用 OpenClaw，只讲它为什么这样设计。读完之后，你对 OpenClaw 的理解会从"会用"升级到"懂原理"。

你有没有想过，AI 助手背后在跑什么？

你在飞书发了一条消息：“帮我查一下明天天气。”
几秒后，AI 回复了你——不只是回了天气，它还记得你上周说过"不喜欢超过 30 度"，主动补了一句"明天 32 度，你可能会觉得热"。

这背后发生了什么？

不是魔法。是一套精心设计的系统在运转：消息怎么进来、谁来决定找哪个 AI 处理、AI 怎么调工具查天气、"记得你不喜欢热"这条记忆从哪里来、回复又怎么发回给你。

OpenClaw 做的，就是这整套系统。

理解它，从这四层架构开始。

---

四层架构总览

OpenClaw 从底到顶，由四个层次组成：

注： Workspace 不在消息的主链路上，而是以"横切注入"的方式影响 Pi Agent——每次推理开始前，Workspace 里的文件内容被读取并拼入系统提示。这就是为什么它画在最下方，而不是消息流的某一环。

每一层职责清晰，互不越界：

• Pi Agent：AI 推理、工具执行、流式输出（src/agents/pi-embedded-runner/）
• Gateway：消息路由、会话管理、客户端协调（src/gateway/）
• Channel：消息接入、格式归一化（src/channels/ + extensions/）
• Workspace：记忆存储、人格定义、规则注入（~/.openclaw/workspace/）

---

一条消息的完整旅程

最直观的理解方式，是跟着一条消息走一遍。

整个过程中，Workspace 层不直接参与消息流转，但它的内容会在推理阶段被注入到 AI 的"脑子"里，决定了 AI 的人格、记忆和行为规则。

---

为什么需要本地 Gateway？

这是 OpenClaw 架构里最值得深想的一个设计决策。

多数人第一反应是：为什么不直接让 Channel 调 Pi Agent？为什么中间要多一个 Gateway？

原因有三：

1. 统一接入点

OpenClaw 支持 52 个消息渠道。如果每个 Channel 都直接调 Agent，意味着每个 Channel 都要自己处理 Session 管理、队列、路由、多 Agent 分发……这些逻辑会在每个 Channel 里重复实现一遍。

有了 Gateway，所有 Channel 只需要把消息"扔"给 Gateway，复杂的协调逻辑全部集中在一处。

2. 解耦 UI 和运行时

Gateway 是一个 WebSocket 服务器，监听 127.0.0.1:18789。连接到这个服务器的，不只是 Channel，还有：

• macOS 伴侣 App
• iOS/Android 节点
• WebChat 网页 UI
• CLI 命令行客户端

这些都是 Gateway 的"客户端"。它们通过统一的 WebSocket 协议与 Gateway 通信，彼此完全解耦。你可以在手机 App 里看到飞书消息触发的 AI 回复，这就是 Gateway 作为中枢的价值。

3. 本地所有权

Gateway 跑在你自己的机器上，所有数据流转都在本地。没有任何消息经过第三方服务器。你的聊天记录、API Key、记忆文件，全部在你的磁盘上。

---

四层的核心设计哲学

Pi Agent 层——“只做推理，不管来源”

Pi Agent 不关心消息从哪个渠道来，不关心用户是谁。它只接受一个标准化的输入（提示词 + 工具列表），产生一个标准化的输出（回复文字 + 工具调用）。这种纯粹性让它可以被复用于任何场景。

Gateway 层——“只管协调，不做推理”

Gateway 是调度员，不是工人。它知道消息该去哪里、Session 该怎么管理、客户端该怎么认证，但它从不直接调用 LLM。

Channel 层——“只管接入，不管业务”

每个 Channel 只负责和外部平台"说话"——接收消息、发送消息、处理平台特有的格式。业务逻辑一律不放在这里。

Workspace 层——“只存数据，不执行逻辑”

Workspace 是纯粹的数据层，全部是 Markdown 文件。没有代码，没有数据库，没有服务。AI 的"记忆"就是几个文本文件——这个设计看起来简单，背后有深刻的原因（第六篇会专门讲）。

---

本系列的阅读路径

本系列共十一篇，按由底到顶的顺序展开——从 Pi Agent 运行时核心出发，逐层向上讲到 Channel 接入、Session 管理、记忆系统，最后以一条消息的完整链路串讲收尾。

建议按顺序阅读。每一篇都会引用前面的概念，后面的篇目会假设你已经理解了前面讲的内容。

下一篇，我们从最底层开始——Pi Agent，OpenClaw 的大脑是怎么运转的。

---

本文基于 OpenClaw 2026.3.1 版本源码分析