在正式深入那些晦涩的源码文件之前我们需要先建立一张“全局地图”。很多初读 OpenClaw 源码的开发者面对庞大的代码仓库往往会迷失方向。OpenClaw 的设计非常工业化它并没有把系统拆成复杂的微服务而是采用了一种“插件化单体Pluggable Monolith”的架构。所有的核心能力都通过pnpm-workspace.yaml组织由pnpm这个工具在Git仓库中进行进行统一管理。今天我们就来全景拆解 OpenClaw 仓库的四大核心目录src、extensions、kills和packages看看它们各自在系统中扮演着什么角色。openclaw/├── src/# 核心 TypeScript 源码69 个子目录├── apps/# 原生客户端应用├── ui/# Web 控制台 UI├── extensions/# 可选通道插件31├── packages/# 内部共享包├── skills/# 内置技能52个├── docs/# 官方文档源├── scripts/# 构建与工具脚本├── test/# 全局测试配置├── vendor/# 第三方代码├── patches/# pnpm 补丁├── package.json# 主包配置├── pnpm-workspace.yaml # Monorepo 工作区定义└── openclaw.mjs# npm 全局安装的 CLI 入口1. src/系统的心脏与核心运行时src/是 OpenClaw 的心脏包含 Gateway、Agent、通道、工具等所有核心功能的 TypeScript 源码。按功能域可以划分为以下几组openclaw/├── src/├── gateway/├──routing/├──channels/├──agents/├──plugins/├──memory/├──sessions/├──providers/gateway/这是 OpenClaw 的绝对中心单一控制平面。它负责处理 WebSocket/HTTP 通信、RPC 调用、事件广播和节点管理。agents/Agent 运行时环境。包括模型管理/Provider 的对接、工具系统Tools、Skills、沙箱以及核心推理逻辑。channels/通道抽象层。负责管理各种消息渠道的注册、路由策略和会话辅助功能。routing/路由解析中心。负责解析sessionKey、绑定账号和路由分发。在 OpenClaw 中sessionKey是第一等公民所有的会话持久化、并发控制和上下文恢复都依赖它。plugins/插件加载器与注册表。它负责在启动时扫描并挂载所有扩展。memory/ sessions/负责记忆后端的索引管理以及会话状态的持久化策略。providers/:模型提供商特定逻辑GitHub Copilot、Google、Qwen 等2. src下其他关键子目录openclaw/├── src/├── auto-reply/# 回复管道agent-runner.ts 是核心 Agent 回合编排器├──cli/# CLI命令定义├──commands/ # 命令实现约352个文件├──entry.ts/ # CLI入口负责环境设置后加载 src/cli/run-main.ts├──infra/#基础设施网络、SSRF 防护、执行安全、归档├── config/# 配置模式、类型、验证├──llm/# 模型/供应商注册、传输辅助工具、供应商专属流式实现├── channels/# 共享通道逻辑身份、白名单、门控、注册├── plugins/ # 插件加载器、插件 API 定义├── security/ # 安全相关逻辑审计、策略、外部内容包装├── plugin-sdk/ # Channel 插件 SDK├── cron/ # Cron 定时任务├── media/ # 媒体管道处理3. extensions/无限扩展的“能力插槽”OpenClaw 之所以能对接各种大模型和通讯平台全靠extensions/目录它是系统扩展的主要承载区。这里的扩展主要分为两类Channel 插件通道比如telegram、discord、slack、whatsapp、signal等。它们负责把外部平台的消息“翻译”成 OpenClaw 内部的标准协议。Provider 插件模型供应商比如openai、qwen、deepseek等。它们封装了不同大模型 API 的调用细节。这种设计的好处是解耦通讯平台和智能体互不感知全部通过网关中转。开发者想要接入一个新平台只需在extensions/下实现标准的插件契约即可完全不需要改动核心代码。4. skills/内置技能库51 个skills/目录存放 OpenClaw内置的 Skill 定义SKILL.md文件。Skills 是 OpenClaw 的能力扩展机制——通过 YAML Frontmatter Markdown 描述告诉 Agent “你能做什么、怎么做”。内置的 51 个 Skills 覆盖了常见场景文件操作、网页浏览、代码分析等。插件也可以通过openclaw.plugin.json声明自己的skills/目录来提供额外的 Skills。本质一个Skill通常是一个封装了特定能力的Markdown文件SKILL.md包含YAML元数据和使用指南。加载优先级OpenClaw 的技能加载有着严格的层级。从高到低依次为工作区技能workspace优先级最高→ 个人/项目级技能 → 全局管理技能managed → 内置技能bundled工具与技能的配合工具Tools提供底层能力而技能Skills提供调用这些能力的方法论。两者配合才能让 Agent 稳定发挥。5. packages/可复用的共享库packages/存放可复用的共享库通过 pnpm workspace 管理。如openclaw/├── packages/├── agent-core/ #可复用的 Agent 核心——Agent 循环、控管框架类型、消息、压缩辅助工具、提示词模板、Skills、会话存储合约├── sdk/ #对外暴露的 SDK├── ai/ #AI 相关共享逻辑├── gateway-protocal #Gateway 协议定义这些包是 OpenClaw模块化设计的体现——核心能力被抽离成独立包便于复用和测试。6. 其他重要目录多端生态与共享基建除了核心的后端逻辑OpenClaw 还具备极强的跨端能力openclaw/├── apps/#多端原生客户端实现。这里包含了 macOS 的菜单栏工具、iOS 和 Android 的原生应用代码。它们通过统一的协议与 Gateway 进行通信。├── ui/#现代化的 Web 管理界面。用于二维码扫码登录、Agent 参数调优、会话管理等可视化操作。├── docs/#官方文档源source of truth├── scripts/#构建、发布和工具脚本├── test/#集成测试 / E2E 测试├── vendor/#第三方代码├── patches#pnpm 补丁文件总结协议优先的工业化设计纵观 OpenClaw 的目录结构我们可以清晰地看到它的核心设计哲学1.单一控制平面一切状态和路由都在 Gateway 中统一管理。2.入口与执行解耦无论是 CLI、WebChat 还是 Telegram 进来的消息最终都会进入统一的 Agent Pipeline。3.协议优先一切操作皆协议这使得它能轻松扩展到多个端和多个平台。 openclaw源码解读——入门与破局：3 仓库目录结构全景图：src、packages、skills、extensions 各自负责什么
在正式深入那些晦涩的源码文件之前我们需要先建立一张“全局地图”。很多初读 OpenClaw 源码的开发者面对庞大的代码仓库往往会迷失方向。OpenClaw 的设计非常工业化它并没有把系统拆成复杂的微服务而是采用了一种“插件化单体Pluggable Monolith”的架构。所有的核心能力都通过pnpm-workspace.yaml组织由pnpm这个工具在Git仓库中进行进行统一管理。今天我们就来全景拆解 OpenClaw 仓库的四大核心目录src、extensions、kills和packages看看它们各自在系统中扮演着什么角色。openclaw/├── src/# 核心 TypeScript 源码69 个子目录├── apps/# 原生客户端应用├── ui/# Web 控制台 UI├── extensions/# 可选通道插件31├── packages/# 内部共享包├── skills/# 内置技能52个├── docs/# 官方文档源├── scripts/# 构建与工具脚本├── test/# 全局测试配置├── vendor/# 第三方代码├── patches/# pnpm 补丁├── package.json# 主包配置├── pnpm-workspace.yaml # Monorepo 工作区定义└── openclaw.mjs# npm 全局安装的 CLI 入口1. src/系统的心脏与核心运行时src/是 OpenClaw 的心脏包含 Gateway、Agent、通道、工具等所有核心功能的 TypeScript 源码。按功能域可以划分为以下几组openclaw/├── src/├── gateway/├──routing/├──channels/├──agents/├──plugins/├──memory/├──sessions/├──providers/gateway/这是 OpenClaw 的绝对中心单一控制平面。它负责处理 WebSocket/HTTP 通信、RPC 调用、事件广播和节点管理。agents/Agent 运行时环境。包括模型管理/Provider 的对接、工具系统Tools、Skills、沙箱以及核心推理逻辑。channels/通道抽象层。负责管理各种消息渠道的注册、路由策略和会话辅助功能。routing/路由解析中心。负责解析sessionKey、绑定账号和路由分发。在 OpenClaw 中sessionKey是第一等公民所有的会话持久化、并发控制和上下文恢复都依赖它。plugins/插件加载器与注册表。它负责在启动时扫描并挂载所有扩展。memory/ sessions/负责记忆后端的索引管理以及会话状态的持久化策略。providers/:模型提供商特定逻辑GitHub Copilot、Google、Qwen 等2. src下其他关键子目录openclaw/├── src/├── auto-reply/# 回复管道agent-runner.ts 是核心 Agent 回合编排器├──cli/# CLI命令定义├──commands/ # 命令实现约352个文件├──entry.ts/ # CLI入口负责环境设置后加载 src/cli/run-main.ts├──infra/#基础设施网络、SSRF 防护、执行安全、归档├── config/# 配置模式、类型、验证├──llm/# 模型/供应商注册、传输辅助工具、供应商专属流式实现├── channels/# 共享通道逻辑身份、白名单、门控、注册├── plugins/ # 插件加载器、插件 API 定义├── security/ # 安全相关逻辑审计、策略、外部内容包装├── plugin-sdk/ # Channel 插件 SDK├── cron/ # Cron 定时任务├── media/ # 媒体管道处理3. extensions/无限扩展的“能力插槽”OpenClaw 之所以能对接各种大模型和通讯平台全靠extensions/目录它是系统扩展的主要承载区。这里的扩展主要分为两类Channel 插件通道比如telegram、discord、slack、whatsapp、signal等。它们负责把外部平台的消息“翻译”成 OpenClaw 内部的标准协议。Provider 插件模型供应商比如openai、qwen、deepseek等。它们封装了不同大模型 API 的调用细节。这种设计的好处是解耦通讯平台和智能体互不感知全部通过网关中转。开发者想要接入一个新平台只需在extensions/下实现标准的插件契约即可完全不需要改动核心代码。4. skills/内置技能库51 个skills/目录存放 OpenClaw内置的 Skill 定义SKILL.md文件。Skills 是 OpenClaw 的能力扩展机制——通过 YAML Frontmatter Markdown 描述告诉 Agent “你能做什么、怎么做”。内置的 51 个 Skills 覆盖了常见场景文件操作、网页浏览、代码分析等。插件也可以通过openclaw.plugin.json声明自己的skills/目录来提供额外的 Skills。本质一个Skill通常是一个封装了特定能力的Markdown文件SKILL.md包含YAML元数据和使用指南。加载优先级OpenClaw 的技能加载有着严格的层级。从高到低依次为工作区技能workspace优先级最高→ 个人/项目级技能 → 全局管理技能managed → 内置技能bundled工具与技能的配合工具Tools提供底层能力而技能Skills提供调用这些能力的方法论。两者配合才能让 Agent 稳定发挥。5. packages/可复用的共享库packages/存放可复用的共享库通过 pnpm workspace 管理。如openclaw/├── packages/├── agent-core/ #可复用的 Agent 核心——Agent 循环、控管框架类型、消息、压缩辅助工具、提示词模板、Skills、会话存储合约├── sdk/ #对外暴露的 SDK├── ai/ #AI 相关共享逻辑├── gateway-protocal #Gateway 协议定义这些包是 OpenClaw模块化设计的体现——核心能力被抽离成独立包便于复用和测试。6. 其他重要目录多端生态与共享基建除了核心的后端逻辑OpenClaw 还具备极强的跨端能力openclaw/├── apps/#多端原生客户端实现。这里包含了 macOS 的菜单栏工具、iOS 和 Android 的原生应用代码。它们通过统一的协议与 Gateway 进行通信。├── ui/#现代化的 Web 管理界面。用于二维码扫码登录、Agent 参数调优、会话管理等可视化操作。├── docs/#官方文档源source of truth├── scripts/#构建、发布和工具脚本├── test/#集成测试 / E2E 测试├── vendor/#第三方代码├── patches#pnpm 补丁文件总结协议优先的工业化设计纵观 OpenClaw 的目录结构我们可以清晰地看到它的核心设计哲学1.单一控制平面一切状态和路由都在 Gateway 中统一管理。2.入口与执行解耦无论是 CLI、WebChat 还是 Telegram 进来的消息最终都会进入统一的 Agent Pipeline。3.协议优先一切操作皆协议这使得它能轻松扩展到多个端和多个平台。