OpenClaw - 个人 AI 助手系统
版本: 2026.1.30
最后更新: 2026-02-01
本文档集包含 OpenClaw 系统的完整架构设计方案和各模块的二次开发指导。
| 序号 | 文档 | 内容概述 |
|---|---|---|
| 1 | 系统整体架构设计方案 | 系统分层、核心组件、数据流、接口设计、部署架构 |
| 2 | Gateway 模块二次开发指导手册 | WebSocket 控制平面、RPC 方法、事件系统、协议扩展 |
| 3 | Channel 插件开发指导手册 | 消息通道开发、Adapter 实现、配置 Schema、测试 |
| 4 | Agent 工具开发指导手册 | Agent Tool 开发、Pi RPC 集成、工具上下文、测试 |
| 5 | [Plugin SDK 开发指导手册](./05-Plugin SDK开发指导手册.md) | 插件架构、扩展点、配置系统、发布流程 |
| 6 | CLI 扩展开发指导手册 | CLI 命令开发、交互设计、依赖注入、测试 |
┌─────────────────────────────────────────────────────────────┐
│ 客户端层 (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 │
└──────────────┘ └──────────────┘ └──────────────┘
| 组件 | 路径 | 职责 |
|---|---|---|
| Gateway | src/gateway/ |
WebSocket/HTTP 控制平面 |
| Channels | src/channels/, src/{whatsapp,telegram,...}/ |
消息通道适配器 |
| Agent Runtime | src/agents/ |
Pi RPC Agent 封装 |
| Plugin SDK | src/plugin-sdk/, src/plugins/ |
插件系统 |
| CLI | src/cli/ |
命令行界面 |
# 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目标: 让 OpenClaw 支持一个新的消息平台
参考文档: 03-Channel插件开发指导手册
关键步骤:
- 创建插件目录
extensions/my-channel/ - 实现
ChannelPlugin接口 - 配置
openclaw.plugin.json - 注册出站/入站适配器
- 测试并发布
目标: 让 AI Agent 能够调用新的功能
参考文档: 04-Agent工具开发指导手册
关键步骤:
- 定义工具 Schema (TypeBox)
- 实现
execute函数 - 在插件中注册或添加到内置工具
- 测试工具调用
目标: 添加新的 WebSocket/HTTP 接口
参考文档: 02-Gateway模块二次开发指导手册
关键步骤:
- 定义协议 Schema
- 实现方法处理器
- 注册到
methodHandlers - 更新类型定义
目标: 创建一个包含多种扩展的插件
参考文档: [05-Plugin SDK开发指导手册](./05-Plugin SDK开发指导手册.md)
关键步骤:
- 创建插件目录和清单
- 实现注册函数
- 注册工具/通道/CLI/服务
- 配置 Schema 和 UI 提示
- 测试并发布到 npm
目标: 扩展命令行界面
参考文档: 06-CLI扩展开发指导手册
关键步骤:
- 创建命令文件
- 使用
@clack/prompts实现交互 - 注册到程序
- 编写测试
WebSocket 协议帧格式:
// 请求
{
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: { ... }
}interface ChannelPlugin {
id: string;
meta: ChannelMeta;
capabilities: ChannelCapabilities;
config: ChannelConfigAdapter;
outbound: ChannelOutboundAdapter;
gateway?: ChannelGatewayAdapter;
security?: ChannelSecurityAdapter;
messaging?: ChannelMessagingAdapter;
// ... 更多适配器
}interface AgentTool {
name: string;
description: string;
parameters: TSchema;
execute: (params: {
args: Record<string, unknown>;
context: ToolContext;
}) => AsyncIterable<ToolResult> | Promise<ToolResult>;
}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/ # 构建脚本
- OpenClaw Docs - 用户文档
- GitHub Repo - 源码仓库
- Pi Agent Core - Agent 运行时
- TypeBox - JSON Schema 类型
- Commander.js - CLI 框架
- @clack/prompts - 交互提示
- Vitest - 测试框架
- 使用清晰的标题描述问题
- 提供复现步骤
- 包含环境信息（Node 版本、操作系统）
- 附上相关日志
- Fork 仓库
- 创建功能分支 (
git checkout -b feature/my-feature) - 提交更改 (
git commit -am 'Add feature') - 推送到分支 (
git push origin feature/my-feature) - 创建 Pull Request
- 使用 TypeScript (ESM)
- 遵循 Oxlint/Oxfmt 规范
- 添加测试覆盖
- 更新相关文档
MIT License - 详见 LICENSE 文件
感谢所有贡献者让 OpenClaw 变得更好！
特别感谢：
- Mario Zechner - Pi Agent Core 作者
- 所有贡献者
提示: 本文档是内部开发文档，与面向用户的 docs.openclaw.ai 互补。如需了解系统使用方法，请参考官方用户文档。