Day 01 / 共 20 天 · 第 1 周 入门与全景
项目全景：个人 AI 助理
欢迎来到 OpenClaw 🦞。第一天先建立全局地图：它是什么、由哪几大块组成、一条消息怎么在系统里流转。今天不抠代码细节，只求"看懂它长什么样"。这张地图会贯穿全部 20 天——之后每天开头的"进度定位条"都会点亮你所在的格子。
📍 你在整门课的位置（第 1 周 · 入门与全景）
Day1 全景→
Day2 入口启动→
Day3 Gateway→
Day4 消息旅程→
Day5 配置·
W2 大脑·
W3 技能/渠道·
W4 安全/部署
L01
它是什么
🤔 痛点：你已经有一堆聊天软件，为什么还要它？
你想要一个"随叫随到"的 AI 助理：出门在 Telegram 问它天气、上班在 Slack 让它查日程、回家用 iMessage 让它订闹钟。可现在的 AI 网站要你单独开一个网页/App，还得来回复制粘贴——它活在"另一个地方"，而不是你本来就在用的聊天窗口里。
💡 本质：把 AI 助理"住进"你已有的聊天软件
OpenClaw 不做新聊天界面，而是当一个后台服务：你在任意已接入的渠道发消息，它在后台想清楚、调工具、把答复送回同一个渠道。本质就像给你的所有聊天软件装了一个"共享的大脑"，你在哪发它就在哪答。
OpenClaw 是一个你自己部署、单用户的个人 AI 助理。它不做一个新聊天网站，而是"住进"你已经在用的聊天软件——你在 Telegram/Slack/Discord/飞书等发消息，它在后台想清楚、调工具、把答复送回同一个渠道。还能说会听、渲染实时画布（Canvas）。
和"框架/库"不一样——它是"成品"
你之前学的 eino、LangGraph、crewAI 都是"给开发者造 Agent 的工具箱"。OpenClaw 不同：它本身就是一个能用的产品——装上、配好、它就在你的微信生态里当助理。所以读它的源码，学的不只是"Agent 怎么实现"，更是"怎么把一个 Agent 变成可靠、安全、随处可达的真实产品"——多渠道接入、故障转移、安全防护、原生 App、一键部署，这些"引擎之外"的工程，才是它 90% 的代码所在。它主体用 TypeScript 写（6000+ 文件），外加 macOS/iOS/Android 原生 App。
L02
五件套
把 OpenClaw 拆开，就是五大块：
| 组成 | 作用 | 本课覆盖 |
|---|---|---|
| 🌐 Channels 渠道 | 接入几十种聊天平台，消息进/出 | Day 13-15 |
| 🎛️ Gateway 控制平面 | 把渠道和大脑粘起来、路由、管生命周期 | Day 03-04 |
| 🧠 Agent 大脑 | LLM + 工具循环（内嵌 Pi），想+做 | Day 06-10 |
| 🧩 Skills / Extensions | 技能与扩展，给助理加本领 | Day 11-12 |
| 🛡️ Sandbox / Security | 沙箱安全执行、防护 | Day 16-17 |
读法：记住这五块和它们的分工，整个系列就有了骨架。核心流向：渠道进 → Gateway 编排 → 大脑想+做（用技能，在沙箱里）→ 渠道出。外加原生 App（Day 18）、构建部署（Day 19-20）。
📝 举个例子：这五块在源码里能摸到
🌐 渠道 →
src/telegram/、src/slack/、extensions/matrix/（README 列了 20+ 平台）；🎛️ Gateway → src/gateway/（boot.ts 启动）；🧠 大脑 → src/agents/；🧩 技能 → skills/（实测 ls skills/ | wc -l = 52 个）；🛡️ 安全 → src/security/（audit.ts 等）。L03
Gateway 控制平面
README 有句关键话："The Gateway is just the control plane — the product is the assistant."（网关只是控制平面，产品是助理本身。）
"控制平面"是什么？
借用网络领域的词：控制平面（control plane）= 负责"协调、路由、管理"，但不亲自处理业务内容的那一层。OpenClaw 的 Gateway 就是这样——它不生成回复（那是大脑的事），也不懂 Telegram 协议细节（那是渠道的事），它只做"粘合"：把各渠道连接管起来、把进来的消息路由给对的 Agent、把回复送回对的渠道、管会话生命周期。好比公司前台：不做具体业务，但负责把访客（消息）领到对的部门（Agent），再把结果送出去。把"协调"独立成一层，是复杂系统解耦的关键——渠道、大脑各自演化，互不干扰。
L04
monorepo 目录地图
仓库根（pnpm workspace，Day 19）主要目录：
| 目录 | 内容 |
|---|---|
src/ | 主程序：gateway/(控制面) agents/(大脑) channels/(渠道抽象) auto-reply/(消息处理) memory/ security/ cli/ config/ … |
extensions/ | 各平台渠道 + 能力扩展（telegram/slack/discord/飞书/ollama…） |
skills/ | 52 个技能（SKILL.md） |
apps/ + Swabble/ | macOS/iOS/Android 原生 App（Swift/Kotlin） |
ui/ | Web 控制台 |
| 根文件 | openclaw.mjs(入口) Dockerfile* docker-compose.yml AGENTS.md SECURITY.md |
读法：顶层专属目录
src/telegram/、src/slack/、src/discord/ 放各渠道的"重实现"，而 extensions/<平台>/ 放"装配"（Day 13-14 会看清这层关系）。先混个脸熟，用到再深入。L05
一条消息的旅程（预览）
提前把主线剧透一遍（Day 04 详讲）：
# 你在 Telegram 发 "北京天气？"
1. 渠道监听收到 → 归一化成统一 MsgContext（src/telegram/... → finalizeInboundContext）
2. Gateway 路由：这消息该由哪个 agent/会话处理（src/routing/resolve-route.ts）
3. Agent 大脑：喂给 LLM（内嵌 Pi），模型决定调 weather 工具 → 执行 → 拿结果再想
4. 生成回复 → 出站投递按 OriginatingChannel 送回 Telegram（src/infra/outbound/deliver.ts）
# 你在 Telegram 收到 "北京今天晴，25°C"一条消息的旅程：进 → 路由 → 想+做（可多轮）→ 出。这条主轴后面每一周都在放大其中一段。
🚶 第一人称之旅：现在你就是那条"北京天气？"
你从 Telegram 被渠道监听捞起来 → 被翻译成统一格式（脱下"Telegram 制服"换上"通用工服"）→ 撞到 Gateway 路由这个门卫，它查名单决定把你交给哪个 agent → 进了大脑，大脑觉得"得查天气"，派出 weather 工具，拿到结果又想了一轮 → 生成答复，最后按你身上贴的"回执地址（OriginatingChannel=telegram）"把你送回 Telegram。旅程闭环！
读法：这条"进 → 路由 → 想+做 → 出"的链路是理解 OpenClaw 的主轴。后面每一周都是在放大这条链路的某一段。今天只需记住这个大流程。
L06
内嵌 Pi 内核（重要预告）
一个会反复强调的事实：OpenClaw 不自己实现 LLM 调用和 ReAct 循环——它内嵌了第三方 Agent 框架 Pi（
所以本课学的重点不是"Agent 引擎怎么写"（那是 Pi），而是"OpenClaw 怎么把 Pi 包装成可靠的个人助理"——故障转移、鉴权轮换、技能、记忆、渠道、安全。这个区分（引擎 vs 产品外壳）是理解整个项目的钥匙，Day 06 会正式展开。
@mariozechner/pi-*），自己做"编排外壳"。所以本课学的重点不是"Agent 引擎怎么写"（那是 Pi），而是"OpenClaw 怎么把 Pi 包装成可靠的个人助理"——故障转移、鉴权轮换、技能、记忆、渠道、安全。这个区分（引擎 vs 产品外壳）是理解整个项目的钥匙，Day 06 会正式展开。
⚠️ 常见误解：很多人以为"OpenClaw = 又一个套壳 ChatGPT 的聊天机器人"。其实它连"和大模型对话"这件事都外包给了 Pi——它真正的价值是把一个 AI 引擎变成"住在你所有聊天软件里、7×24 不掉线、还安全"的产品，这层工程才是 6000+ 文件的主体。
🗣️ 一句话复述（讲给朋友听）
OpenClaw 就是"你自己家里养的一个 AI 管家：你在微信/Telegram 喊它，它在后台用大模型的脑子想清楚、动手办事，再回到同一个聊天窗口答复你"。
L07
20 天路线
- 第 1 周（入门与全景）：项目全景 → 入口启动 → Gateway → 消息旅程 → 配置。
- 第 2 周（Agent 大脑）：Pi 内核 → 故障转移 → 执行循环 → 提示词 → 记忆。
- 第 3 周（技能与渠道）：skills → extensions → 渠道抽象 → 渠道实现 → 归一化/语音/Canvas。
- 第 4 周（运行时/安全/部署）：沙箱 → 安全 → 原生 App → 构建 SDK → 部署收官（七框架对比）。
读法：由表及里：先会用/看懂全貌（W1）→ 深入大脑（W2）→ 扩展与渠道（W3）→ 底层工程（W4）。每天 8 讲、约 30 分钟，跟着"今日小结 + 动手"收尾。
L08
今日小结 + 动手
🧠 今天你应该能回答
- OpenClaw 是"框架"还是"产品"？和 LangGraph 等有何本质不同？
- 五件套分别是什么？核心流向是什么？
- "控制平面"是什么意思？Gateway 管什么、不管什么？
- 一条消息的四步旅程？
- OpenClaw 自己写 LLM 循环吗？（关键预告）
🎵 记忆口诀（把五件套 + 主线记牢）
"渠道进、网关分、大脑想、技能干、沙箱护、原路返"——六个短句，把五件套和消息主线一次记住。之后每天都在给这句口诀里的某个字"放大特写"。
✋ 动手
cd /Users/bitmart/work/codes/github/openclaw
ls src/ # 主程序目录
ls extensions/ | head -20 # 渠道/能力扩展
head -40 README.md # 项目自我介绍
head -20 VISION.md # 愿景明天预告 · Day 02：入口与启动流程——
openclaw.mjs 怎么检查 Node 版本、加载 dist/entry.js、走 Commander CLI 分发；openclaw onboard 向导怎么引导你配置。