04. 项目结构：从目录看懂 OpenClaw

这篇解决什么问题

OpenClaw 仓库很大。

如果直接从 src/ 开始扫，会看到大量测试、adapter、provider、channel、runtime 文件，很容易迷路。

先按职责分层。

根目录先看什么

关键文件：

README.md
package.json
openclaw.mjs
docs/
src/
extensions/
packages/
skills/

package.json 里定义了 npm 包名和 bin：

"bin": {
  "openclaw": "openclaw.mjs"
}

所以 openclaw 命令第一站是 openclaw.mjs。

CLI 和启动层

相关目录：

openclaw.mjs
src/entry.ts
src/cli/
src/commands/
src/bootstrap/

openclaw.mjs 是 Node launcher，负责 Node 版本检查、源码/打包模式判断、compile cache、子进程启动等。

Agent Runtime

相关目录：

src/agents/
src/agents/embedded-agent-runner/
src/agents/sessions/
src/agents/agent-tools*.ts
src/agents/agent-hooks/
src/agents/runtime/
packages/agent-core/
src/llm/

官方架构文档说：runtime code 在 src/agents/，model/provider helpers 在 src/llm/。

这是源码解读主菜。

Gateway 和 Channels

相关目录：

src/gateway/
src/channels/
src/pairing/
src/auto-reply/
extensions/<channel>/

Gateway 是常驻控制平面。Channels 负责不同平台的消息收发、授权、allowlist、pairing、消息格式转换。

配置层

相关目录：

src/config/

这个目录很大，因为它要处理配置 schema、legacy 兼容、channel 类型、provider 类型、sandbox、tools、skills、logging、sensitive path 等。

自动化和长期运行

src/cron/
src/daemon/
src/process/
src/logging/

Cron 是定时任务，Daemon 是常驻服务，Process 和 Logging 支持长期运行时的生命周期和可观测性。

扩展系统

src/plugins/
src/plugin-sdk/
extensions/
src/mcp/

OpenClaw 把很多 provider、channel、工具能力放到 extensions / plugin 体系里。不要把所有能力都理解成内置核心。

一张源码地图

openclaw.mjs        CLI launcher
src/cli             命令解析和 CLI 子命令
src/commands        各类命令实现
src/gateway         常驻 Gateway 服务
src/channels        多平台消息抽象
src/agents          Agent Runtime 和 sessions/tools
src/llm             模型 provider 和流式传输
src/config          配置 schema、加载、迁移、安全校验
src/cron            定时任务
src/plugins         插件运行时
src/plugin-sdk      插件对外契约
src/mcp             MCP 接入
extensions          官方扩展包

下一篇看什么

下一篇看 CLI 入口。