OpenClaw 架构解析：如何让一个 AI Agent 对接所有消息渠道

Simi 收录于 AI Agent

2025-01-10 约 1400 字预计阅读 3 分钟

问题的本质

AI Agent 开发完之后，总要接一个对话渠道。

第一个念头是 Telegram Bot。但当你需要同时接飞书、Discord、Slack，而且要让 Agent 在各个渠道里保持一致的状态和记忆，问题就复杂了。

每个渠道的 API 都不一样：Telegram 用 Bot API，Discord 用 Webhook，WhatsApp 用 Baileys，飞书用 HTTP API。每个渠道的错误处理、重连逻辑、消息格式都不一样。

你的 Agent core 写一遍，但每个渠道都要写一套适配代码。

OpenClaw 的解决思路

OpenClaw 干了这件事：

用户消息 → 渠道接入层 → Gateway (WebSocket) → Agent Runtime → 你的 Agent
                    ↑                                      ↓
                    └──────── 响应 ←───────────────────────┘

核心是一个 Gateway daemon。它：

管理所有渠道连接（WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, etc.）
暴露 WebSocket API 给 Agent runtime
统一消息协议，不管哪个渠道进来的，都转成一样的格式给 Agent

你的 Agent 只需要对接 Gateway 的 WebSocket API，不用管后面连的是 Telegram 还是飞书。

核心架构

根据 OpenClaw 文档，Gateway 的结构：

组件

Gateway (daemon): 主进程，维护所有 provider 连接
Clients: macOS app, CLI, web admin UI 等控制面客户端
Nodes: macOS/iOS/Android/headless 节点，暴露设备能力（canvas, camera, screen record 等）

连接流程

sequenceDiagram participant Client participant Gateway Client->>Gateway: req:connect Gateway-->>Client: res (ok) Note right of Gateway: 或 res error + close Gateway-->>Client: event:presence Gateway-->>Client: event:tick Client->>Gateway: req:agent Gateway-->>Client: res:agent Gateway-->>Client: event:agent (streaming) Gateway-->>Client: res:agent (final)

Client 发起 connect 请求，之后通过 WebSocket 收发消息。Agent 请求通过 req:agent，结果通过 event:agent 流式推送回来。

消息协议

        
        
        
    
// 请求
{
  "type": "req",
  "id": "unique-id",
  "method": "agent",
  "params": {
    "message": "帮我查一下天气"
  }
}

// 响应
{
  "type": "res",
  "id": "unique-id",
  "ok": true,
  "payload": { ... }
}

// 服务端事件
{
  "type": "event",
  "event": "agent",
  "payload": { ... }
}

所有帧都是 JSON over WebSocket。没有 HTTP 轮询，没有 REST，全双工流式。

关键设计决策

1. 一个 Gateway，一个端口

每个 host 上只跑一个 Gateway 实例。它监听一个端口（默认 127.0.0.1:18789），所有客户端和节点都连这个端口。

好处：简化部署。不用为每个渠道单独开端口，也不用管 NAT 映射。

2. Device-based pairing

节点（手机、桌面客户端）通过 device pairing 接入 Gateway，而不是用户账号。Approval 存在 Gateway 本地。

这意味着：如果你有 5 台设备，它们都可以连接同一个 Gateway，但每台设备需要单独配对授权。

3. Canvas host

Gateway 还 serving 了一个 HTTP server：

/__openclaw__/canvas/ — Agent 可编辑的 HTML/CSS/JS
/__openclaw__/a2ui/ — A2UI host

这让 Agent 可以生成网页并让用户在浏览器里查看。比如数据分析 Agent 生成图表，Agent 直接把页面 serve 出来。

与传统 Bot 框架的对比

	传统 Bot 框架	OpenClaw
多渠道	每个渠道独立项目	统一接入
状态管理	各渠道独立	共享 Agent state
部署	每个 Bot 独立部署	一个 Gateway
设备能力	无	支持 camera/screen/location
协议	各渠道私有	统一 WebSocket

适合谁

OpenClaw 最适合的场景：

个人 AI Assistant：你在自己多台设备上跑 AI Agent，通过不同渠道跟它交互
多渠道客服/助手：一个 Agent 对接公司所有对外渠道，统一回复逻辑
需要设备能力的 Agent：比如需要调用手机摄像头、屏幕录制

如果只是做一个 Telegram Bot，OpenClaw 过度了。但当你需要「一个 AI Agent，多个入口」，OpenClaw 的价值就显现了。

局限性

学习曲线：理解 Gateway + Client + Node 的关系需要时间
不是可视化平台：配置靠 JSON，不是拖拽
生产部署：需要考虑 Gateway 的 HA 和横向扩展
渠道支持有限：不是所有渠道都支持，WhatsApp 支持依赖 Baileys 库

总结

OpenClaw 的核心抽象：Gateway as the hub。

你的 AI Agent 只需要对接 Gateway 的 WebSocket API，Gateway 负责对接所有下游消息渠道。这比你给每个渠道写适配代码干净得多。

当然，这是个相对新的项目（从 GitHub activity 来看），生产环境使用需要评估稳定性和社区支持。

项目地址：github.com/openclaw/openclaw

目录