第6课：OpenClaw｜四层架构全解析【Gateway到底有多重要】

OpenClaw采用四层架构设计，包含Gateway、Service、Manager及DAO层，各层职责明确，协同构建高效系统。Gateway作为核心入口，承担请求路由、协议转换、流量管控等关键职能，直接影响系统的可用性与扩展性。Gateway层通过统一鉴权、负载均衡和熔断机制保障高并发场景下的稳定性，同时屏蔽内部服务细节，提升安全性。Service层处理业务逻辑，Manager整合领域能力，DA

Thomas.Sir

500人浏览 · 2026-05-10 17:42:39

Thomas.Sir · 2026-05-10 17:42:39 发布

在这里插入图片描述

文章目录

你有没有想过这样一个问题：为什么有些Agent框架跑着跑着就卡死了，而OpenClaw能在飞书上连续运行三个月不重启？为什么有些框架换个模型就像换了个脑子，而OpenClaw换模型后Agent该干啥还干啥？

答案是藏在架构里的。OpenClaw的创始人Peter Steinberger曾透露过他的设计哲学：“我们不是在搭建聊天机器人，而是在构建连接AI与现实世界的操作系统。”正是这套成熟的四层架构，让OpenClaw在稳定性、可扩展性和可观测性上远超市面上绝大多数Agent框架。

前五节课，我们从安装部署、Workspace配置、跨平台部署走到了Channel集成——你已经摸遍了OpenClaw的外围和配置层。今天这节课，我们来掀开引擎盖，深入到它的骨架与心脏：四层架构。当你理解了每一层的独立角色和协作方式，就等于拿到了一张精准的排障导航图。

这不是理论课。读完这节课，你将能够：

在生产环境里精准定位故障层，而不是大海捞针式地看日志
设计出贴合真实业务场景的Agent系统架构
理解为什么Gateway是7×24小时稳定运行的关键所在

6.1 控制网关层（Gateway）：系统的数据咽喉

一句话概括：Gateway是OpenClaw的“中央控制平面”——单进程常驻、单端口复用，集消息路由、会话管理、鉴权认证、状态同步和插件加载于一体，是连接所有外部渠道与内部智能体执行引擎的唯一入口。

要理解Gateway在OpenClaw中的作用，先看一个对比：绝大多数的Agent框架采用“分布式微服务架构”——消息进一个服务、路由进一个服务、执行进一个服务，各服务通过HTTP或RPC通信。这种设计“看起来”很灵活，但实际部署时光配网络和安全组就能让你想砸电脑。而从代码结构来看，更关键的问题在于：把一个请求拆到多个独立进程里处理，进程间通信的开销会成倍放大，而OpenClaw在1000个消息/秒的基准测试中获得了约35%的吞吐量提升，其中关键因素就是减少了中间队列开销——因为所有交互都集中在Gateway这一个进程里，消息无需在多服务之间来回跳转。

Gateway的核心职责拆解

Gateway是怎么做到“以一当十”的呢？我从源码实现和运行时模型两个维度来拆解：

从启动流程看，Gateway是一个单Node.js进程，但它在同一个TCP端口（默认18789）上同时承载了WebSocket控制平面、HTTP API和控制UI。打开官方文档，“Gateway runs as a single always-on process that manages all sessions, coordinates agent execution, routes messages between channels and agents, handles device pairing, serves the Control UI, and exposes a unified WebSocket/HTTP API for all client interactions”——六项职责，每一项都不简单。

（1）消息路由（Message Routing）

这是Gateway最核心的职责。消息路由器（Message Router）就像一个超级快递员——它同时接住来自WhatsApp、Telegram、飞书等所有渠道的入站消息，根据消息的发送者、聊天室类型、平台属性等信息，精准地判断该由哪个Agent处理、该丢进哪个会话里跑。

OpenClaw的路由解析引擎有一套优先级明确的匹配规则：先匹配具体的对话对象，再匹配社群+角色、社群、团队、账号、渠道，最后才落到默认Agent。这一连串匹配，Gateway都能在毫秒级完成。

（2）会话管理（Session Management）

每个会话是一个“对话身份证”，负责承载用户与AI之间的完整对话上下文。Gateway负责会话的创建、生命周期管理、状态持久化，以及在私聊和群聊场景下的“路由隔离”。用户在Telegram私聊中和Agent说的话，不会被群里插话的人看到——这是Gateway在背后做的核心防护。

【安全提醒】Gateway默认绑定在127.0.0.1回环地址，外部无法直接访问，这是有意构建的安全边界——防止Agent被未授权的外部调用劫持。但同时，Gateway强制开启了基于共享密钥（share key）的身份认证，未授权的客户端无法建立WebSocket连接。在生产环境中，要将Gateway和聊天平台都托管在独立的网络隔离环境中，并通过trusted-proxy等机制在可靠的反向代理后将安全策略进行成体系地补全。

（3）插件加载与总线调度

Gateway自身是一个插件运行时宿主，它在启动时加载所有Channel插件，将它们注册到ChannelRegistry中，此后才能接收和分发各平台消息。Gateway加载时会在初始化阶段扫描extensions/目录，并为每个Channel插件提供运行环境，使Telegram的Webhook回调能够被正确“翻译”成标准消息格式。

（4）定时任务（Cron & Heartbeat）

在第14课里我们会专门讲解，但今天先提一句：所有定时任务的调度逻辑，都发生在Gateway的配置与定时任务调度模块中。每日凌晨的系统清理、故障自愈重试、心跳健康检查，全部由Gateway完成。

（5）设备配对（Device Pairing）

当你有多个设备访问Gateway（如笔记本电脑控制UI和手机App同时发消息），Gateway提供统一的设备配对机制，管理多端会话同步和授权。

理解了Gateway的五大职责后，一个更本质的问题浮现出来了：Gateway到底“是”什么？它和微服务架构里的API Gateway是同一个东西吗？

这也是社区最常见的技术误解。有一个精准的回答：Gateway不是“协议翻译官”，也不是消息转发代理。它自己就包含了Channel Plugin的调用，而Channel Plugin才是真正与外部平台（WhatsApp、Telegram等）进行连接收发的组件。形象地说——Channel Plugin是那些埋在土里的光纤，负责连接不同的IM平台；Gateway是立在光纤交汇点的核心机房，所有信号进来后在这里完成调度、处理和重新分发。Gateway不关心每条消息的内容是什么（那是Agent层的事），它只负责“把消息送到该去的地方”。

【来自官方文档的关键约束】每个会话同时只能执行一个Agent任务，通过Lane Queue实现串行化调度。为什么要有这条默认设计？核心目的是保证消息顺序。同一个会话里，用户问A、再问B，B不能在A还没执行完就插队进入Agent。但不同会话之间可以独立并行——这就是“显式并行，默认串行”的工程智慧。

🛠️ 实战小测：验证Gateway的插件加载

现在，来亲手验证一下Gateway的插件加载流程。

打开一个终端窗口，执行以下命令：

# 启动Gateway并查看插件加载日志
openclaw gateway start --log-level debug

# 在另一个终端中查看已加载的插件列表
openclaw plugins list

你会看到类似这样的输出：

[gateway] loading plugins...
[gateway] loaded plugin: telegram (v1.2.0)
[gateway] loaded plugin: discord (v1.0.5)
[gateway] loaded plugin: slack (v0.8.0)
[gateway] ready (9 plugins, 4.1s)

plugins list的输出会显示每个插件的状态——loaded表示成功加载，disabled表示被用户禁用，error表示加载失败。如果某个Channel插件无法加载，排查Step 1就是看它是否出现在这个列表里——这是全网公认的“从Channel层切入排查”的第一站。

6.2 推理与认知层：AI的“大脑中枢”

一句话概括：推理与认知层是Agent真正“思考”的核心——通过动态组装Workspace中的Markdown引导文件为系统提示词，使无状态的大模型表现出拥有特定人格、知识和边界的智能体行为。

这一层的设计有一个关键的洞察：大语言模型本身是无状态的——它不会记住你和它在10分钟前说过什么。但OpenClaw向用户呈现出了一个“能记忆、有性格”的Agent。这个“魔法”不是模型的能力做多了，而是OpenClaw的推理层在每次调用模型前，都把相关上下文、记忆、配置和人格定义统统注入到了系统提示词里。

注入式系统提示词：如何让“陌生人”变得“知根知底”

OpenClaw为每次Agent运行时构建定制化的系统提示词。这个提示词不由大模型的默认值决定，而是由OpenClaw自己组装，包含了以下固定部分：

Tooling：当前可用的工具列表及其简短描述
Safety：安全防护提醒，约束模型行为边界
Skills（如可用）：告诉模型如何按需加载Skill指令
Workspace：工作目录的路径信息
Workspace Files：注入的引导文件——AGENTS.md、SOUL.md、TOOLS.md等
Current Date & Time：用户本地时间和时区
Runtime：主机系统、Node版本、模型信息等原始运行数据
Reasoning：推理级别的可见性控制

系统提示词中的安全防护仅仅是“建议性的”——它们指导模型行为但不强制执行策略。真正的强制策略是通过工具拒绝策略、执行审批流程、沙箱隔离和渠道允许列表来实现的。

🚨【安全警告】：系统提示词中的安全指引并非不可绕过——它只是“建议”，不是“防火墙”。真正的防护需要配合第27课的沙箱执行和第28课的安全策略体系落地。不要过于依赖提示词层面的限制。

提示词的限制与管理

由于单次请求Token有限制，OpenClaw引入了分片注入和自动截断的逻辑：

单个引导文件最多被注入agents.defaults.bootstrapMaxChars字符（默认20,000）
Workspace中所有注入内容之和最多不超过150,000字符——超出时将被截断

第3课中我们已经详细学习过AGENTS.md、SOUL.md、TOOLS.md等文件的作用，现在就能回到架构图里定位到它们被“注入”的位置：即触发Agent执行前，这些文件被从磁盘读取、聚合、修剪、注入系统提示词。

提示词模式：释放子Agent时的Token节约手段

OpenClaw支持三种提示词模式，运行时根据需要为每次运行设置promptMode：

full（默认）：包含上述所有部分的完整提示词，用于主会话
minimal：用于子Agent，省略Skills、Memory Recall、OpenClaw Self-Update等部分，工具和安全信息仍然保留，Token约能节省30%-50%
none：仅返回基本身份行，Token消耗几乎为0

在子Agent（Subagent）执行任务时，Agent默认使用minimal模式，这是OpenClaw内部实现的性能优化策略——子Agent只需完成父Agent分配的具体子任务，无需完整人格设定和全部工具列表。

Agent执行循环：ReAct范式的工程实现

在理解“大脑如何思考”之前，还需要回答一个问题：装入了系统提示词的大模型，是如何驱动Agent进行多步任务的？

OpenClaw遵循经典的ReAct（Reasoning + Acting）范式——即“思考→行动→观察”的循环。一次完整的Agent执行包含以下步骤：

用户输入到达Agent Runtime
系统提示词组装：注入工作区的配置文件、记忆系统检索结果
模型推理：大模型基于提示词和用户输入，输出结构化回复——可能是最终回答，也可能是工具调用请求
工具执行：Runtime执行模型请求的工具（如打开文件、调用API）
结果回写：工具执行结果作为“Observation”写回上下文
决定下一步：模型基于新获得的观察信息，决定继续调用更多工具，还是生成最终答案返回用户

这个循环反复进行直到任务完成。一个值得注意的细节是：OpenClaw的提示词模式只控制“子Agent”的提示词结构，并不影响主Agent的ReAct执行逻辑本身。

🛠️ 实测一下：查看某次运行中注入的文件

用openclaw logs命令查看Gateway日志，你会发现以下信息：

openclaw logs --tail 50 | grep -E "\"

日志中会显示某条命令触发时系统提示词包含的内容。如果想直观了解系统提示词的完整结构，可以使用开发者调试模式：

openclaw gateway --debug-run "请介绍一下你自己" --dry-run

输出中会显示拼装后的系统提示词——你将看到前面提到的Tooling、Safety、Workspace Files等所有部分在同一个提示词块里被一起发给大模型。结合第3课学到的AGENTS.md等文件的内容，现在你应该能直观地理解它们是何时、以什么形式“注入到大脑里”的。

6.3 记忆与状态层：跨会话上下文持久化

一句话概括：OpenClaw的记忆系统是一套精妙的分层架构——会话级短期记忆按日归档、跨会话长期记忆存储持久事实、同时支持可选的向量检索来扩展认知边界，让AI从“每次对话都像第一次”蜕变为“能记住你是谁”的数字伙伴。

如果你仔细分析过其他Agent框架的记忆策略，会发现大多数只有“会话窗口”这一层——你今天和它对话的所有内容都保存在这个“上下文盒子”里，会话结束后关上了盒子，第二天它就什么都忘了。

OpenClaw放弃了这种“每次都拔电源再插上的行为逻辑”，核心维度是时间分层和向量检索。

三级记忆体系的深度拆解

打开OpenClaw的workspace目录，这套三层体系一目了然：

~/.openclaw/workspace/
├── MEMORY.md        # 长期记忆：用户偏好、工作背景、项目决策等持久事实
├── memory/          # 短期记忆目录
│   ├── 2026-05-05.md
│   ├── 2026-05-06.md
│   └── ...
├── sessions/        # 会话存档（近端记忆）
├── USER.md          # 用户身份描述
└── SOUL.md          # Agent人格设定

第一层：短期记忆（Daily Log）

每天一个独立的YYYY-MM-DD.md文件，以“仅追加（append-only）”的方式记录所有对话。一个关键的设计细节是：系统在每次会话启动时只加载“今天+昨天”两个日志文件——既让Agent拥有最近48小时的上下文连续性，又防止无限制地将历史对话全文加载到Token里形成巨大的浪费。

第二层：近端记忆（Sessions）

当单次对话超过上下文窗口限制时，OpenClaw不会简单粗暴地截断，而是通过上下文压缩（Context Compression） 将过长对话中的关键信息沉淀到近端记忆存储中。但需要注意的是，OpenClaw的本地记忆系统在上下文压缩后记忆会丢失一部分——对于生产级的长期对话场景，用户可能需要接入外部持久化存储来做更可靠的“记忆保险”。

第三层：长期记忆（MEMORY.md + 向量检索）

MEMORY.md存储的是经过AI自筛选后持久化的知识：你的技术栈偏好、经常使用的工具链配置、项目宏观决策等信息。长记忆会在每次用户与Agent私聊时自动加载。

但仅仅Markdown文件不够——要在越来越多的文本中高效地检索最相关的内容，需要建立索引。OpenClaw在每个Agent对应的独立SQLite数据库（位于~/.openclaw/memory/{agentId}.sqlite）中，巧妙地采用了倒排索引（FTS5全文搜索）+ 向量嵌入的混合设计：

-- 虚拟表：全文搜索（FTS5）
CREATE VIRTUAL TABLE chunks_fts USING fts5(text, content=chunks);

-- 虚拟表：向量搜索（sqlite-vec）
CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[1536]);

在检索时，系统会将用户的查询同时交给BM25（关键词匹配）和向量相似度（语义检索）两条路径，然后将结果合并、去重并按相关度排序后返回给模型。

避坑指南：这套基于SQLite的本地向量检索在很多用户场景中能跑得很好，但请注意：它是零运维的本地方案，并非对标企业级Vector DB的性能。数据库可能随着聊天历史增长而变大——建议定期清理过期记忆或配置自动归档。如果你需要跨Agent的记忆共享或更复杂的检索逻辑，阿里云Tablestore记忆插件提供了企业级替代方案，支持跨Agent共享记忆和混合检索，并且压缩后记忆不会丢失。

值得注意的是，OpenClaw的官方长期记忆插件（如基于阿里云Tablestore的mem0适配器）不仅能进行向量检索和BM25关键词匹配，还能识别并存储对话中可提取的事实——比如用户的姓名、技术偏好等。跨周期能力层面，还能实现跨Agent的记忆隔离和会话压缩后记忆不丢失。但作为普通用户来说，三层本地记忆体系已经满足90%的跨会话记忆需求。

🛠️ 小实验：观察Workspace中的记忆文件

执行以下命令，你可以看到记忆体系如何累积：

ls -la ~/.openclaw/workspace/memory/

每个文件都以日期命名，这就是你与Agent对话的历史记录。然后打开某个文件，查看内容格式：

cat ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md | head -20

你会看到每条对话的记录方式——顺便核实一下，Agent确实在向短期记忆文件写入“你告诉它的信息”。阅读第3课时你应该已经知道，这是AGENTS.md中那条“Memory is limited — if you want to remember something, WRITE IT TO A FILE”指令直接驱动的结果。

6.4 技能与执行层：连接数字与物理的抓手

一句话概括：技能与执行层是Agent的“双手和脚”——通过Skill知识注入和沙箱执行环境，让大模型具备实际操作文件、浏览器、操作系统和第三方API的能力，将“告诉你怎么做”转化为“我来替你完成”。

前三层解决了“接消息（Channel）、思考（Agent）和记忆（Memory）”的问题。第四层回答一个更实际的问题——如何在安全可控的前提下，让Agent真正动手操作我的电脑？

Skill的本质：不是代码，是“用户手册”

第10-12课会全面展开Skill开发，这里先概括核心：Skill不是传统意义上的插件代码包，它的主体是一个SKILL.md文件（Markdown格式），里面写满了指导AI如何使用某一个具体能力的操作说明书。

Skill的设计理念来自一个很巧妙的洞察：与其让开发者预先给大模型编写复杂工具函数并注册给Agent用，不如让Agent先“看说明书”再“照说明书操作”。OpenClaw在运行时将所有Skill的文档注入系统提示词，模型阅读Skill文档后立即获得调用底层工具的能力。

这种方式将“技能扩展”的职责分散给了更加模糊语义的人类文档，而不是底层的函数编程代码。与LangChain需要手写Python代码来编写工具相比，Skill的开发效率和质量对技术水平的要求更低，尤其适合非纯工程师背景的用户来撰写和扩展Agent能力。

Skill的注入与加载机制

当promptMode=full时，系统提示词的Skills部分会列出当前可用的Skill列表。提示词会指导模型：当遇到特定领域的任务时，使用read工具加载指定Skill的文档，之后就能根据文档中的操作步骤来调用底层工具（如filesystem、browser等）完成任务。

这种“按需查阅说明书”的设计，既让Agent动态获得了新的能力，又不会在每个对话里把几十个Skill的详细说明都塞进系统提示词（那会导致Token爆炸）。

MCP协议：更广阔的生态整合

从2025年底开始，MCP（Model Context Protocol） 正在成为连接LLM与外部数据源和工具的事实标准。MCP的核心价值在于：它为工具调用制定了统一的交互协议——工具的描述格式、参数结构、执行约定都遵循同一套规范，使得不同MCP Server提供的工具可以被Agent统一地发现和调用。

OpenClaw通过openclaw-mcp-adapter插件支持MCP生态。该插件在Gateway启动时连接到已配置的MCP Server，调用listTools()发现可用工具，然后将每个工具注册为OpenClaw原生Agent工具。此后Agent可以像调用本地工具一样调用这些MCP工具。

例如，通过花生壳MCP插件，OpenClaw可以自主建立内网穿透隧道来访问异地内网资源。

# mcp-adapter配置示例（openclaw.json）
{
  "plugins": {
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "filesystem",
              "transport": "stdio",
              "command": "npx",
              "args": ["-y", "@anthropic/mcp-filesystem", "/allowed/path"]
            }
          ]
        }
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["mcp-adapter"]
      }
    }
  }
}

安全沙箱：执行层的最后一道防线

在执行层，OpenClaw通过沙箱隔离确保Agent的操作不会危害主机系统。沙箱配置在openclaw.json的tools.sandbox部分：可以声明允许/拒绝的工具白名单（如deny: ["exec"]禁止执行Shell命令），限制文件系统访问范围等。

需要特别强调的是：即使你在系统提示词中告诉模型“不能执行危险操作”，模型也很可能因为提示词攻击、上下文污染或模型能力边界而违背这些禁止说明。唯一可靠的强制执行方法是硬性配置——在Gateway层通过tools.deny数组直接禁止某些工具的注册和使用，或为特定Agent指定不可调用的工具列表。安全是一个多层防御的问题，而Gateway的配置层面是最重要的一层。

6.5 四层之间的WebSocket通信协议

一句话概括：WebSocket是四层架构的“神经网络”——所有组件通过同一个ws://127.0.0.1:18789端口进行双向实时通信，承载了CLI交互、控制UI事件、Channel消息传递和Agent执行指令的全部数据流，是理解整个系统日志流向的总钥匙。

如果你已经尝试过通过Web界面管理OpenClaw，你其实已经在通过WebSocket与Gateway对话了——OpenClaw基于WebSocket构建了一个统一控制面和数据面的一体化设计。

具体来说，整个通信体系分为三路：

同进程函数调用：Gateway内部的Registry、Router、Dispatcher模块之间通过直接函数调用通信，延时极短
HTTP/IPC：跨进程访问（如命令行工具openclaw执行后读取状态）通过HTTP API调用Gateway的18789端口
WebSocket：这是交互的主力——CLI客户端、桌面应用程序、控制Web页面都通过同一个WebSocket地址与Gateway建立长连接，进行双向RPC通信和事件推送

当用户通过Channel（例如Telegram机器人）发送消息时，其完整通信路径如下：

Channel插件通过长轮询或Webhook接收到Telegram的消息JSON
Channel插件调用Gateway的消息路由API（内部函数调用），将“归一化后的消息”递交给Gateway
Gateway的消息路由器（Message Router） 根据消息的peerId，解析出对应的AgentId和SessionKey，解包找到目标Agent的标识
Gateway将消息放入该Agent的执行队列（Lane Queue），让Agent Runtime去进行推理
Agent运行期间生成的流式输出，通过WebSocket实时推送到已连接到Control UI的所有客户端上
最终执行结果通过Channel原路返回给用户

在OpenClaw的命令行或WebUI界面中，你可以在实时流中看到Agent思考的片段被打印出来——这背后就是通过WebSocket推送的。

🛠️ 动手尝试验证WebSocket连接

执行openclaw status --verbose，你将看到类似这样的输出：

$ openclaw status --verbose

Gateway: ✅ running (PID: 12345)
WebSocket: ws://127.0.0.1:18789 (role: operator)
Control UI: http://localhost:18789
Connected channels: telegram, slack, wecom
Active sessions: 7
Lane Queue: 3 pending

WebSocket: ws://127.0.0.1:18789 (role: operator)这一行说明当前CLI工具已经以operator身份连接到了Gateway的WebSocket服务器。如果你在WebUI中打开浏览器的开发者工具，切换到Network → WS选项卡，可以看到WebSocket的消息帧——其中包括Heartbeat心跳包、Agent运行时状态更新和执行报告等。这能帮你从“调试网络”的角度切入定位系统瓶颈。

6.6 架构设计的Unix哲学与模块化思想

一句话概括：OpenClaw的架构遵循“Do one thing and do it well”的Unix哲学——每一层专注解决一个问题，层与层之间通过标准化的协议通信，这种看似简单实则克制的设计，是其高稳定性和低心智负担的核心来源。

我们再来审视OpenClaw的四层分层核心功能：

Channel Layer：只负责协议转换，不关心内容
Gateway Layer：只负责路由和调度，不执行业务逻辑
Agent Layer：只负责思考和推理，不直接操作底层API
Skill Layer：只提供操作指引，让模型自行决定何时使用

这种设计导致的直接好处是：当你想增加一个新的IM平台，你只需要写一个Channel Plugin——Gateway的路由器、Agent的推理逻辑、Memory的存储系统，一行代码都不用改。这就是高层模块不依赖低层模块，而是都依赖抽象接口的依赖倒置原则在OpenClaw架构中的体现。

另一个“本可以不做但反而更强”的设计选择是：OpenClaw没有采用分布式微服务架构，而是坚定地选择了单体进程、本地优先的设计。对于一个个人或小团队自托管的AI助手，你并不需要300个微服务Node进程。把整个系统打包成一个npm模块，npm install -g一键完成安装，用户不需要理解Kubernetes、不需要搭建RabbitMQ、不需要维护配置中心。简洁，不意味着简陋，而是意味着“它在你不需要复杂的地方保持了极大的克制”。

这是Unix哲学中“”KISS原则（Keep It Simple, Stupid）”在AI操作系统层面的最高践行。正是这种当别人都在往“大而全”的方向走时，OpenClaw选择了“小而精”的路线，才能用极低的摩擦系数将AI Agent推向更广阔的用户群体。

6.7 一个完整实战：生产系统的消息执行全视角

为了帮助你彻底吸收这一章的四层抽象，我将用一个实际的终端场景来串联整个流程。

场景：你通过Telegram向OpenClaw发送一条指令：“帮我整理_{/Downloads文件夹，把所有.jpg文件移动到}/Pictures/JPG_Archive。”

逐层观察变化：

Channel层：Telegram渠道插件（Channel Plugin）接收到了这条入站消息，将它统一归一化为标准JSON格式，然后调用Gateway的内部API。
Gateway层：消息路由器根据发送者ID和渠道类型计算出Agent和会话，决定将任务送入Agent运行时的处理队列（Lane Queue）。
Agent（推理与认知）层：Agent加载Workspace中的配置文件。系统提示词中注入了AGENTS.md的安全规则（“文件删除前必须询问用户确认”）和SOUL.md、TOOLS.md等。模型推理后，认为“移动.jpg文件”不需要删除操作，可以自动执行，于是发出一系列工具调用请求。
Skill执行层：Skill文档描述文件系统操作方式的指导被模型查阅，模型调用filesystem工具逐一将匹配的文件移动到目标文件夹。

各层协作：Channel将结果从Agent层取回，通过Gateway的路由转回原来的渠道。用户在几秒钟后从Telegram获得一份完成报告。

6.8 本节小结

这节课是全套专栏中技术深度最强的一节，但也是承上启下的架构之锚。我们来完整复习一下核心知识：

四层架构：Channel Layer负责消息接入和协议归一化；Gateway Layer是中枢调度中心，管理消息路由、会话、认证和定时任务；Agent Layer负责系统提示词组装、记忆注入与ReAct推理循环；Skill & Execution Layer提供安全沙箱执行环境和MCP生态集成能力。
Gateway作为控制平面：单进程常驻运行于18789端口，同时承载WebSocket、HTTP和UI服务，是所有消息通信的唯一进出节点。它的健康直接影响整个Agent系统的稳定性。
Agent认知层：通过注入式系统提示词替代模型默认行为，支持三级记忆分层（短期→长期→向量检索）和无缝的MCP工具生态扩展。
四层通信基于WebSocket：通过同一个连接管理CLI、UI、Channel消息和设备配对请求——一体化的通信设计最大化降低了跨组件调用延迟。
Unix哲学的内化：坚持模块解耦、单一职责、本地优先，以用户可接受的简洁度带来最低的上手门槛与最高的长期可控性。

6.9 课后习题

1. 四层故障定位演练

请在你目前运行OpenClaw的环境里模拟以下三种故障场景，依次写出如何推断故障出在哪一层：

场景A：往Telegram Bot发送消息，Bot显示“已读”，但是Agent没有任何回应。
场景B：文件批量重命名的任务在日志里显示已经执行，但磁盘上的文件没有任何改动。
场景C：Agent回复你的消息很慢，但日志显示模型调用的网络延迟很低，平均仅有200ms。

2. 会话ID与信息隔离分析

参考本章5.4节从Gateway获取会话标识的方法，假设你在per-channel-peer会话隔离模式下运行OpenClaw，有两个用户在同一个群里和Agent对话。用理论分析，为什么Agent能够正确地区分两个用户的指令并与他们各自独立交互？写出你在日志中看到的sessionKey的差异。

3. 开源框架选型对比

请与LangChain和AutoGPT进行横向对比，从以下维度梳理OpenClaw的四层架构相比其他两种框架的主逻辑区别（可以画对照表）：

学习与上手曲线
生产级稳定性可靠性
工具扩展体系的复杂度
跨会话记忆能力

4. 记忆系统观察实验

在你的OpenClaw运行24小时后，用ls -lh ~/.openclaw/workspace/memory/执行查看。估计一下短期日志的总存储增长趋势。查阅OpenClaw文档，说明如果我想配置自动清理超过30天的旧记忆日志，应该在哪一个配置项里进行设置？

5. WebSocket抓包练习

打开OpenClaw的Web控制界面（http://localhost:18789），在浏览器中打开开发者工具的Network选项卡，切换到WS页签。观察WebSocket消息帧的类型——尝试找到session_status、agent:run、heartbeat这几种帧类型，并说明每种帧在四层架构中大体对应哪些模块的通信。

🔗《30节课精通 OpenClaw》系列课程导航

去订阅

第一部分（第1-5课）：基础认知与入门部署——解决“这是什么、怎么搭建”的问题。
第二部分（第6-10课）：核心原理深度剖析——解决“底层怎么工作”的问题。
第三部分（第11-15课）：应用场景与平台集成——解决“能用来做什么”的问题。
第四部分（第16-21课）：技能开发与定制扩展——解决“如何自己扩能力”的问题。
第五部分（第22-26课）：高级特性与性能优化——解决“怎么用得更好”的问题。
第六部分（第27-30课）：安全、运维与生态进阶——解决“如何安全可靠地规模化”的问题。