跳到主要内容
OpenClaw 架构设计解析：从 Gateway 到 Agent Runtime 全链路 | 极客日志
TypeScript Node.js AI
OpenClaw 架构设计解析：从 Gateway 到 Agent Runtime 全链路 OpenClaw 是一个开源 AI 助手运行时平台，采用 Gateway 连接聊天平台、Agent Runtime 调度 AI 模型的架构。系统包含控制面、网关层、代理运行时和节点层四层结构。核心特性包括单进程网关、WebSocket 通信协议、基于 Markdown 的文件化记忆系统以及插件化扩展能力。通过 Canvas 和 Nodes 实现多端协同与物理设备接入。相比竞品，其优势在于原生多平台支持、透明可审计的记忆机制及简洁的单进程架构，适合构建自托管 AI 助手系统。
日志猎手 发布于 2026/3/30 更新于 2026/5/22 OpenClaw 架构设计解析：从 Gateway 到 Agent Runtime 全链路
1. OpenClaw 是什么？一句话定位
OpenClaw 是一个开源的 AI 助手运行时平台，核心理念是：一个 Gateway 连接所有聊天平台，一个 Agent Runtime 调度所有 AI 模型。
你可以把它理解为"AI 助手的操作系统"——它不是一个聊天机器人，而是让你在 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等十几个平台上运行同一个 AI 助手的基础设施。
跟 Dify、Coze 这类"拖拽式 AI 应用构建平台"不同，OpenClaw 更偏底层：它关心的是消息怎么路由、上下文怎么组装、工具怎么执行、记忆怎么持久化。
2. 整体架构概览：Gateway + Agent 双核心
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 │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Control Plane（控制面） ：macOS App、CLI、Web UI、WebChat——都是客户端Gateway（网关层） ：核心枢纽，管理所有消息通道和会话Agent Runtime（代理运行时） ：AI 的大脑，负责上下文组装、模型调用、工具执行Nodes（节点层） ：分布式设备节点，提供摄像头、屏幕、位置等物理能力
3. 网关层深度解析
3.1 一个 Gateway 统治一切 OpenClaw 的设计哲学是单 Gateway 架构 ：一台主机上只运行一个 Gateway 进程，它独占所有消息通道的连接。
为什么是单进程？因为 WhatsApp（通过 Baileys 库）要求单会话连接，Telegram Bot 也是单实例。与其搞复杂的分布式锁，不如让一个进程管所有事。
3.2 WebSocket 协议：一切通信的基础 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 的首帧直接断开幂等性 Key ：所有副作用操作（send、agent）必须带幂等性 Key，服务端维护短期去重缓存事件不重放 ：客户端断线后需要自己刷新状态，不做事件回放
3.3 安全模型：设备配对 + Token 认证
每个 WS 客户端在 connect 时携带设备身份
新设备需要配对审批，Gateway 颁发设备 Token
本地连接（loopback）可以自动审批
签名载荷 v3 绑定 platform + deviceFamily，元数据变更需要重新配对
设置 OPENCLAW_GATEWAY_TOKEN 后，所有连接必须在 connect.params.auth.token 中提供匹配的 Token
远程访问推荐走 Tailscale 或 SSH 隧道
ssh -N -L18789:127.0.0.1:18789 user@host
4. Agent 运行时：AI 的大脑
4.1 会话管理 OpenClaw 的会话（Session）是 Agent 运行时的核心概念。每个聊天窗口、每个用户对话都是一个独立的会话。
独立上下文 ：每个会话有自己的消息历史和上下文窗口自动压缩（Compaction） ：当上下文接近模型的 Token 限制时，自动压缩历史消息记忆刷新（Memory Flush） ：压缩前触发一次静默的 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 一次"临终遗言"的机会，把重要信息写到文件里。
4.2 上下文组装 每次 Agent 回合，运行时需要组装完整的上下文：
System Prompt ：从 SOUL.md、AGENTS.md、USER.md 等文件加载记忆注入 ：加载 MEMORY.md（仅主会话）和 memory/YYYY-MM-DD.md工具定义 ：根据策略过滤可用工具列表消息历史 ：当前会话的对话记录Workspace 文件 ：注入工作区的关键文件内容
4.3 工具执行循环 OpenClaw 的工具执行是一个经典的 ReAct 循环：
用户消息 → 模型思考 → 调用工具 → 获取结果 → 模型继续思考 → ... → 最终回复
exec：执行 Shell 命令read/write/edit：文件操作web_search/web_fetch：网络搜索和抓取browser：浏览器自动化memory_search/memory_get：记忆检索message：跨平台消息发送cron：定时任务管理sessions_spawn：子代理编排
5. 记忆系统：Markdown 即记忆 OpenClaw 的记忆系统是我最欣赏的设计之一。它没有搞什么复杂的向量数据库，而是用纯 Markdown 文件 作为记忆的载体。
5.1 双层记忆架构 workspace/
├── MEMORY.md
└── memory/
├── 2026-03-05. md
├── 2026-03-06. md
└── heartbeat-state.json
MEMORY.mdmemory/YYYY-MM-DD.md
5.2 向量搜索 虽然记忆是 Markdown 文件，但 OpenClaw 在上面建了一层向量索引：
自动监听文件变更（防抖）
支持多种 Embedding 提供商：OpenAI、Gemini、Voyage、Mistral，甚至本地模型
通过 memory_search 工具做语义检索
memory_search(query="上次讨论的部署方案" )
5.3 为什么用 Markdown？
可以用任何编辑器查看和修改
Git 友好，可以版本控制
不依赖任何数据库
模型"记住"的东西就是写到磁盘上的东西——透明、可审计
6. 插件体系：四大扩展方向 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" ,
}
}
}
Channel 插件的丰富程度令人印象深刻——从主流的 WhatsApp/Telegram/Discord，到小众的 Nostr/Tlon/Synology Chat，甚至 IRC 都支持。这意味着你可以在几乎任何聊天平台上运行你的 AI 助手。
7. 多端协同：Canvas、A2UI 与 Nodes
7.1 Canvas：Agent 可编辑的 Web 界面 Gateway 的 HTTP 服务器提供两个特殊路径：
/__openclaw__/canvas/：Agent 可以动态生成和编辑的 HTML/CSS/JS 页面/__openclaw__/a2ui/：A2UI（Agent-to-UI）宿主 Canvas 让 AI 助手不再局限于文字回复——它可以生成交互式的 Web 界面、数据可视化、甚至小应用。
7.2 Nodes：分布式设备能力 Nodes 是 OpenClaw 最有想象力的设计之一。任何设备（macOS、iOS、Android、Headless）都可以作为 Node 连接到 Gateway：
{ "role" : "node" , "caps" : [ "camera" , "screen" , "location" , "canvas" ] , "commands" : [ "camera.snap" , "screen.record" , "location.get" ] }
通过手机摄像头拍照
录制电脑屏幕
获取设备位置
在设备上展示 Canvas 界面
Node 的配对流程跟客户端一样——设备身份 + 审批 + Token。
8. 一条消息的完整生命周期 让我们追踪一条消息从用户发送到 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 事件，实现实时流式展示。
9. 与竞品对比 特性 OpenClaw Dify Coze AutoGPT 定位 AI 助手运行时 AI 应用构建平台 AI Bot 平台 自主 AI Agent 部署方式 自托管（单进程） 自托管/云 云服务 自托管 聊天平台 15+ 原生支持 需要额外集成 有限 无 记忆系统 Markdown + 向量 向量数据库 云端 文件系统 工具扩展 插件 + Skills 可视化编排 插件市场 Python 代码 多端协同 Canvas + Nodes 无 无 无 开源 ✅ ✅ ❌ ✅ 上手难度 中等 低 低 高
真正的多平台原生支持 ：不是通过 Webhook 转发，而是原生适配每个平台的 SDKMarkdown 记忆 ：透明、可审计、Git 友好Node 系统 ：把物理设备能力接入 AI单进程简洁架构 ：不需要 Redis、PostgreSQL、消息队列
10. 实战：配置 AI 模型提供商 OpenClaw 需要配置 AI 模型的 API 才能工作。可以通过第三方 API 网关或直接对接模型厂商进行配置。
{
"providers" : {
"openai" : {
"baseUrl" : "https://api.example.com/v1" ,
"apiKey" : "sk-your-api-key"
}
}
}
这样配置后，OpenClaw 的所有模型调用都会通过指定的 Provider 路由。
11. 总结：为什么 OpenClaw 的架构值得学习 OpenClaw 的架构设计有几个值得借鉴的理念：
单进程 > 微服务 ：对于个人 AI 助手这个场景，单进程架构足够了。不需要 Kubernetes，不需要消息队列，一个进程搞定一切。文件 > 数据库 ：Markdown 记忆、JSON 配置、文件系统工作区。简单、透明、可移植。协议先行 ：先定义好 WebSocket 协议（TypeBox Schema → JSON Schema → Swift 代码生成），再实现功能。这让多端适配变得自然。插件化但不过度 ：四个核心槽位覆盖了 90% 的扩展需求，不搞复杂的插件生命周期管理。安全内建 ：设备配对、Token 认证、签名验证——安全不是事后补丁，而是架构的一部分。 如果你正在构建自己的 AI 助手系统，OpenClaw 的源码绝对值得一读。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
随机西班牙地址生成器 随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown转HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
