OpenClaw（GitHub 主仓库：https://github.com/openclaw/openclaw）是一个用 TypeScript + Node.js 编写的开源、自托管 AI 代理框架。它的核心设计哲学是“文件即配置、文件即状态”（workspace-first），通过 Markdown/JSON 文件驱动 Agent 行为、记忆、技能，而不是复杂的数据库或代码硬编码。
本文基于官方仓库最新 main 分支（2026.3.x 系列）+ 社区深度剖析文章（如 ppaolo.substack、Medium 架构文、BetterLink Blog 等），系统拆解源码目录结构，并给出开发者入门路径。目标：让你能快速定位代码、理解核心循环、开始贡献或自定义扩展。
OpenClaw 采用经典的 三层解耦 + 中心辐射 模型：
核心文件驱动原则：
网站资讯
关于我们openclaw/
├── .github/ # CI/CD、issue 模板、PR 限制（目前限 10 个 PR/作者）
├── .vscode/ # 推荐设置（eslint、tsconfig 等）
├── docker/ # Dockerfile、docker-compose.yml、docker-setup.sh
├── packages/ # monorepo 子包（pnpm workspace）
│ ├── cli/ # openclaw CLI 入口（openclaw.mjs → src/cli/program.ts）
│ ├── gateway/ # Gateway 服务核心（src/gateway/server.ts）
│ ├── plugin-sdk/ # 插件开发 SDK（Channel/Tool/Skill 定义）
│ └── ui/ # Web Dashboard 前端（pnpm ui:build）
├── src/ # 主源码（TypeScript）
│ ├── agents/ # Agent 运行时
│ │ ├── piembeddedrunner.ts # 核心 Agent 执行器（Pi Agent Core 封装）
│ │ └── ... # 多 Agent、MCP 协作逻辑
│ ├── channels/ # 渠道适配器
│ │ ├── telegram.ts # grammY 实现
│ │ ├── whatsapp.ts # Baileys 实现
│ │ └── ... # discord、slack、signal、imessage 等
│ ├── gateway/ # 消息中枢
│ │ └── server.ts # WebSocket + HTTP 服务（ws 库）
│ ├── plugins/ # 插件加载器
│ │ └── loader.ts # 扫描 extensions/ + package.json openclaw.extensions
│ ├── tools/ # 内置工具（browser、shell、file、git、email 等）
│ ├── memory/ # 记忆管理（Memory.md → 向量检索 / LanceDB）
│ └── cli/ # CLI 命令实现（onboard、gateway、agents、skills 等）
├── extensions/ # 示例/社区插件目录（热加载）
├── CONTRIBUTING.md # 贡献指南（先 Discussion → 小修复直接 PR）
├── openclaw.mjs # CLI 入口文件（Commander.js）
├── pnpm-workspace.yaml # monorepo 配置
├── tsconfig.json # TypeScript 配置
└── Dockerfile # 生产镜像构建关键文件速查：
步骤（推荐 pnpm）：
git clone https://github.com/openclaw/openclaw.git
cd openclawpnpm installpnpm ui:buildpnpm cli dev # 或直接 node openclaw.mjspnpm gateway dev
# 或
nodemon --watch src/gateway src/gateway/server.ts推荐调试工具：
| 难度 | 切入点 | 推荐修改文件/目录 | 典型任务示例 |
|---|---|---|---|
| ★☆☆ | 自定义 Skill | ~/.openclaw/skills/ 或 extensions/ | 新建 auto-backup-vercel.skill.json |
| ★★☆ | 自定义 Tool | extensions/my-tool/ | 写一个调用 Linear API 的工具 |
| ★★☆ | 新增/改 Channel | src/channels/ 或 extensions/ | 开发企业微信/钉钉适配器 |
| ★★★ | 修改 Agent 推理逻辑 | src/agents/piembeddedrunner.ts | 调整 max iterations / 自定义 prompt 模板 |
| ★★★ | 增强 Gateway 安全/路由 | src/gateway/server.ts | 加 rate limit、IP 白名单 |
| ★★★★ | 贡献 MCP 多 Agent 增强 | src/agents/ + plugin-sdk | 支持更复杂的依赖图 / 并行执行 |
小技巧：
OpenClaw 的源码设计非常“开发者友好”——文件驱动 + 插件化 + monorepo，让你改一行配置就能改变 Agent 行为，改几行代码就能新增能力。
建议路径：
