OpenClaw 系统架构设计与二次开发手册

📚 文档目录

🏗️ 系统架构速览

架构分层

┌─────────────────────────────────────────────────────────────┐
│ 客户端层 (Client Layer) │
│ CLI │ WebChat │ macOS App │ iOS/Android Nodes │
└─────────────────────────────────────────────────────────────┘
 │
 │ WebSocket / HTTP
 ▼
┌─────────────────────────────────────────────────────────────┐
│ Gateway 控制平面层 (Control Plane) │
│ WS Server │ HTTP API │ Channel Mgr │ Plugin Mgr │
└─────────────────────────────────────────────────────────────┘
 │
 ┌─────────────────────┼─────────────────────┐
 ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 消息通道层 │ │ Agent 运行时层 │ │ 扩展插件层 │
│ Channels │ │ Agent │ │ Plugins │
└──────────────┘ └──────────────┘ └──────────────┘

核心组件

🚀 快速开始

环境准备

# 1. Node.js ≥22
node --version # v22.12.0+
# 2. pnpm
pnpm --version # 10.23.0+
# 3. 安装依赖
pnpm install
# 4. 构建
pnpm build

启动开发

# 启动 Gateway 开发模式
pnpm gateway:dev
# 带热重载
pnpm gateway:watch
# 运行测试
pnpm test

📖 开发场景导航

场景 1: 添加新的消息通道

场景 2: 添加 Agent 工具

场景 3: 扩展 Gateway RPC

场景 4: 开发完整插件

场景 5: 添加 CLI 命令

🎯 核心概念

1. Gateway 协议

// 请求
{
 type: "req",
 id: "unique-id",
 method: "methodName",
 params: { ... },
 idempotencyKey?: "for-retry"
}
// 响应
{
 type: "res",
 id: "same-id",
 ok: true | false,
 payload?: { ... },
 error?: { message, code }
}
// 事件推送
{
 type: "event",
 event: "eventName",
 payload: { ... }
}

2. Channel Plugin 接口

interface ChannelPlugin {
 id: string;
 meta: ChannelMeta;
 capabilities: ChannelCapabilities;
 config: ChannelConfigAdapter;
 outbound: ChannelOutboundAdapter;
 gateway?: ChannelGatewayAdapter;
 security?: ChannelSecurityAdapter;
 messaging?: ChannelMessagingAdapter;
 // ... 更多适配器
}

3. Agent Tool 接口

interface AgentTool {
 name: string;
 description: string;
 parameters: TSchema;
 execute: (params: {
 args: Record<string, unknown>;
 context: ToolContext;
 }) => AsyncIterable<ToolResult> | Promise<ToolResult>;
}

4. Plugin API

interface OpenClawPluginApi {
 registerChannel(options: { plugin: ChannelPlugin }): void;
 registerTool(tool: AgentTool): void;
 registerGatewayMethod(method: string, handler: Function): void;
 registerHttpRoute(path: string, handler: Function): void;
 registerCli(registerFn: Function, metadata: CliMetadata): void;
 registerService(service: BackgroundService): void;
 // ... 更多
}

🔧 常用命令

# 开发
pnpm install # 安装依赖
pnpm build # 构建
pnpm gateway:dev # 开发模式启动 Gateway
pnpm gateway:watch # 热重载模式
# 测试
pnpm test # 运行测试
pnpm test:coverage # 覆盖率测试
pnpm test:e2e # E2E 测试
# 代码规范
pnpm lint # 检查
pnpm lint:fix # 自动修复
pnpm format # 格式化
# CLI 使用
openclaw onboard # 引导安装
openclaw gateway # 启动 Gateway
openclaw agent --message "Hi" # 发送消息给 Agent
openclaw plugins list # 列出插件
openclaw plugins install <pkg> # 安装插件
# 调试
DEBUG=openclaw:* pnpm gateway:dev # 详细日志
DEBUG=openclaw:gateway pnpm gateway:dev # Gateway 日志
DEBUG=openclaw:channels pnpm gateway:dev # 通道日志

📁 目录结构

openclaw/
├── src/ # 核心源码
│ ├── gateway/ # Gateway 服务器
│ ├── channels/ # 通道框架
│ ├── agents/ # Agent 运行时
│ ├── plugins/ # 插件系统
│ ├── cli/ # CLI 实现
│ ├── config/ # 配置系统
│ ├── sessions/ # 会话管理
│ └── ... # 其他模块
│
├── extensions/ # 扩展插件
│ ├── matrix/ # Matrix 通道
│ ├── msteams/ # Microsoft Teams
│ ├── voice-call/ # 语音通话
│ └── ... # 更多插件
│
├── docs-internal/ # 本文档集
│ ├── README.md # 本文件
│ ├── 01-系统整体架构设计方案.md
│ ├── 02-Gateway模块二次开发指导手册.md
│ ├── 03-Channel插件开发指导手册.md
│ ├── 04-Agent工具开发指导手册.md
│ ├── 05-Plugin SDK开发指导手册.md
│ └── 06-CLI扩展开发指导手册.md
│
├── docs/ # 用户文档 (Mintlify)
├── apps/ # 客户端应用
│ ├── macos/ # macOS 应用
│ ├── ios/ # iOS 应用
│ └── android/ # Android 应用
│
├── test/ # 测试辅助
└── scripts/ # 构建脚本

🔗 参考资源

官方文档

技术参考

📝 贡献指南

提交 Issue

提交 PR

代码规范

📜 许可证

🙏 致谢