OpenClaw 架构设计解析:从 Gateway 到 Agent Runtime 全链路
1. OpenClaw 是什么?一句话定位
OpenClaw 是一个开源的 AI 助手运行时平台,核心理念是:一个 Gateway 连接所有聊天平台,一个 Agent Runtime 调度所有 AI 模型。
OpenClaw 是一个开源 AI 助手运行时平台,采用 Gateway 连接聊天平台、Agent Runtime 调度 AI 模型的架构。系统包含控制面、网关层、代理运行时和节点层四层结构。核心特性包括单进程网关、WebSocket 通信协议、基于 Markdown 的文件化记忆系统以及插件化扩展能力。通过 Canvas 和 Nodes 实现多端协同与物理设备接入。相比竞品,其优势在于原生多平台支持、透明可审计的记忆机制及简洁的单进程架构,适合构建自托管 AI 助手系统。
OpenClaw 是一个开源的 AI 助手运行时平台,核心理念是:一个 Gateway 连接所有聊天平台,一个 Agent Runtime 调度所有 AI 模型。
你可以把它理解为"AI 助手的操作系统"——它不是一个聊天机器人,而是让你在 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等十几个平台上运行同一个 AI 助手的基础设施。
跟 Dify、Coze 这类"拖拽式 AI 应用构建平台"不同,OpenClaw 更偏底层:它关心的是消息怎么路由、上下文怎么组装、工具怎么执行、记忆怎么持久化。
OpenClaw 的架构可以用一张图概括:
┌─────────────────────────────────────────────────────────┐
│ Control Plane │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ macOS App│ │ CLI │ │ Web UI │ │ WebChat │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ └────────────┼────────────┼─────────────┘ │
│ │ WebSocket │
│ ┌────▼──────────────▼───────┐ │
│ │ GATEWAY │ │
│ │ ┌─────────────────────────┐│ │
│ │ │ Channel Adapters ││ │
│ │ │ WhatsApp Telegram Slack ││ │
│ │ │ Discord Signal iMessage ││ │
│ │ └─────────────────────────┘│ │
│ │ ┌─────────────────────────┐│ │
│ │ │ Session Manager ││ │
│ │ │ Auth Protocol Cron ││ │
│ │ └─────────────────────────┘│ │
│ └──────────────┬───────────────┘ │
│ │ │
│ ┌──────────────▼───────────────┐ │
│ │ AGENT RUNTIME │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │Memory│ │Tools │ │Canvas│ │ │
│ │ └──────┘ └──────┘ └──────┘ │ │
│ │ ┌──────────────────────────┐│ │ │
│ │ │ Model Providers ││ │ │
│ │ │ GPT Claude Gemini DeepSeek││ │ │
│ │ └──────────────────────────┘│ │ │
│ └──────────────────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────┐ │
│ │ NODES │ │
│ │ macOS iOS Android Headless │ │
│ │ Camera Screen Location Canvas │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
整个系统分为四层:
OpenClaw 的设计哲学是单 Gateway 架构:一台主机上只运行一个 Gateway 进程,它独占所有消息通道的连接。
# 启动 Gateway
openclaw gateway
# 默认监听
# WebSocket: 127.0.0.1:18789
# HTTP (Canvas): 同端口
为什么是单进程?因为 WhatsApp(通过 Baileys 库)要求单会话连接,Telegram Bot 也是单实例。与其搞复杂的分布式锁,不如让一个进程管所有事。
Gateway 的所有通信都走 WebSocket,协议设计非常干净:
// 请求
{"type":"req","id":"abc123","method":"agent","params":{...}}
// 响应
{"type":"res","id":"abc123","ok":true,"payload":{...}}
// 事件(服务端推送)
{"type":"event","event":"agent","payload":{...},"seq":42}
关键设计决策:
connect:任何非 JSON 或非 connect 的首帧直接断开send、agent)必须带幂等性 Key,服务端维护短期去重缓存OpenClaw 的安全模型分两层:
设备配对(Pairing):
connect 时携带设备身份platform + deviceFamily,元数据变更需要重新配对Token 认证:
OPENCLAW_GATEWAY_TOKEN 后,所有连接必须在 connect.params.auth.token 中提供匹配的 Token# SSH 隧道远程访问
ssh -N -L18789:127.0.0.1:18789 user@host
OpenClaw 的会话(Session)是 Agent 运行时的核心概念。每个聊天窗口、每个用户对话都是一个独立的会话。
会话的关键特性:
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000,
"systemPrompt": "Session nearing compaction. Store durable memories now.",
"prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply NO_REPLY if nothing to store."
}
}
}
}
}
这个设计非常巧妙——在上下文被压缩之前,给 AI 一次"临终遗言"的机会,把重要信息写到文件里。
每次 Agent 回合,运行时需要组装完整的上下文:
SOUL.md、AGENTS.md、USER.md 等文件加载MEMORY.md(仅主会话)和 memory/YYYY-MM-DD.mdOpenClaw 的工具执行是一个经典的 ReAct 循环:
用户消息 → 模型思考 → 调用工具 → 获取结果 → 模型继续思考 → ... → 最终回复
内置工具非常丰富:
exec:执行 Shell 命令read/write/edit:文件操作web_search/web_fetch:网络搜索和抓取browser:浏览器自动化memory_search/memory_get:记忆检索message:跨平台消息发送cron:定时任务管理sessions_spawn:子代理编排OpenClaw 的记忆系统是我最欣赏的设计之一。它没有搞什么复杂的向量数据库,而是用纯 Markdown 文件作为记忆的载体。
workspace/
├── MEMORY.md # 长期记忆(人工策展)
└── memory/
├── 2026-03-05.md # 昨天的日志
├── 2026-03-06.md # 今天的日志
└── heartbeat-state.json
MEMORY.md:长期记忆,类似人的"长期记忆"。存放决策、偏好、重要事实。仅在主会话加载(安全考虑)。memory/YYYY-MM-DD.md:每日日志,类似人的"工作记忆"。追加写入,每次会话加载今天和昨天的。虽然记忆是 Markdown 文件,但 OpenClaw 在上面建了一层向量索引:
memory_search 工具做语义检索# Agent 内部调用示例
memory_search(query="上次讨论的部署方案")
# → 返回相关记忆片段 + 文件路径 + 行号
这个设计选择背后的哲学是:文件是真相的唯一来源。
OpenClaw 的插件系统围绕四个核心槽位(Slot)设计:
| 槽位 | 职责 | 示例 |
|---|---|---|
| Channel | 消息通道适配 | WhatsApp、Telegram、Discord、Slack、Signal、iMessage、IRC、Matrix、LINE、Nostr… |
| Memory | 记忆存储和检索 | memory-core(默认)、自定义向量后端 |
| Tool | 工具能力扩展 | 浏览器控制、文件操作、API 调用、Feishu 集成 |
| Provider | 模型提供商 | OpenAI、Anthropic、Google、DeepSeek… |
插件配置示例:
{
"plugins": {
"slots": {
"memory": "memory-core", // 或 "none" 禁用
// 其他槽位...
}
}
}
Channel 插件的丰富程度令人印象深刻——从主流的 WhatsApp/Telegram/Discord,到小众的 Nostr/Tlon/Synology Chat,甚至 IRC 都支持。这意味着你可以在几乎任何聊天平台上运行你的 AI 助手。
Gateway 的 HTTP 服务器提供两个特殊路径:
/__openclaw__/canvas/:Agent 可以动态生成和编辑的 HTML/CSS/JS 页面/__openclaw__/a2ui/:A2UI(Agent-to-UI)宿主Canvas 让 AI 助手不再局限于文字回复——它可以生成交互式的 Web 界面、数据可视化、甚至小应用。
Nodes 是 OpenClaw 最有想象力的设计之一。任何设备(macOS、iOS、Android、Headless)都可以作为 Node 连接到 Gateway:
// Node 连接时声明能力
{"role":"node","caps":["camera","screen","location","canvas"],"commands":["camera.snap","screen.record","location.get"]}
这意味着你的 AI 助手可以:
Node 的配对流程跟客户端一样——设备身份 + 审批 + Token。
让我们追踪一条消息从用户发送到 AI 回复的完整路径:
1. 用户在 Telegram 发送 "帮我查一下今天的天气"
2. Telegram Bot API → Gateway Channel Adapter (grammY)
解析消息、提取文本、识别会话
3. Gateway Session Manager
查找/创建会话、检查权限
4. Agent Runtime 开始新回合
├─ 4a. 组装上下文
System Prompt + SOUL.md + MEMORY.md
+ memory/2026-03-06.md
+ 工具定义列表
+ 历史消息
├─ 4b. 调用 AI 模型
POST /v1/chat/completions
→ 模型返回:调用 weather 工具
├─ 4c. 执行工具
weather("北京") → 获取天气数据
├─ 4d. 再次调用模型
将工具结果注入上下文
→ 模型生成最终回复
5. Gateway 将回复路由回 Telegram
通过 grammY 发送消息
6. 用户在 Telegram 收到天气信息
整个过程中,Gateway 通过 WebSocket 向所有连接的客户端(macOS App、Web UI 等)推送 event:agent 事件,实现实时流式展示。
| 特性 | OpenClaw | Dify | Coze | AutoGPT |
|---|---|---|---|---|
| 定位 | AI 助手运行时 | AI 应用构建平台 | AI Bot 平台 | 自主 AI Agent |
| 部署方式 | 自托管(单进程) | 自托管/云 | 云服务 | 自托管 |
| 聊天平台 | 15+ 原生支持 | 需要额外集成 | 有限 | 无 |
| 记忆系统 | Markdown + 向量 | 向量数据库 | 云端 | 文件系统 |
| 工具扩展 | 插件 + Skills | 可视化编排 | 插件市场 | Python 代码 |
| 多端协同 | Canvas + Nodes | 无 | 无 | 无 |
| 开源 | ✅ | ✅ | ❌ | ✅ |
| 上手难度 | 中等 | 低 | 低 | 高 |
OpenClaw 的独特优势在于:
OpenClaw 需要配置 AI 模型的 API 才能工作。可以通过第三方 API 网关或直接对接模型厂商进行配置。
配置方式:
{
"providers": {
"openai": {
"baseUrl": "https://api.example.com/v1",
"apiKey": "sk-your-api-key"
}
}
}
这样配置后,OpenClaw 的所有模型调用都会通过指定的 Provider 路由。
OpenClaw 的架构设计有几个值得借鉴的理念:
如果你正在构建自己的 AI 助手系统,OpenClaw 的源码绝对值得一读。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online