search

1.4 项目目录结构详解

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~130,000 tokens，输出 ~12,000 tokens（本章合计）

在深入源码之前，我们需要对 OpenClaw 的项目目录有一个全面的了解。一个好的目录结构就像一本书的目录——它反映了项目的架构决策和模块划分。

OpenClaw 仓库根目录的顶层结构如下：

openclaw/
├── src/                    # 核心源码（TypeScript）
├── apps/                   # 原生客户端应用
│   ├── macos/             # macOS 菜单栏应用（Swift）
│   ├── ios/               # iOS 节点应用（Swift）
│   ├── android/           # Android 节点应用（Kotlin）
│   └── shared/            # 跨平台共享代码（Swift）
├── ui/                     # Web 控制台 UI（Lit + Vite）
├── extensions/             # 可选通道扩展（31 个）
├── packages/               # 内部共享包
├── skills/                 # 内置技能（52 个）
├── docs/                   # 官方文档源码
├── scripts/                # 构建与工具脚本
├── test/                   # 全局测试配置
├── vendor/                 # 第三方代码
├── patches/                # pnpm patch 补丁
├── git-hooks/              # Git 钩子
├── package.json            # 主包配置
├── pnpm-workspace.yaml     # Monorepo 工作区定义
├── tsconfig.json           # TypeScript 配置
├── tsdown.config.ts        # 打包配置
├── vitest.config.ts        # 测试配置
├── docker-compose.yml      # Docker 编排
├── Dockerfile              # 主容器镜像
├── Dockerfile.sandbox      # 沙箱容器镜像
├── Dockerfile.sandbox-browser # 带浏览器的沙箱镜像
└── openclaw.mjs            # npm 全局安装的 CLI 入口

下面我们逐一深入每个核心目录。

hashtag
1.4.1 src/ — 核心源码（69 个子目录）

src/ 是 OpenClaw 的核心，包含了 Gateway、Agent、通道、工具等所有核心功能的 TypeScript 源码。它有 69 个子目录——这是整个项目最庞大的部分。

按功能域划分，这些子目录可以分为以下几组：

hashtag
Gateway 核心（控制平面）

目录
文件数
说明

src/gateway/

128

Gateway WebSocket 服务器、HTTP 服务器、会话管理、方法处理

src/routing/

5

消息路由逻辑：路由解析、会话键生成

src/sessions/

7

会话辅助：级别覆盖、模型覆盖、发送策略

hashtag
Agent 运行时

目录
文件数
说明

src/agents/

308

最大目录。Agent 循环、工具系统、模型管理、技能、沙箱

src/providers/

8

模型提供者特定逻辑（GitHub Copilot、Google、Qwen）

src/agents/ 是整个项目中文件最多的目录。它内部进一步划分为：

hashtag
通道实现

目录
文件数
说明

src/channels/

31

通道抽象层：注册表、白名单、提及门控、命令门控

src/whatsapp/

—

WhatsApp 特定逻辑

src/web/

46

WhatsApp Web 实现（Baileys）：登录、入站、出站、自动回复

src/telegram/

—

Telegram Bot（grammY）实现

src/discord/

—

Discord Bot 实现

src/slack/

—

Slack Bot（Bolt）实现

src/signal/

—

Signal（signal-cli）实现

src/imessage/

—

iMessage Legacy 实现

src/line/

—

LINE 通道辅助

hashtag
工具与自动化

目录
文件数
说明

src/browser/

68

浏览器控制：CDP、Playwright、Chrome 管理、截图

src/canvas-host/

4

Canvas/A2UI 服务器

src/cron/

33

Cron 定时任务：调度、存储、投递

src/node-host/

3

设备节点 Host

src/commands/

—

聊天斜杠命令处理

src/hooks/

28

钩子系统：加载器、安装、Gmail 钩子

hashtag
基础设施

目录
文件数
说明

src/config/

124

配置系统：加载、Schema、类型、迁移、校验

src/security/

13

安全：审计、外部内容检查、技能扫描

src/infra/

—

基础设施工具：端口管理、二进制文件、环境变量

src/media/

19

媒体管道：获取、解析、存储、图像处理

src/memory/

43

记忆系统：嵌入、向量搜索、SQLite、混合搜索

src/logging/

—

日志子系统

src/tts/

—

文本转语音

hashtag
CLI 与用户界面

目录
文件数
说明

src/cli/

105

CLI 命令实现：gateway、agent、send、models、skills 等

src/wizard/

10

引导向导（Onboarding Wizard）

src/tui/

—

终端用户界面

src/terminal/

—

终端渲染工具

src/daemon/

—

守护进程管理

hashtag
其他

目录/文件
说明

src/plugin-sdk/

插件 SDK（供扩展开发者使用）

src/plugins/

插件加载器

src/extensionAPI.ts

扩展 API 入口

src/acp/

Agent Communication Protocol 实现

src/auto-reply/

自动回复逻辑

src/link-understanding/

链接内容理解

src/media-understanding/

媒体内容理解

src/pairing/

DM 配对系统

src/process/

进程管理

src/shared/

共享工具函数

src/types/

第三方库类型声明

src/utils.ts

通用工具函数

src/markdown/

Markdown 处理

src/macos/

macOS 特定功能

src/entry.ts

CLI 入口点

src/index.ts

库入口点（导出公共 API）

src/globals.ts

全局常量

src/runtime.ts

运行时配置

src/logger.ts

日志器实例

src/logging.ts

日志配置

hashtag
1.4.2 apps/ — 原生客户端应用

macOS 和 iOS 应用使用 XcodeGen 来生成 Xcode 项目文件（而不是直接提交 .xcodeproj），这避免了 Xcode 项目文件的合并冲突问题。

hashtag
1.4.3 ui/ — Web 控制台 UI

UI 是一个独立的 pnpm 工作区包（openclaw-control-ui），使用 Vite 构建。构建产物被嵌入到 Gateway 中直接托管，不需要单独部署。Gateway 启动时自动提供 UI 服务（src/gateway/control-ui.ts）。

hashtag
1.4.4 extensions/ — 可选通道扩展（31 个扩展）

每个扩展是一个独立的 pnpm 包，具有自己的 package.json 和入口文件。扩展通过 Plugin SDK 与 Gateway 交互。

hashtag
1.4.5 packages/ — 内部共享包

这两个包提供了一些跨模块共享的基础功能。moltbot 是 OpenClaw 的前身项目名称的遗留。

hashtag
1.4.6 skills/ — 内置技能（52 个技能）

每个技能目录通常包含一个 SKILL.md 文件，这是一个 Markdown 格式的说明文档，Agent 会在运行时读取它来了解技能的使用方法。部分技能还包含额外的脚本或配置文件。

hashtag
1.4.7 docs/ — 官方文档源码

文档使用 Mintlifyarrow-up-right 构建，托管在 docs.openclaw.ai。docs/concepts/ 目录中的 31 个概念文档是理解 OpenClaw 设计决策的绝佳参考——本书在很多地方也参考了这些文档。

到这里，你应该对 OpenClaw 的项目结构有了清晰的认识。让我们以一个速查表结束本节：

你想了解的功能
首先去看的目录

Gateway 服务器实现

src/gateway/

AI Agent 循环

src/agents/pi-embedded-*.ts

工具系统

src/agents/pi-tools*.ts + src/agents/bash-tools*.ts

WhatsApp 通道

src/web/

Telegram 通道

src/telegram/

配置系统

src/config/

安全模型

src/security/ + src/agents/sandbox*.ts

记忆系统

src/memory/

浏览器自动化

src/browser/

CLI 命令

src/cli/

技能系统

src/agents/skills*.ts + skills/

扩展开发

src/plugin-sdk/ + extensions/

macOS 应用

apps/macos/Sources/

Web UI

ui/src/

在下一章中，我们将亲手搭建开发环境，并运行 OpenClaw。

Previous1.3 技术栈全景Next第02章-快速上手与开发环境

Last updated