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 等），系统拆解源码目录结构，并给出开发者入门路径。目标：让你能快速定位代码、理解核心循环、开始贡献或自定义扩展。
一、总体架构概述（三层 + Hub-and-Spoke）
OpenClaw 采用经典的 三层解耦 + 中心辐射 模型：
- Gateway（控制平面 / 消息中枢）
- 唯一常驻进程，负责所有渠道接入、路由、会话管理
- 暴露 WebSocket + HTTP API（默认 127.0.0.1:18789）
- Agent Runtime（代理运行时）
- 基于 @mariozechner/pi-agent-core 的 ReAct/Tool-Use 循环
- 加载 Memory、Tools、Skills，执行推理 → 工具调用 → 结果反馈
- Channels & Plugins（接入 & 扩展层）
- 多平台适配器（Telegram、WhatsApp、Discord 等）
- 插件系统（extensions/）支持热加载自定义工具/技能
核心文件驱动原则：
- ~/.openclaw/workspace/ 是“真相之源”
- Agent 身份、工具列表、记忆摘要、任务状态都用 Markdown/JSON 文件表达
- Gateway 只管路由，Runtime 只管执行，Channels 只管收发
二、核心源码目录结构详解（main 分支 2026.3.x）
text
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 # 生产镜像构建关键文件速查：
- CLI 入口：openclaw.mjs → src/cli/program.ts
- Gateway 启动：src/gateway/server.ts（绑定 18789，处理 ws/http）
- Agent 推理循环：src/agents/piembeddedrunner.ts（ReAct + Tool Call + Streaming）
- 插件发现：src/plugins/loader.ts（扫描 workspace 中的 package.json）
- 内存文件：运行时读取 ~/.openclaw/workspace/Memory.md、SOUL.md、TOOLS.md 等
三、开发环境搭建（从源码运行 & 调试）
步骤（推荐 pnpm）：
- 克隆仓库
Bash
git clone https://github.com/openclaw/openclaw.git cd openclaw - 安装依赖（Node 22+ 必须）
Bash
pnpm install - 构建 UI（Dashboard，可选）
Bash
pnpm ui:build - 从源码运行 CLI（开发模式）
Bash
pnpm cli dev # 或直接 node openclaw.mjs - 启动 Gateway（开发模式，热重载推荐用 nodemon）
Bash
pnpm gateway dev # 或 nodemon --watch src/gateway src/gateway/server.ts - 本地调试完整流程
- 先 openclaw onboard（用源码 CLI）
- 配置模型、渠道（推荐 Telegram 测试）
- 启动 Gateway
- 在 Telegram 发消息观察日志
推荐调试工具：
- VS Code + TypeScript 插件
- Chrome DevTools（WebSocket 调试 ws://127.0.0.1:18789/ws）
- openclaw logs --level debug
四、常见开发切入点（由浅入深）
| 难度 | 切入点 | 推荐修改文件/目录 | 典型任务示例 |
|---|---|---|---|
| ★☆☆ | 自定义 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 | 支持更复杂的依赖图 / 并行执行 |
小技巧：
- 开发自定义 Channel/Tool 时，先用 npx create-openclaw-plugin my-plugin 生成模板
- 测试时用 openclaw message send "测试消息" 模拟发送
- 提交 PR 前跑 pnpm check && pnpm test
五、开发注意事项 & 社区规范
- PR 限制：目前每作者最多 10 个开放 PR（barnacle-openclaw 机器人强制执行）
- 讨论优先：大功能/架构改动先开 Discussion 或 Discord 聊
- 安全第一：任何涉及工具执行的改动，必须考虑 prompt injection 防护
- 文档同步：改动后同步更新 https://docs.openclaw.ai（仓库内 docs/ 或直接提 PR）
- 赞助与 maintainer：项目积极招募全职/长期 maintainer（见 CONTRIBUTING.md）
六、结语：从用户到贡献者的一条清晰路径
OpenClaw 的源码设计非常“开发者友好”——文件驱动 + 插件化 + monorepo，让你改一行配置就能改变 Agent 行为，改几行代码就能新增能力。
建议路径：
- 先从本地 workspace 自定义 Skill/Tool 玩熟
- 开发 1–2 个简单 extensions（如新工具或 channel）
- 阅读 src/gateway/server.ts 和 piembeddedrunner.ts 理解核心循环
- 挑一个小 bug 或 missing feature 提交 PR