00. 教程总览

先说这套教程解决什么

OpenClaw 这类项目，最容易看乱。

它不是一个单纯的聊天机器人，也不是一个普通 CLI。它更像一个个人 AI 助手运行时：CLI 负责本地操作，Gateway 负责常驻和多渠道消息，Agent Runtime 负责模型与工具循环，Channels 负责 Telegram、Feishu、WhatsApp 等入口，Skills、Cron、Plugins 又把它扩展成长期系统。

如果只看 README，你能知道怎么安装；但想二开或排障，真正的问题是：一次消息到底从哪里进来，怎么进入 Agent，工具和会话状态又存在哪里。

这套教程按一条实际路线来写：先跑起来，再看入口，再看核心运行时，最后看扩展和二开。

这套教程分成五段

00-05 入门和地图
06-09 Agent Runtime 主线
10-14 Gateway / Channels / Sessions / Cron
15-18 Skills / Plugins / MCP / 安全
19-20 排障、二开和总结

读者不需要一开始就把所有目录背下来。先知道每一层解决什么问题，后面读源码才不会迷路。

如果你只是想先用起来

看这几篇：

01. OpenClaw 是什么
02. 快速开始
03. 配置和模型

目标是能安装、启动 Gateway、知道状态目录在哪里、能发起一次 agent 消息。

如果你想二次开发

重点看：

04. 项目结构
05. CLI 入口
06-09 Agent Runtime
10-14 Gateway 和自动化
15-18 扩展、安全、调试

源码篇不要只看概念。OpenClaw 是 TypeScript 大仓库，很多能力分层很细：src/agents/、src/channels/、src/gateway/、src/config/、src/plugins/ 都有自己的边界。

本教程基于哪些资料

本教程核对了：

https://github.com/openclaw/openclaw
README.md
docs/openclaw-agent-runtime.md
docs/agent-runtime-architecture.md
package.json
openclaw.mjs
src/agents/
src/config/
src/gateway/
src/channels/
src/cron/
src/plugins/
src/mcp/

如果 OpenClaw 后续版本改目录，优先以官方仓库和官方文档为准。

完整目录

00. 教程总览
01. OpenClaw 是什么
02. 快速开始
03. 配置和模型
04. 项目结构
05. CLI 入口
06. Agent Runtime 主循环
07. 模型 Provider 与流式响应
08. Tools 原理
09. Tools 源码
10. Gateway：常驻控制平面
11. Channels：多平台消息入口
12. Sessions：会话和状态
13. Cron：定时任务
14. Skills：过程知识
15. Plugins：扩展机制
16. MCP：外部工具接入
17. 安全边界
18. 调试与排障
19. 二开路线
20. 总结

看到最后应该能做什么

读完后，至少应该能做到：

• 知道 OpenClaw 适合解决什么问题；
• 在本地安装并启动 Gateway；
• 找到配置、状态、会话和 workspace；
• 看懂 CLI、Gateway、Agent Runtime 的分层；
• 知道要改 channel、tool、skill、plugin 时分别看哪里；
• 遇到问题时能按层排查，而不是盲猜。