OpenClaw架构揭秘：178k stars的个人AI助手如何用Gateway模式统一控制12+通讯频道

一句话简介：178k stars 的开源项目 OpenClaw，用一套 Gateway 架构同时接入了 WhatsApp、Telegram、Slack、Discord 等 12+ 通讯频道，还实现了 Canvas 可视化、全时语音、浏览器控制等高级功能。这篇文章将深度拆解它的架构设计，告诉你一个「个人 AI 助手」应该如何构建。

📋 目录

• 背景：为什么需要个人AI助手？
• 项目概览：178k stars的OpenClaw
• 核心架构：Gateway WebSocket控制平面
• 多频道接入：12+通讯频道的秘密
• Pi Agent：AI大脑的RPC实现
• Canvas+A2UI：可视化工作空间
• Voice Wake+Talk Mode：全时语音交互
• Skills Platform：三级插件系统
• 技术启发：架构设计的通用性思考
• 总结：从OpenClaw学到的5个架构原则

背景：为什么需要个人AI助手？

你是否也遇到过这样的场景？

• 同事在 WhatsApp 上问你问题，客户在 Slack 上催进度，老板在 Telegram 上布置任务，而你还在 Discord 上跟社区成员讨论技术问题...
• 你想让 AI 帮你处理这些消息，但每个平台都有不同的 API、不同的接入方式、不同的消息格式...
• 你试过 ChatGPT，但它只能在网页里聊天；你试过各种 AI 助手，但它们要么收费昂贵，要么不能接入你日常使用的通讯工具...

直到我发现了 OpenClaw。

这个项目用一套优雅的架构解决了所有这些痛点：一个 Gateway 控制平面，统一管理 12+ 通讯频道，让你在任何平台上都能与同一个 AI 助手对话。更重要的是，它是完全开源的，你可以部署在自己的设备上，数据完全由你掌控。

项目概览：178k stars的OpenClaw

OpenClaw 是一个个人 AI 助手，你可以在自己的设备上运行它，通过 WhatsApp、Telegram、Slack、Discord 等常用通讯工具与它交互。它的核心理念是：Gateway 只是控制平面，真正的产品是 AI 助手本身。

核心数据

支持的通讯频道（12+）

支持的平台

• macOS：完整的菜单栏应用，支持 Voice Wake、Talk Mode、Canvas
• iOS：Node 模式，支持 Canvas、语音、相机、录屏
• Android：Node 模式，支持 Canvas、语音、相机、录屏、短信

核心架构：Gateway WebSocket控制平面

OpenClaw 的架构可以用一句话概括：一个 Gateway，多个客户端，统一控制。

架构图

1graph TD
2    A[WhatsApp] --> G[Gateway WebSocket Control Plane]
3    B[Telegram] --> G
4    C[Slack] --> G
5    D[Discord] --> G
6    E[Google Chat] --> G
7    F[Signal/iMessage/Teams/Matrix/Zalo/WebChat] --> G
8    
9    G -->|WebSocket ws://127.0.0.1:18789| P[Pi Agent Runtime]
10    G -->|CLI| CLI[openclaw CLI]
11    G -->|Web UI| WC[WebChat]
12    G -->|Native App| MA[macOS App]
13    G -->|Node Protocol| N1[iOS Node]
14    G -->|Node Protocol| N2[Android Node]
15    
16    P -->|Canvas| CV[Canvas A2UI]
17    P -->|Browser| BR[Browser Control]
18    P -->|Skills| SK[Skills Platform]
19    P -->|Voice| VW[Voice Wake]
20    P -->|Talk| TM[Talk Mode]
21

为什么用 WebSocket 做控制平面？

你可能会问：为什么要用 WebSocket 而不是 HTTP REST API？

答案很简单：实时性 + 双向通信。

传统的 HTTP 请求是"一问一答"模式：客户端问，服务器答。但在 AI 助手的场景里，我们需要：

1. 服务器主动推：AI 生成内容时，需要流式输出（stream）到客户端
2. 双向通信：Gateway 既要接收用户消息，也要发送 AI 回复，还要处理各种事件（typing indicators、presence、媒体文件等）
3. 长连接管理：一个用户可能同时在 WhatsApp、Telegram、Slack 上聊天，Gateway 需要同时维护多个连接

WebSocket 就像是给 AI 助手装了一个"神经系统"：所有感官（频道）都连接到大脑（Pi Agent），大脑的处理结果又能实时反馈到任何一个感官。

Gateway 的核心职责

多频道接入：12+通讯频道的秘密

OpenClaw 最让人惊叹的是它同时支持 12+ 个通讯频道。这是怎么做到的？

统一抽象层

OpenClaw 没有为每个频道写一堆重复代码，而是设计了统一的 Channel Abstraction Layer（频道抽象层）。

代码示例（概念性）：

1// 统一的频道接口
2interface Channel {
3  // 发送消息
4  send(to: string, message: string): Promise<void>;
5  
6  // 接收消息（回调）
7  onMessage(handler: (msg: Message) => void): void;
8  
9  // 发送打字状态
10  sendTyping(to: string): Promise<void>;
11  
12  // 获取频道信息
13  getInfo(): ChannelInfo;
14}
15
16// WhatsApp 实现
17class WhatsAppChannel implements Channel {
18  private baileys: any;
19  
20  async send(to: string, message: string) {
21    // 使用 Baileys 库发送
22    await this.baileys.sendMessage(to, { text: message });
23  }
24  
25  onMessage(handler) {
26    this.baileys.ev.on('messages.upsert', handler);
27  }
28  
29  // ... 其他实现
30}
31
32// Telegram 实现  
33class TelegramChannel implements Channel {
34  private bot: Bot;
35  
36  async send(to: string, message: string) {
37    // 使用 grammY 发送
38    await this.bot.api.sendMessage(to, message);
39  }
40  
41  onMessage(handler) {
42    this.bot.on('message', handler);
43  }
44  
45  // ... 其他实现
46}
47

关键洞察：虽然 WhatsApp、Telegram、Slack 的底层协议完全不同（WhatsApp 用 Baileys 的 WhatsApp Web 协议，Telegram 用 Bot API，Slack 用 Bolt SDK），但在 Gateway 看来，它们都是实现了统一接口的 Channel。

群聊 vs 私聊的路由策略

OpenClaw 的消息路由设计非常精细：

DM 安全策略

OpenClaw 连接到真实的通讯表面，必须处理不受信任的输入。默认安全策略：

• Pairing Mode（配对模式）：未知发送者会收到一个配对码，必须先通过 CLI 批准才能与 AI 助手对话
• Allowlist（白名单）：只有通过 openclaw pairing approve 批准的用户才能发送消息
• Open Mode（开放模式）：显式配置后允许所有人发送消息（不推荐）

这就像是在你家门口装了一个智能门禁：陌生人需要按门铃（配对码），你确认后才开门（批准）。

Pi Agent：AI大脑的RPC实现

如果说 Gateway 是神经系统，那么 Pi Agent 就是大脑。

RPC 模式 vs 直接调用

OpenClaw 的 Pi Agent 运行在 RPC（Remote Procedure Call）模式，这意味着：

• 分离架构：Gateway 和 Agent 可以运行在不同的进程甚至不同的机器上
• 语言无关：Agent 可以用任何语言实现（OpenClaw 用 Node.js/TypeScript）
• 可替换性：你可以接入自己的 Agent 实现，只要遵循相同的 RPC 协议

对比传统的直接调用：

1// 传统方式：Gateway 直接调用 Agent
2const response = await agent.processMessage(message);
3
4// OpenClaw 方式：RPC 调用
5const response = await rpc.call('pi.agent.processMessage', {
6  sessionId: 'main',
7  message: message,
8  tools: ['browser', 'canvas', 'node']
9});
10

RPC 就像是给大脑和神经系统之间加了一个标准接口：只要接口不变，你可以换任何品牌的大脑。

Tool Streaming & Block Streaming

Pi Agent 支持两种流式输出：

1. Tool Streaming：AI 决定使用工具时，实时流式传输工具调用信息
2. Block Streaming：AI 生成内容时，分块流式传输（类似 ChatGPT 的打字效果）

这让用户体验更加实时、流畅，不用等待 AI 完全生成完才看到回复。

Canvas+A2UI：可视化工作空间

如果说文字聊天是 1D 交互，那么 Canvas 就是 2D/3D 交互。

什么是 A2UI？

A2UI（Agent-to-User Interface） 是 OpenClaw 提出的概念：Agent 主动构建用户界面，而不是被动响应。

传统 AI 助手：

• 用户问："帮我画个架构图"
• AI 回答："这是一个 Mermaid 代码：mermaid..."
• 用户：?? 还要自己复制到 Mermaid 编辑器里才能看到图

OpenClaw 的 Canvas：

• 用户问："帮我画个架构图"
• AI 直接在 Canvas 上渲染出架构图
• 用户可以看到、交互、甚至修改

Canvas 的技术实现

Canvas 是一个本地运行的 Web 视图，Agent 可以通过 RPC 调用控制它的内容：

1// Agent 推送内容到 Canvas
2await canvas.push({
3  type: 'mermaid',
4  content: `
5    graph TD
6      A[用户] --> B[Gateway]
7      B --> C[Pi Agent]
8  `
9});
10
11// Agent 重置 Canvas
12await canvas.reset();
13
14// Agent 执行 JavaScript（在 Canvas 内）
15await canvas.eval(`
16  document.querySelector('.chart').style.background = '#f0f0f0';
17`);
18

关键洞察：Canvas 就像是给 AI 助手提供了一个无限扩展的画布，它可以画图、展示表格、渲染图表、甚至构建简单的交互应用。

Voice Wake+Talk Mode：全时语音交互

文字聊天很方便，但有时候你只想说而不想打字。

Voice Wake（语音唤醒）

就像 Siri 或 Alexa 的 "Hey Siri"，OpenClaw 支持自定义唤醒词：

• 你在电脑上工作，突然想查个资料
• 说出唤醒词（比如 "Hey Claw"）
• OpenClaw 立即进入监听状态
• 你说出问题，它语音回复

技术实现：

• macOS/iOS：使用系统 Speech Recognition API + ElevenLabs TTS
• Android：使用 Android Speech API
• 持续监听：本地处理唤醒词检测，保护隐私

Talk Mode（对话模式）

Voice Wake 是"一问一答"，Talk Mode 则是持续对话：

• 进入 Talk Mode 后，AI 助手保持监听状态
• 你可以像跟朋友聊天一样连续对话
• 支持打断（interrupt）：AI 说话时你也可以插话
• 支持 context 保持：对话历史不丢失

使用场景：

• 头脑风暴时，边说边让 AI 记录和整理
• 编程时，语音描述需求让 AI 生成代码
• 不方便打字的场景（做饭、开车、运动）

Skills Platform：三级插件系统

OpenClaw 的插件系统叫 Skills，分三个层级：

1. Bundled Skills（内置技能）

• 随 OpenClaw 一起发布的官方技能
• 示例：browser（浏览器控制）、canvas（画布）、cron（定时任务）
• 特点：开箱即用，质量有保障

2. Managed Skills（托管技能）

• 社区开发，通过 OpenClaw 官方仓库分发
• 用户通过 CLI 安装：openclaw skills install <skill-name>
• 特点：审核过的第三方技能，安全可控

3. Workspace Skills（工作区技能）

• 用户自己开发的本地技能
• 放在工作区目录下，OpenClaw 自动加载
• 特点：完全自定义，适合特定业务需求

技能开发示例

1// 一个简单的 Skill
2export default {
3  name: 'weather',
4  description: 'Get weather information',
5  
6  async execute({ city }) {
7    const response = await fetch([`https://api.weather.com/v1/current?city=${city}`](https://api.weather.com/v1/current?city=${city}));
8    const data = await response.json();
9    
10    return {
11      text: [`Current weather in ${city}: ${data.temperature}°C, ${data.condition}`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.data.md),
12      temperature: data.temperature,
13      condition: data.condition
14    };
15  }
16};
17

关键洞察：三级技能系统就像是 App Store + 企业应用 + 个人脚本 的结合，既保证了生态丰富性，又保留了灵活度。

技术启发：架构设计的通用性思考

OpenClaw 的架构设计给了我们很多启发，不仅适用于 AI 助手，也适用于其他类型的应用。

启发 1：控制平面与数据平面分离

OpenClaw 的 Gateway 是控制平面，负责连接管理、路由、安全策略；Pi Agent 是数据平面，负责 AI 逻辑。

通用化：

• 聊天应用：Gateway 管理连接，Chat Service 处理消息逻辑
• IoT 平台：Gateway 管理设备连接，Rule Engine 处理业务逻辑
• 实时协作：Gateway 管理用户会话，Collaboration Service 处理文档协作

好处：

• 控制平面可以独立扩展（加更多 Gateway 实例）
• 数据平面可以独立升级（更新 AI 模型不影响连接）
• 支持多种数据平面（可以用同样的 Gateway 接入不同的 AI 模型）

启发 2：统一抽象层应对多样性

OpenClaw 用统一的 Channel 接口接入 12+ 个不同的通讯频道。

通用化：

• 支付系统：统一的 Payment Gateway 接口，接入支付宝、微信、Stripe、PayPal
• 存储系统：统一的 Storage 接口，接入 S3、Azure Blob、本地文件
• 消息队列：统一的 MQ 接口，接入 Kafka、RabbitMQ、RocketMQ

好处：

• 新增渠道只需实现接口，无需改动核心逻辑
• 可以轻松切换底层实现（比如从 WhatsApp 切换到 Telegram）
• 便于测试（可以 mock Channel 接口）

启发 3：WebSocket 作为实时系统的标配

OpenClaw 用 WebSocket 实现双向实时通信。

适用场景：

• 实时协作（Google Docs、Figma）
• 实时游戏（多人在线游戏）
• 实时金融（股票行情、交易系统）
• IoT 实时监控

注意事项：

• WebSocket 连接需要心跳保活
• 需要考虑断线重连机制
• 大规模部署需要负载均衡（Sticky Session）

启发 4：渐进式权限控制

OpenClaw 的 DM 安全策略从 "完全开放" 到 "完全封闭" 之间有多个层级（pairing → allowlist → open）。

通用化：

• API 权限：公开 API → 需要 API Key → 需要 OAuth → 需要特定 Scope
• 文件访问：公开下载 → 需要登录 → 需要特定权限 → 完全私有
• 功能开放：Beta 功能 → 灰度发布 → 全量发布

好处：

• 可以根据安全需求灵活调整
• 便于逐步开放功能，降低风险
• 用户可以选择自己舒适的隐私级别

启发 5：本地优先 + 云端可选

OpenClaw 的设计是"本地优先"：

• 默认 Gateway 运行在本地（ws://127.0.0.1:18789）
• 数据存储在本地
• 也可以部署到远程服务器（通过 Tailscale、SSH 隧道）

这种模式的优点：

• 隐私可控：敏感数据不出本机
• 离线可用：即使没有网络也能用（只要 AI 模型本地运行）
• 云端可选：需要远程访问时，可以通过安全隧道连接

适用场景：

• 个人知识管理工具
• 隐私敏感的 AI 应用
• 边缘计算场景

总结：从OpenClaw学到的5个架构原则

1. 控制平面与数据平面分离：Gateway 负责连接，Agent 负责逻辑，两者可以独立演进
2. 统一抽象层应对多样性：用统一接口封装底层差异，12+ 频道也能管理得井井有条
3. WebSocket 实现实时双向通信：流式输出、打字状态、在线状态，都用 WebSocket 搞定
4. 渐进式权限控制：从 pairing 到 allowlist 到 open，给用户选择权，给开发者灵活度
5. 本地优先 + 云端可选：数据默认留在本地，需要时可以通过安全隧道远程访问

参考链接

《OpenClaw架构揭秘：178k stars的个人AI助手如何用Gateway模式统一控制12+通讯频道》 是转载文章，点击查看原文。