OpenClaw 架构深度解析：构建多渠道 AI 网关的完整指南

吃素的老虎
9 阅读1分钟

OpenClaw 架构深度解析

本文深入分析 OpenClaw 的核心架构，帮助你理解其设计思想，为构建自己的 AI 网关系统提供参考。

🎯 OpenClaw 是什么？

OpenClaw 是一个多渠道 AI 网关，它能让你在各种聊天平台（WhatsApp、Telegram、Discord、微信等）上使用 AI 助手。其核心特点：

  • 统一消息协议：屏蔽不同平台的 API 差异
  • WebSocket 网关：实时双向通信
  • 插件化架构：渠道、技能都可扩展
  • 技能系统：类似 ChatGPT Plugins 的能力扩展

📐 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                      Chat Channels (消息渠道)                     │
│      WhatsApp | Telegram | Discord | Slack | Signal | ...       │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Channel Extensions (渠道扩展)                  │
│              每个渠道一个独立插件，适配消息格式和 API               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Gateway (核心网关)                           │
│         WebSocket 服务器 | 认证 | 心跳 | 消息路由                  │
└──────────────────────────┬──────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │   Agent     │  │   Nodes     │  │   Clients   │
   │  (LLM运行时) │  │ (设备节点)   │  │  (CLI/UI)   │
   └──────┬──────┘  └─────────────┘  └─────────────┘
          │
          ▼
   ┌─────────────┐
   │   Skills    │
   │  (技能系统)  │
   └─────────────┘

🔧 核心组件详解

1. Gateway（核心网关）

Gateway 是 OpenClaw 的心脏，负责：

1.1 WebSocket 服务器
  • 默认端口：127.0.0.1:18789
  • 传输协议：WebSocket，文本帧，JSON 格式
  • 单一实例：每个主机只能运行一个 Gateway
1.2 消息协议设计

OpenClaw 使用类似 JSON-RPC 的协议：

// 请求消息
{
  "type": "req",
  "id": "req-1",
  "method": "connect",  // 方法名
  "params": { ... }     // 参数
}

// 成功响应
{
  "type": "res",
  "id": "req-1",
  "ok": true,
  "payload": { ... }
}

// 错误响应
{
  "type": "res",
  "id": "req-1",
  "ok": false,
  "error": "错误信息"
}

// 事件消息（服务端主动推送）
{
  "type": "event",
  "event": "presence",
  "payload": { ... },
  "seq": 123,
  "stateVersion": "v1"
}
1.3 连接生命周期
Client                Gateway
  │                      │
  │──── connect ────────>│  (握手)
  │<─── hello-ok ────────│  (或 error + close)
  │                      │
  │<─── event:presence ──│  (推送事件)
  │<─── event:tick ──────│
  │                      │
  │──── req:agent ──────>│  (发起请求)
  │<─── res:agent ───────│  (响应)
  │<─── event:agent ─────│  (流式事件)
1.4 认证机制
  • Token 认证：设置 OPENCLAW_GATEWAY_TOKEN
  • 设备配对：新设备需要审批
  • 本地自动审批：loopback 或同主机连接可自动通过

2. Channel Extensions（渠道扩展）

2.1 插件结构

每个渠道扩展是一个独立插件：

extensions/telegram/
├── openclaw.plugin.json   # 插件配置
├── index.ts               # 入口文件
├── src/
│   ├── channel.ts         # 渠道实现
│   └── runtime.ts         # 运行时支持
└── package.json
2.2 插件配置示例
{
  "id": "telegram",
  "channels": ["telegram"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
2.3 插件注册
const plugin = {
  id: "telegram",
  name: "Telegram",
  description: "Telegram channel plugin",
  configSchema: emptyPluginConfigSchema(),
  register(api: OpenClawPluginApi) {
    setTelegramRuntime(api.runtime);
    api.registerChannel({ plugin: telegramPlugin });
  },
};

export default plugin;
2.4 支持的渠道
渠道实现方式特点
WhatsAppBaileys需要 QR 配对
TelegramgrammY Bot API简单配置
DiscordDiscord.js支持服务器/频道/DM
SlackBolt SDK工作区应用
Signalsignal-cli隐私优先
iMessageBlueBubbles需要macOS服务端
FeishuWebSocket飞书机器人
WeChat企业微信API企业微信

3. Agent Runtime（Agent 运行时）

3.1 工作空间

Agent 使用单一工作目录：

~/.openclaw/workspace/
├── AGENTS.md       # 操作指令 + 记忆
├── SOUL.md         # 人格设定
├── TOOLS.md        # 工具使用说明
├── USER.md         # 用户信息
├── IDENTITY.md     # Agent 身份
└── BOOTSTRAP.md    # 首次运行仪式（完成后删除）
3.2 工具系统

Agent 拥有内置工具：

  • read - 读取文件
  • write - 写入文件
  • edit - 精确编辑
  • exec - 执行命令
  • web_search - 网络搜索
  • browser - 浏览器控制
  • ... 更多工具
3.3 技能加载

技能从三个位置加载（优先级递增）：

  1. 内置技能：随 OpenClaw 发布
  2. 管理目录：~/.openclaw/skills
  3. 工作空间：<workspace>/skills

4. Skills System（技能系统）

4.1 技能结构
skills/my-skill/
├── SKILL.md          # 技能定义文件
├── scripts/          # 脚本文件
│   └── main.py
└── references/       # 参考文档
    └── api.md
4.2 SKILL.md 格式
---
name: my-skill
version: 1.0.0
description: 技能描述
metadata:
  openclaw:
    requires:
      bins: ["python3"]
    install:
      - id: "node"
        kind: "node"
        package: "some-package"
---

# 技能名称

使用说明...
4.3 技能管理
# 搜索技能
clawhub search "关键词"

# 安装技能
clawhub install my-skill

# 更新技能
clawhub update my-skill

# 发布技能
clawhub publish ./my-skill

5. Session Management（会话管理）

5.1 会话隔离策略
{
  session: {
    dmScope: "per-channel-peer",  // DM 隔离策略
    // 可选值：
    // - "main": 所有 DM 共享一个会话
    // - "per-peer": 按发送者隔离
    // - "per-channel-peer": 按渠道+发送者隔离
    // - "per-account-channel-peer": 按账号+渠道+发送者隔离
  }
}
5.2 会话键映射
场景会话键格式
主会话agent:<agentId>:main
按发送者DMagent:<agentId>:dm:<peerId>
群组agent:<agentId>:<channel>:group:<id>
频道agent:<agentId>:<channel>:channel:<id>
Cron任务cron:<job.id>
5.3 会话维护
{
  session: {
    maintenance: {
      mode: "enforce",      // warn | enforce
      pruneAfter: "30d",    // 清理超过30天的会话
      maxEntries: 500,      // 最大会话数
      rotateBytes: "10mb",  // 日志轮转大小
    }
  }
}

🔄 消息流程

入站消息流程

用户消息
    │
    ▼
┌──────────────┐
│ Channel Ext  │ ← 接收平台消息
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Gateway    │ ← 消息路由
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Session    │ ← 加载会话上下文
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    Agent     │ ← LLM 处理
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    Reply     │ ← 生成回复
└──────┬───────┘
       │
       ▼
用户收到回复

🎨 设计亮点

1. 插件化架构

  • 渠道插件：每个聊天平台一个独立扩展
  • 技能插件：按需加载的能力扩展
  • 热插拔：无需重启即可添加新渠道

2. 协议设计

  • 统一协议：所有渠道使用相同的消息格式
  • 幂等性保证：使用 idempotency key 防止重复
  • 流式响应：支持 SSE 流式输出

3. 安全设计

  • 设备配对：新设备需要审批
  • Token 认证：网关级别的访问控制
  • DM 隔离：防止跨用户信息泄露

4. 可扩展性

  • 技能商店：ClawHub 生态系统
  • 自定义工具：通过 exec 执行任意命令
  • 多模型支持：OpenAI、Anthropic、本地模型等

📊 关键代码统计

组件文件数说明
Gateway 核心~100+dist/ 目录
渠道扩展41extensions/ 目录
内置技能52skills/ 目录
文档200+docs/ 目录

🚀 学习要点

对于 MyClaw 项目

从 OpenClaw 学习：

  1. WebSocket 协议设计：请求-响应-事件三元组
  2. 插件架构：渠道扩展的标准模式
  3. 会话管理：多种隔离策略
  4. 技能系统：SKILL.md 的规范设计
  5. 安全机制：设备配对和 Token 认证

推荐阅读源码

openclaw/
├── docs/
│   ├── gateway/protocol.md    # 协议规范
│   ├── concepts/architecture.md # 架构概述
│   └── concepts/session.md    # 会话管理
├── extensions/telegram/       # 渠道扩展示例
└── skills/clawhub/            # 技能示例

📚 参考资源

OpenClaw 是一个设计精良的多渠道 AI 网关实现，通过学习其架构，我们可以更好地理解如何构建类似的系统。下一篇将分析具体的渠道扩展实现细节。

avatar
文章
阅读
粉丝