Socket Chat

Name: Socket Chat
Rating: 3.5 (1 reviews)
Author: leochen-g

By leochen-g 👁 50 views ▲ 0 votes

OpenClaw Socket Chat channel plugin — MQTT-based IM bridge

GitHub

Install

npm install
```

Configuration Example

channels:
  socket-chat:
    apiKey: "your-api-key"
    apiBaseUrl: "https://your-backend.com"
    enabled: true
    dmPolicy: "pairing"   # pairing | open | allowlist
    allowFrom: []         # 允许触发 AI 的发送者 ID 白名单
    requireMention: true  # 群组消息是否需要 @提及机器人

README

# socket-chat OpenClaw Extension

通过 **MQTT** 协议与自定义 IM 系统对接的 OpenClaw channel plugin。

---

## 工作原理

```
IM 平台 ──MQTT──► reciveTopic ──► socket-chat plugin ──► OpenClaw AI
OpenClaw AI ──► socket-chat plugin ──MQTT──► sendTopic ──► IM 平台
```

1. 插件启动时，调用 `GET /api/openclaw/chat/config?apikey={apiKey}` 获取 MQTT 连接参数
2. 建立 MQTT 连接，订阅 `reciveTopic`
3. 收到消息后，通过 `channelRuntime` 派发给 AI agent
4. AI 回复通过 `outbound.sendText/sendMedia` 向 `sendTopic` 发布

---

## 安装

```bash
# 在 openclaw 项目目录中安装此插件
openclaw plugins add /path/to/socket-chat
# 或者（发布到 npm 后）
openclaw plugins add @openclaw/socket-chat
```

安装插件依赖：

```bash
cd /path/to/socket-chat
npm install
```

---

## 配置

在 `~/.openclaw/config.yaml` 中添加：

```yaml
channels:
  socket-chat:
    apiKey: "your-api-key"
    apiBaseUrl: "https://your-backend.com"
    enabled: true
    dmPolicy: "pairing"   # pairing | open | allowlist
    allowFrom: []         # 允许触发 AI 的发送者 ID 白名单
    requireMention: true  # 群组消息是否需要 @提及机器人
```

### 多账号配置

```yaml
channels:
  socket-chat:
    accounts:
      work:
        apiKey: "work-api-key"
        apiBaseUrl: "https://work.example.com"
        enabled: true
      personal:
        apiKey: "personal-api-key"
        apiBaseUrl: "https://personal.example.com"
        enabled: true
```

### 可选高级配置

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `mqttConfigTtlSec` | `300` | MQTT 配置缓存时间（秒） |
| `maxReconnectAttempts` | `10` | MQTT 断线最大重连次数 |
| `reconnectBaseDelayMs` | `2000` | 重连基础延迟（毫秒，指数退避） |
| `useTls` | `false` | 是否使用 `mqtts://`（TLS） |

---

## 通过 CLI 添加账号

```bash
openclaw channels add socket-chat --token <apiKey> --http-url <apiBaseUrl>
```

---

## 消息格式

### 收到的 MQTT 消息（reciveTopic）

文字消息：

```json
{
  "content": "消息内容",
  "robotId": "wxid_robot",
  "senderId": "wxid_user123",
  "senderName": "用户昵称",
  "isGroup": false,
  "groupId": "roomid_xxx",
  "groupName": "群组名称",
  "timestamp": 1234567890123,
  "messageId": "uuid-xxx",
  "type": "文字"
}
```

图片 / 视频 / 文件消息（已上传 OSS）：

```json
{
  "content": "【图片消息】\n文件名：img.jpg\n下载链接：https://oss.example.com/img.jpg",
  "robotId": "wxid_robot",
  "senderId": "wxid_user123",
  "senderName": "用户昵称",
  "isGroup": false,
  "timestamp": 1234567890123,
  "messageId": "uuid-xxx",
  "type": "图片",
  "url": "https://oss.example.com/img.jpg"
}
```

> **说明**：`type` 枚举值包括 `文字`、`图片`、`视频`、`文件`、`语音`、`名片`、`h5链接`、`视频号`、`位置`、`历史记录`。
>
> 图片/视频等媒体消息会同时携带 `content`（格式化描述文字）和 `url`（资源链接）。若平台未配置 OSS，`url` 为 base64 字符串，插件会忽略 base64 内容，仅将 `content` 描述文字传给 AI agent。

#### 媒体消息处理逻辑

| 场景 | `content` | `url` | AI 收到的内容 |
|------|-----------|-------|--------------|
| 纯文字 | 消息文本 | — | 消息文本 |
| 图片（有 OSS URL） | 包含下载链接的描述 | HTTP URL | 描述文字 + `MediaUrl` 字段 |
| 图片（无 OSS，base64） | 包含 base64 的描述 | `data:image/...` | 仅描述文字（base64 被过滤） |
| 仅有 URL、无 content | — | HTTP URL | `<media:图片>` placeholder |

### 发送的 MQTT 消息（sendTopic）

```json
{
  "isGroup": false,
  "contactId": "wxid_user123",
  "messages": [
    { "type": 1, "content": "文字消息" }
  ]
}
```

群消息 + @提及：
```json
{
  "isGroup": true,
  "groupId": "roomid_xxx",
  "mentionIds": ["wxid_a", "wxid_b"],
  "messages": [
    { "type": 1, "content": "回复内容" },
    { "type": 2, "url": "https://example.com/image.jpg" }
  ]
}
```

---

## 发消息目标格式（openclaw message send）

| 格式 | 说明 |
|------|------|
| `wxid_xxx` | 私聊某用户 |
| `group:roomid_xxx` | 发到群组 |
| `group:roomid_xxx@wxid_a,wxid_b` | 发到群组并 @提及用户 |

```bash
openclaw message send "Hello" --channel socket-chat --to wxid_user123
openclaw message send "Hello group" --channel socket-chat --to group:roomid_xxx
```

---

## 项目结构

```
socket-chat/
├── index.ts              # 插件入口（register）
├── package.json          # 包配置，含 openclaw.extensions
├── tsconfig.json
└── src/
    ├── types.ts          # MQTT 消息类型定义
    ├── config-schema.ts  # Zod 配置 Schema
    ├── config.ts         # 账号配置解析 + 写入工具
    ├── api.ts            # GET /api/openclaw/chat/config 调用（带缓存）
    ├── outbound.ts       # 发送消息（buildPayload + sendSocketChatMessage）
    ├── inbound.ts        # 入站消息处理 → dispatch AI 回复
    ├── mqtt-client.ts    # MQTT 连接管理 + 自动重连 monitor 循环
    ├── probe.ts          # 账号连通性探测
    ├── runtime.ts        # PluginRuntime 单例
    └── channel.ts        # ChannelPlugin 主体（所有 adapter 实现）
```

---

## API 接口要求

后端需实现：

### `GET /api/openclaw/chat/config?apikey={apiKey}`

**Response 200:**
```json
{
  "host": "mqtt.example.com",
  "port": "1883",
  "username": "mqttuser",
  "password": "mqttpass",
  "clientId": "openclaw-bot-001",
  "reciveTopic": "/im/botId/msg",
  "sendTopic": "/im/botId/send",
  "robotId": "wxid_bot",
  "userId": "user123"
}
```

所有字段均为必填字符串。

channels