1. 项目概览

OpenClaw 是一个多通道 AI 网关（Multi-Channel AI Gateway），其核心价值是：作为统一的 AI 助手，同时在多个即时通讯平台上运行，对用户透明地提供 AI 能力。

支持的 IM 平台（20+）

主流IM：WhatsApp，Telegram，Slack，Feishu等，见extensions目录

项目规模

• TypeScript 文件：~4,605 个
• 扩展模块：74+ 个（通道、提供者、工具）
• Gateway 协议文件：246 个
• 移动端：iOS（Swift）、Android（Kotlin）、macOS（Swift）

---

2. 整体架构

2.1 顶层架构图

2.2 部署架构

---

3. 核心模块详解

3.1 目录结构

openclaw/
├── apps/                    # 移动/桌面客户端
│   ├── android/             # Kotlin
│   ├── ios/                 # Swift
│   └── macos/               # Swift
├── extensions/              # 74+ 通道扩展（各 IM 平台）
│   ├── whatsapp/            # 97 文件
│   ├── telegram/            # 70+ 文件
│   ├── discord/             # 60+ 文件
│   ├── slack/               # 50+ 文件
│   └── [17+ more...]
├── packages/                # 外部 Bot 包
│   ├── clawdbot/
│   └── moltbot/
├── src/                     # 核心源码（~4605 TS 文件）
│   ├── gateway/             # Gateway 服务器和协议（246 文件）
│   │   ├── protocol/schema/ # TypeBox 协议模式
│   │   ├── server.impl.ts   # 服务器实现
│   │   ├── server-chat.ts   # 聊天服务
│   │   └── client.ts        # 客户端连接
│   ├── channels/            # 通道核心框架
│   │   └── plugins/         # 插件接口定义
│   │       ├── types.plugin.ts   # 插件合约
│   │       ├── types.adapters.ts # 适配器类型
│   │       ├── types.core.ts     # 核心类型
│   │       ├── normalize/        # 消息规范化
│   │       ├── outbound/         # 出站适配器
│   │       ├── actions/          # 消息操作
│   │       └── contracts/        # 入站消息合约测试
│   ├── auto-reply/          # 自动回复引擎
│   │   ├── dispatch.ts      # 消息分发
│   │   └── reply/           # 回复队列和调度
│   ├── agents/              # AI 代理和任务执行
│   ├── sessions/            # 会话管理
│   ├── routing/             # 消息路由
│   ├── config/              # 配置管理
│   ├── cli/                 # CLI 命令
│   ├── daemon/              # 守护进程
│   ├── canvas-host/         # Canvas A2UI 渲染
│   ├── plugin-sdk/          # 公共插件 SDK
│   └── plugin-sdk-internal/ # 内部插件 SDK
└── test/                    # 测试文件

---

4. 第三方 IM 通讯机制

OpenClaw 只是 Agent 控制层，IM 只是一个 消息通道。这是 OpenClaw 最核心的设计，通过统一的「通道插件接口」屏蔽了各平台的差异。

典型架构：

Telegram / WhatsApp / Discord
            │
            │ (Bot API / WebSocket / Web Protocol)
            ▼
      IM Adapter / Connector
            │
            │ (统一消息格式)
            ▼
        OpenClaw Agent
   ├── LLM (Claude / GPT / DeepSeek)
   ├── Memory
   ├── Tools
   └── Planner
            │
            ▼
        回复消息
            │
            ▼
        发回 IM

核心思想：

IM → Adapter → Agent → 回复 → Adapter → IM

4.1 通道插件接口（ChannelPlugin）

每个 IM 平台都实现 ChannelPlugin<ResolvedAccount> 接口，这是所有通道的核心合约：

// src/channels/plugins/types.plugin.ts
type ChannelPlugin<ResolvedAccount, Probe, Audit> = {
  id: ChannelId;                                // 唯一标识："whatsapp" | "telegram" | ...
  meta: ChannelMeta;                            // 标签、文档等元数据
  capabilities: ChannelCapabilities;            // 功能声明（群聊、投票、媒体等）

  // 核心适配器（按需实现）
  config: ChannelConfigAdapter;                 // 账户配置
  pairing?: ChannelPairingAdapter;              // 配对流程（QR 码等）
  security?: ChannelSecurityAdapter;            // 安全策略（白名单等）
  outbound?: ChannelOutboundAdapter;            // 出站消息发送
  messaging?: ChannelMessagingAdapter;          // 入站消息处理
  gateway?: ChannelGatewayAdapter;              // WebSocket 连接生命周期
  auth?: ChannelAuthAdapter;                    // 认证流程
  lifecycle?: ChannelLifecycleAdapter;          // 启动/停止/重连
  actions?: ChannelMessageActionAdapter;        // 消息操作（编辑、删除、反应）
  heartbeat?: ChannelHeartbeatAdapter;          // 心跳保活
  threading?: ChannelThreadingAdapter;          // 线程和回复管理
}

4.2 适配器职责分工

4.3 Telegram 通讯深度解析

Telegram 使用官方 Bot API，通过 Grammy 框架实现长轮询：

Telegram 特色功能：

// extensions/telegram/src/outbound-adapter.ts
// 话题（Topic）支持 - 超级群组中的线程
parseTelegramTopicConversation({ conversationId })
  → { chatId: "-1001234567", topicId: "42" }

// 内联按钮（执行审批）
buildTelegramExecApprovalButtons(request)
  → [[✅ 批准], [❌ 拒绝]]

// Markdown → Telegram HTML 转换
markdownToTelegramHtmlChunks(text, { limit: 4000 })
  → ["<b>chunk1</b>", "<i>chunk2</i>", ...]

4.4 消息规范化（Normalization）

所有平台的消息都必须规范化为统一格式才能进入核心引擎：

统一入站消息结构：

type InboundMessage = {
  id: string;                    // 消息 ID
  channelId: ChannelId;          // 平台标识
  accountId: string;             // 账户 ID
  sessionKey: string;            // 会话键（路由用）
  peer: { kind: "user" | "group", id: string };
  from: { id: string, name?: string, isBot?: boolean };
  text?: string;                 // 文本内容
  mediaUrls?: string[];          // 媒体 URL
  replyToId?: string;            // 回复的消息 ID
  threadId?: string;             // 线程 ID
  chatType: "direct" | "group" | "channel" | "thread";
  timestamp: number;
  raw?: unknown;                 // 平台原始消息
}

4.5 出站消息（ReplyPayload）

AI 处理后的输出也有统一格式，再由各平台适配器转换：

type ReplyPayload = {
  text?: string;                 // 文本回复
  mediaUrl?: string;             // 单个媒体
  mediaUrls?: string[];          // 多个媒体
  interactive?: InteractiveReply; // 按钮、菜单、卡片
  replyToId?: string;            // 回复特定消息
  audioAsVoice?: boolean;        // WhatsApp 语音消息
  isError?: boolean;             // 错误消息
  isReasoning?: boolean;         // AI 思维块（部分平台隐藏）
  channelData?: Record<string, unknown>; // 平台特定数据
}

---

5. Gateway 协议

Gateway 是 OpenClaw 的「控制平面」，使用 WebSocket + JSON 帧协议连接客户端和服务器。

5.1 协议握手流程

5.2 帧格式定义

// src/gateway/protocol/schema/frames.ts

// 请求帧（客户端 → 服务器）
RequestFrame = {
  type: "req",
  id: string,          // UUID，关联响应
  method: string,      // RPC 方法名
  params?: unknown     // 参数
}

// 响应帧（服务器 → 客户端）
ResponseFrame = {
  type: "res",
  id: string,          // 对应请求的 UUID
  ok: boolean,
  payload?: unknown,   // 成功时的数据
  error?: {
    code: string,
    message: string,
    details?: unknown,
    retryable?: boolean,
    retryAfterMs?: number
  }
}

// 事件帧（服务器 → 客户端，单向推送）
EventFrame = {
  type: "event",
  event: string,       // 事件名
  payload?: unknown,
  seq?: number,        // 序列号（检测丢包）
  stateVersion?: StateVersion
}

5.3 Gateway RPC 方法

// 通道操作
"channels.status"              // 获取所有通道状态快照
"channels.logout"              // 登出账户
"channels.<id>.setup"          // 通道特定设置

// 聊天消息
"chat.send"                    // 发送消息
"chat.inject"                  // 注入消息（模拟收到）
"chat.abort"                   // 中止正在生成的回复

// 会话管理
"sessions.list"                // 列出会话
"sessions.patch"               // 修改会话属性
"sessions.preview"             // 预览会话

// 配置管理
"config.get"                   // 获取配置
"config.set"                   // 设置配置
"config.apply"                 // 应用配置变更

// 代理操作
"agent.create"                 // 创建 AI 代理
"agent.update"                 // 更新代理
"agent.delete"                 // 删除代理

5.4 Gateway 客户端实现

// src/gateway/client.ts - GatewayClient 类

class GatewayClient {
  // 认证优先级（从高到低）
  // 1. 显式 token
  // 2. Bootstrap token（初始配对）
  // 3. Device token（持久化到 ~/.openclaw/device-tokens/）
  // 4. 密码认证

  // 安全检查（CWE-319, CVSS 9.8）
  if (!isSecureWebSocketUrl(url)) {
    throw "SECURITY ERROR: 非本地地址必须使用 wss://";
    // 建议：SSH 隧道 / Tailscale / wss://
  }

  // TLS 指纹钉扎（防中间人攻击）
  if (url.startsWith("wss://") && opts.tlsFingerprint) {
    checkServerIdentity: validateFingerprint256(cert);
  }

  // 自动重连（指数退避：1s → 30s）
  // Tick 心跳（>2× tickInterval 无响应时断开重连）
}

---