OpenClaw 的核心组件有六个：Gateway（控制平面）、Channels（渠道适配器）、Agent Runtime（决策大脑）、Tools/Skills（执行手脚）、Memory（记忆系统）、Session Router（会话路由）。它们的关系是典型的轮毂-辐条结构——Gateway 是中心轮毂，所有渠道与工具执行都是辐条，消息从渠道进来统一汇入 Gateway，由会话路由器分发给对应的 Agent 工作区，Agent 在推理循环中按需调用工具、检索记忆，最后把结果沿原路返回。
一、六个核心组件各管什么
| 组件 | 职责 | 关键实现 |
|---|---|---|
| Gateway | 常驻进程，消息路由、会话管理、进程调度 | 单进程 WebSocket 服务器，默认 127.0.0.1:18789 |
| Channels | 对接各聊天平台，收发与格式适配 | 26+ 渠道适配器，统一 adapter 接口 |
| Agent Runtime | 决策推理与工具调用循环 | 内置 Pi Agent Core，四阶段循环 |
| Tools / Skills | 外部能力入口 | shell、fs、browser、MCP 等工具 + SKILL.md 技能 |
| Memory | 跨会话知识持久化与召回 | MEMORY.md + 每日日志 + 混合检索 |
| Session Router | 消息按会话键分发与排队 | 层级化 session key + 车道队列并发控制 |
Gateway 是唯一长期运行的进程，其余组件随消息按需激活。这种”单进程 + 事件驱动”的设计让部署退化为一个进程、一份配置，不需要微服务编排。
二、组件之间的协作关系
下面这张文字图描述了一条消息在组件间的流转方向：
IM 消息（Telegram / 微信 / WhatsApp ...）
│
▼
Channels 适配器 ──标准化为内部消息──► Gateway
│
▼
Session Router（按 session key 定位）
│
▼
Agent Runtime（Pi Agent Core）
│ │ │
调用 Tools ◄──┘ │ └──► 检索 Memory
执行结果回填 │
▼
LLM 推理（模型可替换）
│
▼
结果沿原通道返回（Channel 回复）Gateway 与 Agent 不直接耦合：渠道差异收敛在 adapter 层，新增聊天平台不改 Agent 代码；Agent 与模型解耦，换模型只改配置。三者之间的松耦合是 OpenClaw 能同时支撑”20 多个渠道 + 任意模型 + 社区技能”的结构前提。
2.1 从三层视角看
- 第一层 Gateway：循环系统，管消息进出、会话定位、事件分发；
- 第二层 Agent Runtime：神经系统，跑 ReAct（推理-行动-观察）循环，做工具调用与上下文管理；
- 第三层 Memory + Skills：知识与能力系统，记忆分层存储，技能按需加载。
三、两条关键机制：会话路由与车道队列
3.1 层级化会话键
每个会话有一个层级化的 session key，决定了它归属于哪个 Agent、哪个渠道、哪个对话对象。形如：
agent:main:main # 主 Agent 操作者主会话
agent:main:whatsapp:direct:+15551234567 # WhatsApp 私聊（按渠道+联系人隔离）
agent:main:telegram:group:-10012345678 # Telegram 群聊
agent:work:slack:direct:U0123ABC # 子 Agent 的 Slack 私聊会话状态以 append-only JSONL 持久化到 ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl，支持断线恢复与对话分支回溯。
3.2 车道队列保证”一会话一执行”
并发控制是 OpenClaw 的细节亮点。队列按车道（lane）隔离：同一会话严格串行，主聊天与心跳各占一条并发通道，子 Agent 与嵌套工具调用并行度更高。核心保证只有一句话：”同一时刻，一个会话只允许一次 Agent 运行。”用户还能用 /queue 命令动态切换消息合并模式（steer 立即介入 / followup 排队 / collect 合并处理）。
四、配置文件即组件
OpenClaw 把人格、规则、记忆都做成工作区里的 Markdown 文件，改行为不用改源码：
| 文件 | 作用 |
|---|---|
| SOUL.md | 人格、边界、语调 |
| AGENTS.md | 操作指令与记忆规则 |
| USER.md | 用户资料与偏好 |
| MEMORY.md | 长期记忆与习得模式 |
| openclaw.json | 网关、模型、渠道、沙箱总配置 |
这些文件在每次推理时被组装进系统提示词，大文件自动裁剪并加截断标记。记忆不达标时，模型会先把可持久信息写进每日日志，再整理进 MEMORY.md——记忆增长是透明的、可读的。
五、组件链路自检五步
怀疑某个组件没接上时，按顺序排查：
- 跑
openclaw status，确认 Gateway 进程存活且 18789 端口在监听； - 用 WebChat 发一条简单消息，确认消息穿过 Channel 进入 Gateway；
- 打开
~/.openclaw/agents/<agentId>/sessions/，确认对应会话 JSONL 已生成； - 下发一个带工具调用的任务，检查工具执行结果是否成功回填给模型；
- 改动 SOUL.md 后重发消息，确认人格文件在下一轮推理中重新生效。
常见问题（FAQ）
Q1：Gateway 挂了会怎样？
所有消息停摆，但已落盘的会话与记忆不丢，重启后恢复。
Q2：多个 Agent 能共享一套记忆吗？
默认各 Agent 隔离工作区，需显式配置共享或跨 Agent 迁移。
Q3：加一个新聊天渠道要改 Agent 代码吗？
不用。渠道差异收敛在适配层，新增 adapter 即可接入。
