1. 本期目标
前两期分别介绍了 OpenClaw 的项目定位和源码运行方式。到目前为止，我们已经知道：
OpenClaw 不是一个简单的聊天机器人，
而是一个本地优先、多渠道、可调用工具、可扩展技能、带安全隔离机制的个人 AI 助手系统。这一期开始正式看仓库结构。
对于 OpenClaw 这种工程规模较大的项目，一开始不要直接钻进某个文件逐行看。更合理的方式是先建立目录地图，知道每个目录大概负责什么，再逐步进入核心链路。OpenClaw 仓库根目录下包含 apps、config、deploy、docs、extensions、packages、qa、scripts、security、skills、src、test、ui 等目录。(GitHub)
本期主要解决几个问题：
1. OpenClaw 根目录下有哪些重要目录？
2. src、extensions、skills、packages、apps、ui 分别负责什么？
3. docs、security、test、qa、scripts 这类目录如何辅助源码学习？
4. 初学者应该从哪个目录开始看？
5. 后续源码解析应该按照什么目录顺序推进？2. 为什么要先看目录结构？
源码解析最怕一开始就陷入细节。
比如一上来就打开 src 里的某个文件，可能会看到大量命令、事件、会话、工具、配置相关代码。没有整体地图时，很容易不知道这个文件在系统中处于什么位置。
所以，这一期的目标不是把每个文件都讲完，而是先建立一个大致判断：
哪些目录是核心运行时？
哪些目录是扩展能力？
哪些目录是技能库？
哪些目录是前端或移动端？
哪些目录是配置、部署、安全和测试？有了这个判断，后面再读 CLI、Gateway、Channel、Agent、Tools、Skills、Sandbox，就不会迷路。
3. 根目录整体印象
从仓库根目录看，OpenClaw 至少可以分成六类内容：
第一类：核心运行时代码
src
第二类：扩展与插件
extensions
packages
第三类：技能和能力模板
skills
第四类：应用端和界面
apps
ui
第五类：工程支持
config
deploy
scripts
docs
第六类：质量与安全
test
qa
security这种目录结构说明 OpenClaw 不是一个"单后端 + 单前端"的简单项目，而是一个包含核心运行时、插件系统、技能系统、多端应用、控制界面、安全规则和测试体系的综合 Agent 工程。根目录也包含 openclaw.mjs、package.json、pnpm-workspace.yaml、多个 tsconfig 文件和构建配置文件，这说明它是一个以 Node / TypeScript / pnpm workspace 为核心组织方式的项目。(GitHub)
4. src：核心运行时代码
src 是后续源码解析最重要的目录之一。
从 src 目录列表可以看到，它下面包含 agents、channels、chat、cli、commands、config、cron、daemon 等多个子目录。(GitHub)
可以先这样理解：
src
├─ cli / commands 命令行入口和命令实现
├─ daemon Gateway 后台运行相关逻辑
├─ config 配置加载与解析
├─ agents Agent 相关逻辑
├─ channels 渠道接入相关逻辑
├─ chat 对话处理相关逻辑
├─ cron 定时任务相关逻辑
└─ 其他运行时模块src 的地位类似于整个项目的"大脑和神经系统"。
后续我们分析：
openclaw 命令如何解析？
Gateway 如何启动？
用户消息如何进入 Agent？
session 如何创建和保存？
模型如何被调用？
工具和技能如何被加入上下文？这些问题都绕不开 src。
5. 初学者如何看 src？
src 不适合一次性全部读完。
建议按照主链路来读：
第一步：看 cli / commands
先找到 openclaw 命令从哪里进入。
第二步：看 daemon / gateway 相关代码
理解 Gateway 如何启动和常驻。
第三步：看 config
理解 openclaw.json 和默认配置如何加载。
第四步：看 agents / chat
理解 Agent 如何处理用户消息。
第五步：看 channels
理解外部消息平台如何接入。
第六步：再看 tools、skills、sessions、cron 等扩展能力。也就是说，src 的阅读方式不是"按字母顺序看目录"，而是围绕这条链路：
CLI
↓
Gateway
↓
Config / Session
↓
Agent
↓
Model / Tools / Skills
↓
Response6. extensions：插件与外部能力扩展
extensions 是 OpenClaw 很有特点的目录。
从 extensions 目录列表可以看到，里面包含很多扩展项，例如 active-memory、admin-http-rpc、alibaba、amazon-bedrock、anthropic、azure-speech、browser 等。(GitHub)
这个目录说明 OpenClaw 的很多能力不是全部硬编码在核心运行时里，而是通过 extension 的方式组织
可以先分成几类理解：
模型提供商扩展：
anthropic
amazon-bedrock
alibaba
byteplus 等
语音或多媒体扩展：
azure-speech 等
工具或系统能力扩展：
browser
active-memory
admin-http-rpc 等
其他平台或服务扩展：
根据目录名称继续展开分析。这种设计的好处是：
核心运行时负责统一调度；
具体模型、工具、平台能力通过 extensions 扩展。后续分析模型调用链路、工具系统、Channel 接入时，extensions 都会是重点目录。
7. extensions 和 src 的关系
可以这样理解二者关系：
src：
定义 OpenClaw 的核心运行机制。
extensions：
给核心机制提供可插拔能力。举个例子：
src 负责说明：
模型调用需要经过什么抽象接口。
extensions 负责实现：
Anthropic 怎么调；
Amazon Bedrock 怎么调；
浏览器工具怎么用；
语音服务怎么接。这和很多大型框架的设计类似：核心框架保持稳定，具体能力以插件或扩展形式接入。
这也解释了为什么 OpenClaw 支持很多模型、渠道和工具能力。它不是每新增一个能力就改一堆核心代码，而是通过扩展目录把能力模块化。
8. packages：共享包和 SDK
packages 目录目前可以看到 memory-host-sdk、plugin-package-contract、plugin-sdk、sdk 等子目录。(GitHub)
从命名可以看出，这个目录更偏向"可复用包"和"接口契约"。
可以先这样理解：
packages/sdk：
可能面向外部或内部调用 OpenClaw 能力的 SDK。
packages/plugin-sdk：
插件开发相关 SDK。
packages/plugin-package-contract：
插件包的结构或协议约束。
packages/memory-host-sdk：
记忆宿主相关的 SDK 或接口。这里暂时不需要一开始深入。
对于初学者来说，packages 的意义是：
当你看到 src 或 extensions 中引用某些 SDK、类型、接口时，
可以回到 packages 里找这些公共抽象的定义。所以 packages 更像是支撑其他模块的"公共基础层"。
9. skills：内置技能库
skills 是 OpenClaw 的另一个重点目录。
从目录列表可以看到，它包含很多内置技能，例如 1password、apple-notes、apple-reminders、bear-notes、blogwatcher、canvas、coding-agent、diagram-maker、discord、gh-issues 等。(GitHub)
这个目录非常值得单独分析。
因为 Skills 体现的是：
OpenClaw 不只是调用工具，
还可以通过技能文件获得特定任务能力。可以这样理解：
Tool：
让 Agent 能做某个动作。
Skill：
告诉 Agent 如何完成某类任务。例如：
apple-notes：
可能和 Apple Notes 工作流有关。
coding-agent：
可能和代码任务有关。
diagram-maker：
可能和图表生成有关。
gh-issues：
可能和 GitHub issue 处理有关。后续分析 Skills 系统时，要重点看每个 skill 中是否包含 SKILL.md、工具说明、配置模板、提示词或工作流说明。
10. skills 和 extensions 的区别
这两个目录容易混淆。
可以这样区分：
extensions：
更偏程序能力扩展，通常包含 TypeScript 代码、服务接入、模型接入、工具实现。
skills：
更偏 Agent 使用层能力，通常告诉 Agent 如何完成某类任务、如何使用某些工具或如何遵守某些流程。举个简单例子：
browser extension：
提供浏览器能力。
web research skill：
告诉 Agent 如何用浏览器做网页调研。也就是说：
extension 更像底层能力；
skill 更像上层使用方法。后续源码阅读时，不能只看工具代码，还要看技能如何把工具组织成可执行任务。
11. apps：桌面端、移动端和伴随应用
apps 目录下可以看到 android、ios、macos、macos-mlx-tts、shared/OpenClawKit、swabble 等子目录。(GitHub)
这说明 OpenClaw 不只面向命令行或浏览器，还包含移动端、桌面端和共享应用组件。
可以先这样理解：
apps/android：
Android 节点或移动端相关代码。
apps/ios：
iOS 节点或移动端相关代码。
apps/macos：
macOS 桌面端或菜单栏应用相关代码。
apps/macos-mlx-tts：
macOS 上与本地语音合成相关的能力。
apps/shared/OpenClawKit：
多端共享的基础库或组件。
apps/swabble：
独立应用或实验性应用模块，后续可单独查看。这和 OpenClaw 的定位一致：它不是只在网页中运行，而是希望成为跨设备、跨渠道、靠近用户个人环境的助手系统。README 也提到它可以在 macOS、iOS、Android 上说话和听取语音输入。(GitHub)
12. apps 目录什么时候看？
apps 不建议一开始就深入。
原因是：
apps 更多是端侧形态；
src 才是核心运行时；
extensions / skills 才是 Agent 能力扩展。建议阅读顺序是：
先看 src：
理解 Gateway 和 Agent 如何工作。
再看 extensions / skills：
理解能力如何扩展。
最后看 apps：
理解移动端和桌面端如何接入 Gateway。也就是说，apps 更适合作为后半部分内容，尤其是在讲"移动端与 Nodes"那一期时重点分析。
13. ui：Control UI 和可视化界面
ui 目录下包含 public、src、index.html、package.json、vite.config.ts、vitest.config.ts 等文件。(GitHub)
从这些文件可以判断，ui 是一个前端项目，使用 Vite 组织构建。
它大概率对应前面第二期提到的 Control UI。也就是当 Gateway 启动后，用户可以通过浏览器访问本地控制界面。
可以这样理解：
Gateway：
负责后端控制平面。
ui：
负责把 Gateway 状态、会话、配置、工具或 Canvas 等内容可视化展示出来。后续如果分析 Canvas、Control UI 或前后端交互，ui 就是重点目录。
14. ui 和 Gateway 的关系
第二期提到过，pnpm gateway:watch 不会自动重建 dist/control-ui，修改 ui/ 后需要重新执行 pnpm ui:build 或使用 pnpm ui:dev。这说明 ui 和 Gateway 虽然联动，但构建链路是分开的。(GitHub)
可以理解为：
Gateway 提供服务和接口；
ui 负责前端页面；
构建后由 Gateway 或本地服务提供访问入口。后续看源码时可以重点关注：
1. ui 如何请求 Gateway？
2. Gateway 暴露了哪些接口给 Control UI？
3. Canvas 或会话状态如何在页面中展示？
4. 前端是否通过 WebSocket 和 Gateway 通信？15. docs：官方文档和架构说明
docs 目录非常重要，尤其适合辅助源码阅读。
从 docs 目录可以看到，它包含 .generated、.i18n、announcements、assets、automation、channels、cli、concepts、debug、diagnostics、gateway、install、nodes 等子目录。(GitHub)
也就是说，docs 不只是普通说明文档，而是覆盖了：
安装
CLI
Gateway
Channel
节点
调试
诊断
概念解释
自动化这些内容和源码模块是一一对应的。
所以，在读源码时，不应该只看代码，还应该对照 docs：
读 CLI 源码前：
先看 docs/cli。
读 Gateway 源码前：
先看 docs/gateway。
读 Channel 源码前：
先看 docs/channels。
读 Nodes 源码前：
先看 docs/nodes。
遇到问题：
看 docs/debug 和 docs/diagnostics。这样效率会高很多。
16. security：安全规则和安全工具
security 目录目前包含 opengrep 和 README.md。其 README 说明，这个目录保存 OpenClaw 发布的 OpenGrep 安全规则包，以及用于验证和运行这些规则的支持工具。(GitHub)
这个目录很值得关注。
因为 OpenClaw 是一个能连接真实消息入口、调用工具、处理本地文件和设备能力的 Agent 系统。安全不是附加内容，而是架构的一部分。
从源码解析角度看，security 至少有三层意义：
第一，项目本身需要安全扫描规则，防止代码层面的风险回归。
第二，Agent 工具调用需要安全边界，避免模型滥用高风险能力。
第三，外部消息入口可能带来 prompt injection、恶意链接、恶意指令等风险。后续讲 Sandbox、安全模型、DM pairing、工具权限时，可以把 security 目录作为辅助材料。
17. config、deploy 和 scripts
这三个目录通常不是一开始最吸引人的地方，但它们对工程运行很重要。
可以先这样理解：
config：
项目默认配置、模板配置或环境相关配置。
deploy：
部署相关内容，例如容器、云平台或服务部署文件。
scripts：
开发、构建、检查、生成、发布等脚本。这些目录适合在遇到对应问题时查：
想知道默认配置从哪里来：
看 config。
想知道如何部署：
看 deploy。
想知道 pnpm 某个命令背后跑了什么：
看 scripts 和 package.json。对于源码解析博客来说，这些目录可以穿插讲，不必单独作为最早几期重点。
18. test 和 qa：测试与质量保障
根目录下同时有 test 和 qa。
从命名看，test 更可能保存自动化测试代码，qa 更可能保存质量检查、验收、测试场景或项目质量保障相关内容。根目录确实列出了 qa 和 test 两个目录。(GitHub)
读源码时，测试目录非常有价值。
原因是：
测试用例通常会告诉我们：
某个模块应该如何被调用；
输入输出是什么；
异常情况如何处理；
作者认为哪些行为必须保持稳定。所以后续分析某个模块时，可以配合测试来看：
看 CLI：
找 CLI 相关测试。
看 Gateway：
找 Gateway 相关测试。
看 Channel：
找 Channel 或 adapter 相关测试。
看 Skills：
找 skills 加载或解析相关测试。测试用例常常比长篇文档更能说明代码意图。
19. 根目录关键文件
除了目录，根目录的几个文件也很重要。
可以重点关注：
README.md
package.json
openclaw.mjs
pnpm-workspace.yaml
tsconfig*.json
Dockerfile
docker-compose.yml
SECURITY.md
CONTRIBUTING.md
AGENTS.md
CLAUDE.md其中：
README.md：
项目定位和快速使用入口。
package.json：
脚本、依赖、bin 命令、构建流程入口。
openclaw.mjs：
CLI 运行入口之一。
pnpm-workspace.yaml：
说明 workspace 如何组织。
tsconfig*.json：
说明 TypeScript 编译边界。
Dockerfile / docker-compose.yml：
说明容器化运行方式。
SECURITY.md：
说明安全报告和安全策略。
AGENTS.md / CLAUDE.md：
面向 Agent 或代码助手的项目说明。根目录文件在 GitHub 页面中也可以看到，例如 openclaw.mjs、package.json、pnpm-workspace.yaml、多个 tsconfig、Dockerfile、SECURITY.md、AGENTS.md 和 CLAUDE.md。(GitHub)
20. 一张目录地图
可以用下面这张简化图理解 OpenClaw 仓库：
openclaw/
├─ src/ 核心运行时代码
│ ├─ cli/ CLI 命令入口
│ ├─ commands/ 具体命令实现
│ ├─ agents/ Agent 相关逻辑
│ ├─ channels/ 渠道接入逻辑
│ ├─ chat/ 对话处理逻辑
│ ├─ config/ 配置加载逻辑
│ ├─ daemon/ Gateway / daemon 相关逻辑
│ └─ cron/ 定时任务相关逻辑
│
├─ extensions/ 插件、模型、工具、平台扩展
├─ packages/ SDK、插件契约、共享包
├─ skills/ 内置技能库
├─ apps/ Android / iOS / macOS 等端侧应用
├─ ui/ Control UI / 前端界面
├─ docs/ 官方文档
├─ security/ 安全规则和安全工具
├─ test/ 自动化测试
├─ qa/ 质量保障相关内容
├─ config/ 配置模板或默认配置
├─ deploy/ 部署相关内容
└─ scripts/ 工程脚本这张图不一定覆盖所有细节，但足够作为后续阅读路线图。
21. 对源码阅读的建议
我建议后续按照下面顺序读：
第一阶段：入口和主链路
1. package.json
2. openclaw.mjs
3. src/cli
4. src/commands
5. src/daemon
第二阶段：核心运行机制
6. src/config
7. src/agents
8. src/chat
9. src/channels
第三阶段：能力扩展
10. extensions
11. packages
12. skills
第四阶段：安全和工程化
13. security
14. test / qa
15. docs/debug / docs/diagnostics
第五阶段：前端和多端
16. ui
17. apps这个顺序的逻辑是：
先知道命令怎么进来；
再知道 Gateway 怎么运行；
再知道 Agent 怎么处理消息；
再知道工具、技能和扩展怎么增强能力；
最后看 UI、移动端和安全细节。22. 本期重点理解
这一期最重要的是建立目录层面的整体认识。
可以总结为五点：
第一，src 是核心运行时代码，后续分析 CLI、Gateway、Agent、Channel、Config 都要从这里开始。
第二，extensions 是插件和外部能力扩展目录，模型提供商、工具能力、平台能力很可能都在这里组织。
第三，skills 是内置技能库，体现 OpenClaw 如何通过技能扩展 Agent 的任务能力。
第四，apps 和 ui 分别对应多端应用和浏览器控制界面，它们让 OpenClaw 不只停留在命令行。
第五，docs、security、test、qa、scripts 是理解工程化、安全和运行方式的重要辅助目录。一句话概括：
OpenClaw 的仓库结构体现了一个完整个人 AI 助手系统的组成：src 负责核心运行，extensions 和 skills 负责能力扩展，apps 和 ui 负责交互形态，security、test、qa 和 docs 负责安全、质量和工程支撑。23. 本期小结
本期主要分析了 OpenClaw 的仓库目录结构。src 是核心运行时代码，包含 CLI、commands、agents、channels、chat、config、daemon 等关键模块；extensions 用于组织模型、工具、平台和外部服务扩展；packages 保存 SDK、插件契约和共享包；skills 保存内置技能；apps 包含 Android、iOS、macOS 等端侧应用；ui 是基于前端工程组织的控制界面；docs、security、test、qa、scripts 则分别承担文档、安全规则、测试、质量保障和工程脚本职责。
这一期可以用一句话总结：
读 OpenClaw 源码时，不能只盯着某一个模型调用函数，而要先看懂 src、extensions、skills、apps、ui、security、docs 这些目录如何共同组成一个可运行、可扩展、可交互、可安全约束的 Agent 系统。下一期可以继续分析：
OpenClaw 源码解析（四）：CLI 入口与 openclaw 命令
下一期重点分析 package.json、openclaw.mjs、src/cli 和 src/commands，理解用户在终端输入 openclaw agent --message "Hello"、openclaw gateway status 或 openclaw onboard 后，命令是如何进入源码并分发到具体处理逻辑的。