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. 初学者如何看 srcsrc不适合一次性全部读完。建议按照主链路来读第一步看 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共享包和 SDKpackages目录目前可以看到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. uiControl 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后命令是如何进入源码并分发到具体处理逻辑的。
OpenClaw 源码解析（三）：仓库目录结构解析
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. 初学者如何看 srcsrc不适合一次性全部读完。建议按照主链路来读第一步看 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共享包和 SDKpackages目录目前可以看到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. uiControl 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后命令是如何进入源码并分发到具体处理逻辑的。
