OpenClaw WeCom WebSocket 插件

企业微信智能机器人 Node.js SDK 的 OpenClaw 插件，基于 WebSocket 长连接通道。

环境要求

• OpenClaw 版本: >= 2026.2.26 (测试于 2026.3.9)
• Node.js 版本: >= 18.0.0
• npm 版本: >= 9.0.0
• @wecom/aibot-node-sdk 版本: 1.0.1

特性

• 🔗 WebSocket 长连接 - 基于企业微信官方 wss://openws.work.weixin.qq.com 地址
• 🔐 自动认证 - 连接建立后自动发送认证帧（botId + secret）
• 💓 心跳保活 - 自动维护心跳，断线自动重连
• 📡 无需公网域名 - 与传统 webhook 方式不同，不需要暴露公网端口

与 Webhook 版本的区别

| 特性 | Webhook 版本 (openclaw-wecom) | WebSocket 版本 (本插件) | |------|-------------------------------|----------------------| | 需要公网域名 | ✅ 需要 | ❌ 不需要 | | 部署方式 | 需要 Nginx/Caddy 反向代理 | 直接运行即可 | | 连接方式 | 被动接收回调 | 主动建立长连接 | | 适用场景 | 有公网服务器的部署 | 本地/内网/开发环境 |

安装

方式一：通过 OpenClaw CLI 安装（推荐）

openclaw plugin install openclaw-wecom-websocket

方式二：手动安装

1. 安装依赖：

npm install openclaw-wecom-websocket

2. 复制插件到 OpenClaw 扩展目录：

cp -r node_modules/openclaw-wecom-websocket ~/.openclaw/extensions/

配置

1. 获取企业微信机器人凭证

1. 登录 企业微信管理后台
2. 进入「应用管理」→「创建应用」
3. 创建应用后，在应用详情页面获取：
   • AgentId (应用 ID)
   • Secret (应用 Secret)
4. 重要：在应用配置中开启「API 模式」并选择「长连接」方式

2. 配置 OpenClaw

编辑 OpenClaw 配置文件 ~/.openclaw/openclaw.json，添加以下内容：

{
  "plugins": {
    "entries": {
      "openclaw-wecom-websocket": {
        "enabled": true
      }
    }
  },
  "channels": {
    "wecom-websocket": {
      "enabled": true,
      "botId": "your-bot-id",
      "secret": "your-bot-secret",
      "wsUrl": "wss://openws.work.weixin.qq.com",
      "autoReconnect": true,
      "maxReconnectAttempts": 10
    }
  }
}

配置说明

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | enabled | boolean | 否 | 是否启用，默认 true | | botId | string | ✅ | 企业微信机器人 ID | | secret | string | ✅ | 企业微信机器人 Secret | | wsUrl | string | 否 | WebSocket 服务器地址，默认 wss://openws.work.weixin.qq.com | | autoReconnect | boolean | 否 | 断线自动重连，默认 true | | maxReconnectAttempts | number | 否 | 最大重连次数，默认 10 |

3. 启动 OpenClaw

openclaw start

首次启动后，机器人会自动建立 WebSocket 连接。

使用

启动机器人

确保企业微信应用已创建并启用，机器人会自动：

1. 建立 WebSocket 长连接
2. 自动认证
3. 接收消息并回复

发送消息

使用 OpenClaw CLI 发送消息：

# 发送给用户
openclaw send --channel wecom-websocket --to <userid> --text "你好"

# 发送给群聊
openclaw send --channel wecom-websocket --to "chat:<chatid>" --text "大家好"

项目结构

openclaw-wecom-websocket/
├── src/
│   ├── index.ts           # 插件入口
│   ├── channel.ts         # 通道实现
│   ├── config-schema.ts  # 配置 Schema
│   ├── runtime.ts        # 运行时
│   └── ws-client.ts      # WebSocket 客户端封装
├── openclaw.plugin.json  # 插件配置
├── package.json
├── tsconfig.json
└── README.md

常见问题

Q: 连接失败，提示 "connect ECONNREFUSED"

A: 检查网络是否能访问 wss://openws.work.weixin.qq.com，以及 botId 和 secret 是否正确。

Q: 机器人收不到消息

A: 确保：

1. 应用已在企业微信后台启用
2. 应用可见范围包含需要接收消息的用户/部门
3. 已开启「API 模式」并选择「长连接」方式
4. 用户已添加机器人为好友

Q: 回复失败，提示 "invalid message type"

A: 这是企业微信长连接的限制，需要使用流式回复（stream）方式发送消息。插件已自动处理。

Q: 如何查看连接日志

A: 启动 OpenClaw 时加上调试模式：

openclaw start --debug

开发

本地开发

# 安装依赖
npm install

# 构建
npm run build

# 链接到全局
npm link

发布到 npm

# 登录 npm
npm login

# 发布
npm publish

相关链接

• OpenClaw 官方文档
• 企业微信开发者后台
• 企业微信长连接文档
• @wecom/aibot-node-sdk GitHub

许可证

MIT