OpenClaw 架构学习指南
本目录是面向开发者的 OpenClaw 架构学习文档。目标是帮助你：
- 掌握阅读 OpenClaw 代码所需的 TypeScript 模式
- 理解 OpenClaw 的整体业务架构
- 能从头到尾跟踪一条消息的完整生命周期
- 代码版本: 2026.3.13
学习路径
按顺序阅读效果最佳：
| 序号 | 文档 | 内容 | 阅读时间 |
|---|---|---|---|
| 00 | 项目地图 | 目录结构、关键文件速查 | 5 min |
| 01 | 代码模式速查 | 读代码前必知的 TypeScript 模式 | 20 min |
| 02 | 整体架构 | OpenClaw 是什么、核心模块、数据流 | 15 min |
| 03 | 消息全链路 | 一条消息从 IM 到回复的完整旅程 | 15 min |
| 04 | 设计原理 | 关键设计决策及其原因 | 15 min |
深入模块（按需阅读）：
| 文档 | 内容 |
|---|---|
| 05. Gateway 深度解析 | 网关启动、消息分发、24x7 运行 |
| 06. Agent 运行机制 | AI 推理循环、工具调用、故障转移 |
| 07. 会话管理 | Session 生命周期、存储、隔离 |
| 08. 记忆系统 | 长期记忆的存储与检索 |
| 09. 并发控制 | 队列模式、消息去重 |
| 10. 安全架构 | 认证、授权、沙箱 |
消息流转逐步跟踪（10 步详细分析）：
| 步骤 | 标题 | 关键代码入口 |
|---|---|---|
| 01 | Gateway 启动 | runGatewayCommand() |
| 02 | 接收消息 | createInboundEnvelope() |
| 03 | 路由决策 | resolveAgentRoute() |
| 04 | 上下文准备 | prepareReplyContext() |
| 05 | 回复生成 | runGetReply() |
| 06 | Agent 调度 | runReplyAgent() |
| 07 | 容错执行 | runAgentTurnWithFallback() |
| 08 | AI 调用 | runEmbeddedPiAgent() |
| 09 | 工具调用循环 | runEmbeddedAttempt() |
| 10 | 回复发送 | deliverReplies() |
架构总览
用户 (WhatsApp / Telegram / Discord / ...)
│
▼
渠道适配器 (Channel Plugin) ← 各平台消息标准化
│
▼
Gateway (WebSocket 服务) ← 路由、会话管理、状态持久化
│
▼
Agent 运行时 ← 上下文组装 → AI 模型调用 → 工具执行
│
▼
回复分发 ← 格式化 → 发送回渠道