02 - 架构核心能力验证

技术研究人工智能 AI Agent

!-- 详细分析 Gateway 架构、协议设计与组件交互 --

Gateway 架构概述

OpenClaw 的核心是一个集中式的 Gateway（网关），它作为单一控制平面负责协调所有组件之间的通信。这种架构设计巧妙地解决了多平台、多客户端、多工具之间的复杂交互问题。

架构设计哲学

Gateway 架构遵循以下设计原则：

单一真源 (Single Source of Truth)：所有状态管理集中在 Gateway，避免分布式状态同步的复杂性
协议统一：无论消息来自 WhatsApp、Telegram 还是 Slack，都转换为统一的内部协议处理
解耦设计：Clients、Nodes、AI Agent 通过 Gateway 间接通信，降低组件间耦合度
本地优先：默认绑定 localhost，确保隐私和安全，同时支持安全的远程访问扩展

核心组件拓扑

Gateway (ws://127.0.0.1:18789)
├── Channels: WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord
├── Session Manager: 会话状态、上下文、修剪策略
├── Agent Runtime: Pi Agent、工具调用、模型路由
├── Tool Registry: Skills 加载、动态发现
└── WebSocket Server: 客户端连接、事件推送

Connected Clients:
├── CLI / macOS App / Web UI (control clients)
└── iOS / Android Nodes (device capabilities)

WebSocket 协议详解

协议分层设计

Gateway 使用自定义的 WebSocket 协议栈，分为三层：

1. 传输层: WebSocket 文本帧传输 JSON 消息，支持本地连接和远程隧道 2. 会话层: 首次连接握手、设备身份验证、心跳检测 3. 应用层: Request/Response 模式、Event 推送、工具调用 RPC

消息帧格式

连接握手:

{
  "type": "connect",
  "id": "conn-001",
  "params": {
    "deviceId": "macbook-pro-001",
    "role": "client",
    "auth": {"token": "device-token-here"},
    "caps": ["canvas", "camera"]
  }
}

请求/响应模式:

// Request
{"type": "req", "id": "req-123", "method": "agent", "params": {"message": "..."}}
// Response
{"type": "res", "id": "req-123", "ok": true, "payload": {"runId": "run-456"}}

连接生命周期

Client                    Gateway
  |---- connect --------->|
  |<---- res (ok) -----|
  |<---- event:presence|
  |---- req:agent ------>|
  |<---- event:agent ---| (streaming)
  |<---- res:agent -----| (final)

组件职责

Gateway 守护进程

通道管理: 维护各平台持久连接，消息格式转换
会话管理: 每个对话对应一个 Session，存储历史和上下文
Agent 运行时: 集成 Pi Agent，支持工具流式调用
工具注册表: 加载 bundled skills 和 workspace skills

客户端类型

控制客户端 (CLI, macOS App, Web UI):

Gateway 状态监控
发送 Agent 执行请求
管理配置和通道

节点客户端 (iOS, Android, macOS):

canvas.*: 渲染可视化界面
camera.*: 拍照录像
screen.record: 屏幕录制
location.get: 地理位置
system.run: 本地命令执行

结论

Gateway 架构通过统一的 WebSocket 协议和集中式状态管理，实现了多平台消息路由、多客户端协调和多工具调用的复杂功能。其设计核心是解耦和协议统一，为后续工具扩展奠定了坚实基础。