OpenClaw不只是一个聊天机器人，而是一个能连接多个消息平台、调用各种工具、维护长期记忆的完整系统。很多问题（消息没送达、上下文丢了、工具调用失败）都可以通过理解它的架构来快速定位。

三层架构

OpenClaw的设计遵循直觉的三层模型：

层级	角色	功能
Channel Layer	系统的"感官"	对接各种消息平台（WhatsApp、Telegram、Slack、Discord等），把不同协议的消息标准化为统一内部格式
Brain Layer	系统的"思考中枢"	运行Agent Runtime，执行ReAct循环：接收→推理→决策→调用工具→观察结果→继续推理
Body Layer	系统的"四肢"	浏览器操作、文件系统访问、Shell命令、MCP Servers对接、自定义Skills

工作流：Channel收消息 → Brain想办法 → Body干活 → Brain整理结果 → Channel回消息

核心概念

Gateway：神经中枢

Gateway是整个系统的"神经系统"——一个WebSocket服务器，负责消息路由和会话管理。它是Channel和Agent之间的桥梁。

你可以把Gateway理解成电话总机：

• 来电（用户消息）进来后，根据规则决定转给哪个分机（Agent）
• 然后把回复转回给来电者
• 一个Gateway可以同时管理多个Agent

Agent：思考和行动的主体

Agent是OpenClaw中执行AI操作循环的核心组件：

职责	说明
组装上下文	把会话历史、记忆、技能说明等拼装成prompt
调用模型	把上下文发给LLM，获取推理结果
执行工具	根据模型决策调用相应工具
持久化状态	保存对话历史和学到的记忆

一个Gateway可以运行多个Agent，每个有独立的身份（SOUL.md）、工具集（Skills）和工作空间。

Session：对话的上下文容器

Session维护对话上下文和历史。每当用户通过Channel和Agent交互，系统就会创建独立的Session。

Session Key格式：workspace:channel:userId，确保不同平台、不同用户的对话完全隔离。

Session内部维护完整对话历史，通过智能机制（裁剪工具结果、压缩长对话）控制上下文长度，避免token爆炸。

Channel：连接世界的通道

Channel是消息平台的适配器，每个Channel对应一个具体平台：

• 接收该平台的原始消息
• 转换为OpenClaw内部的标准格式
• 把Agent的回复转换回平台特定格式并发送

系统通过**Bindings（消息绑定）**决定"来自哪个Channel的哪个用户的消息，应该由哪个Agent处理"。

它们如何协同

用户发送消息（Telegram）
    ↓
Channel接收消息，标准化
    ↓
Gateway根据Bindings找到对应Agent
    ↓
Agent查找或创建Session
    ↓
Agent在Session上下文中执行ReAct循环
    ↓
结果通过Gateway → Channel返回用户

一个Agent可以同时服务多个Channel的多个用户，每个用户各有隔离的Session。

Session深入

Session是最值得深入理解的概念，很多"奇怪行为"都和它有关。

生命周期

触发方式	说明
每日重置	默认凌晨4:00重置，开启新的一天
空闲重置	长时间没有交互后自动重置
手动重置	用户发送/new命令主动开启新会话

重置意味着对话历史清空，Agent从零开始——但重要信息已经写入了Memory，不会真正"失忆"。

隔离级别

通过dmScope配置不同粒度：

配置	效果
main（默认）	所有Channel的所有私聊共用一个Session
per-peer	每个用户一个独立Session，跨Channel共享
per-channel-peer（推荐）	每个Channel+用户组合一个独立Session

Steering Queue：消息转向

当Agent正在处理消息时又有新消息进来，系统通过Steering Queue决定如何处理：

模式	行为
steer（默认）	将新消息注入当前运行的Agent，让模型在下一个推理边界看到它
queue	旧版逐个注入模式
steer-backlog	注入当前运行，同时保留一份给后续followup
followup	不打扰当前运行，排队等它跑完再处理
collect	等当前运行结束后，将多等待消息合并成一个followup回合
interrupt	中断当前运行，立刻处理最新消息

串行保证：同一Session内的消息永远不会并行处理，避免并发读写文件导致的竞态问题。稍微慢一点，但换来了确定性和可调试性。

Sub-agent：后台工作者

有些任务很耗时（深度研究、大量文件处理），如果在主Session中执行，用户就要干等着。

Sub-agent从当前Session中派生出来，运行在独立的隔离Session中，完成后向请求方报告结果。

你可以把它理解成主线程派出去的工作线程：主线程继续响应用户，工作线程在后台默默干活。

扩展机制

Skills：可插拔的能力

每个Skill本质上是结构化的知识文件（Markdown），告诉Agent"遇到某类任务时该怎么做"：

• 可以热加载，不需要重启Gateway
• 社区通过ClawHub共享和复用

Memory：跨会话的持久记忆

Memory解决了"Session重置后Agent就失忆"的问题。核心文件是MEMORY.md，存储跨会话的持久事实和偏好。

一个优雅设计：Memory对人类可审计——你可以直接打开MEMORY.md看Agent记住了什么，甚至手动编辑。

注意区分：

• Memory = 持久记忆（MEMORY.md）
• Session History = 当前会话的对话记录

Session重置会清空对话历史，但Memory中的内容会保留。

SOUL.md：人格定义

SOUL.md定义Agent的人格和行为哲学。OpenClaw区分"做什么"（AGENTS.md）和"是谁"（SOUL.md）——SOUL.md在每次会话启动时被注入系统prompt，确保Agent保持一致的沟通风格和价值观。

Bindings：多Agent路由

Bindings是将消息路由到不同Agent的确定映射规则：

匹配条件 (channel, accountId, peer, guild/team) → agentId

遵循most-specific wins原则：peer级别匹配优先于channel级别。

这让多Agent架构成为可能——你可以同时运行"工作助手"和"生活管家"，每个有独立的workspace、SOUL.md和session存储。

总结

概念	角色
三层模型	Channel管通信，Brain管思考，Body管执行
Gateway	神经中枢，串联一切
Agent	执行单元，跑ReAct循环
Session	上下文容器，提供隔离和串行保证
Channel	适配器，连接各种消息平台
Skills	能力扩展
Memory	持久记忆
SOUL.md	人格定义
Bindings	消息路由

理解了这些概念和它们之间的关系，再去使用和调试OpenClaw会顺畅很多。