@partme.ai/openclaw-web-mqtt

v2026.5.25-2

Published

6 days ago

Enterprise-grade MQTT over WebSocket channel plugin for OpenClaw

0High
0Medium
0Low

partme

openclaw plugin mqtt websocket web protocol-bridge

OpenClaw Web MQTT

OpenClaw 渠道插件：企业级 MQTT over WebSocket，支持 topic 治理与 agent 绑定

简体中文 | English

简介

@partme.ai/openclaw-web-mqtt 是基于 OpenClaw 最新 channel SDK 的渠道插件：

使用 defineChannelPluginEntry 进行完整注册
使用 defineSetupPluginEntry 支持 setup-only 轻量加载
使用 runtime store 管理 runtime 注入与读取

插件提供内嵌强化版 MQTT over WebSocket broker，面向浏览器与 Web 应用接入，并将入站消息路由给 OpenClaw Agent。

核心能力

多 topic 订阅治理：subscribeTopics 白名单，支持 +/# 通配符
topic-agent 显式绑定：topicPattern -> agentId，支持绑定 replyTopic
标准路由回退：<topicPrefix>agent/<agentId>/in -> <topicPrefix>agent/<agentId>/out
企业级增强：
- 鉴权与用户级 topic 访问控制
- TLS/WSS 支持
- 消息大小与 WebSocket 帧大小限制
- 空闲超时与连接治理
- 路由命中与丢弃原因统计

消息处理流程

Web MQTT 客户端发布消息
插件按 subscribeTopics 过滤
路由决策：
- 优先 topicBindings
- 回退标准 topic
payload 按 jsonTextOrPlain 解析
进入 OpenClaw reply pipeline
回复发布到绑定 replyTopic 或默认 out topic

快速开始

前置条件

OpenClaw >= 2026.4.0
Node.js 22+

安装

openclaw plugins install @partme.ai/openclaw-web-mqtt

最低依赖：@partme.ai/openclaw-message-sdk >= 2026.5.22。

message-sdk 复用

MQTT over WebSocket 传输与 ACL 留在本插件；下列能力通过 薄封装 委托 message-sdk：

| message-sdk 模块 | web-mqtt 挂载点 | 用途 | |------------------|-----------------|------| | ingress/wire-ingress（normalizeWireIngress） | inbound.ts | 入站 payload 解析 + 幂等短路 | | dedup（createIdempotencyCache + getGlobalSingleton） | shared/wire-helpers.ts | 入站 messageId / 指纹去重 | | bridge（dispatchChannelMessage、resolveChannelDispatchIdentity） | inbound.ts | Wire 路径 OpenClaw reply 管线 | | pipeline/serialize-payload | inbound.ts reply.deliver | 出站 wire 序列化（envelope / legacyJsonText / plainText） | | config/resolveChannelAgentReplyTimeoutMs | config/resolvers.ts | Agent 回复超时 | | config/resolveChannelMediaMaxBytes | config/resolvers.ts | 媒体/载荷上限解析 |

最小配置（`openclaw.json`）

{
  "channels": {
    "mqtt-ws": {
      "port": 15675,
      "path": "/ws",
      "topicPrefix": "openclaw/",
      "subscribeTopics": [
        "openclaw/agent/+/in",
        "devices/+/in"
      ],
      "topicBindings": [
        {
          "topicPattern": "devices/+/in",
          "agentId": "iot-agent",
          "replyTopic": "devices/reply"
        }
      ],
      "payload": { "mode": "jsonTextOrPlain" },
      "auth": {
        "required": true,
        "allowAnonymous": false,
        "users": [
          {
            "username": "mqtt_user",
            "password": "change_me",
            "publishAllow": ["openclaw/agent/+/in", "devices/+/in"],
            "subscribeAllow": ["openclaw/agent/+/out", "devices/reply"]
          }
        ]
      },
      "tls": {
        "enabled": false
      },
      "ws": {
        "compress": true,
        "idleTimeoutMs": 60000,
        "maxFrameSize": 262144
      },
      "limits": {
        "maxPayloadBytes": 1048576,
        "maxSubscriptionsPerClient": 200
      }
    }
  }
}

企业级加固建议

可靠性矩阵与生产配置：队列可靠性指南

| 项 | 行为 | |----|------| | 分级 | 协议限制需文档约束（QoS0 即时 PUBACK） | | 入站 | per-clientId 串行 dispatch；processInbound await | | 出站 | publishToTopic await | | 隔离 | server publish 不触发入站；ACL + topic 白名单 |

强制替换默认账号，使用独立 MQTT 用户
生产环境开启 tls.enabled，部署 WSS
严格配置 publishAllow / subscribeAllow
按流量调优 maxPayloadBytes、maxFrameSize、idleTimeoutMs
配合反向代理与网络 ACL 做边界隔离

状态与可观测性

GET /mqtt-ws/status（插件鉴权路由）输出：

当前连接数
入站接受/丢弃计数
binding 与标准回退路由命中计数
出站发布计数
最近错误摘要
脱敏后的生效配置快照

测试

单元测试

npm test

集成测试端

npm run test:client

默认测试端点：

MQTT_BROKER_URL=ws://127.0.0.1:15675/ws

支持环境变量：

MQTT_BROKER_URL
MQTT_CLIENT_ID
MQTT_TEST_TIMEOUT_MS
MQTT_TEST_SUBSCRIBE_TOPICS
MQTT_TEST_PUBLISH_CASES
MQTT_TEST_TOPIC_JSON
MQTT_TEST_TOPIC_PLAIN
MQTT_TEST_REPLY_TOPIC

CI 与发版

| 工作流 | 触发方式 | 作用 | | --- | --- | --- | | .github/workflows/ci.yml | Push / PR | 安装、类型检查、构建、测试、上传产物 | | .github/workflows/release.yml | v* tag / 手动触发 | 构建、测试并发布 npm（已存在版本自动跳过） |

发版细节见 RELEASING.md。

RabbitMQ Web-MQTT 兼容基线

本插件参考 RabbitMQ Web-MQTT 官方生产实践：

默认 websocket 端点约定 15675/ws
明确插件启用与独立用户策略
WSS/TLS 生产部署建议
websocket 帧大小/超时/压缩调优建议

参考文档：RabbitMQ Web MQTT

OpenClaw 官方文档

Plugins

Building plugins

SDK reference

许可证

MIT

消息格式指南

Web MQTT 使用共享的 OpenClaw 队列 wire 契约完成入站解析与回复序列化。标准 MessageEnvelope、非标准消息归一化、payload.outboundFormat 与多语言 SDK 适配说明见 OpenClaw 队列消息格式指南。