Skip to content
Back to search

openclaw-plugin-wecom

企业微信 AI 机器人插件 - Enterprise WeChat (WeCom) AI Bot plugin for OpenClaw. 支持流式输出、动态 Agent 管理、群聊集成、指令白名单等功能。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sunnoy--openclaw-plugin-wecom/badge.svg)](/listings/sunnoy--openclaw-plugin-wecom)

HTML

<a href="/listings/sunnoy--openclaw-plugin-wecom"><img src="/api/listings/sunnoy--openclaw-plugin-wecom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

openclaw plugins install @sunnoy/wecom

> **3.0 兼容性说明:** 从 `3.0.0` 开始,本插件仅支持 OpenClaw `2026.3.23-2+`。旧版 OpenClaw 请继续使用 `2.x`。

> **3.1 MCP 说明:** `wecom_mcp` 已按官方 `@wecom/wecom-openclaw-plugin@2026.4.23` 协商版本与 `@wecom/aibot-node-sdk@1.0.6` 对齐。企业规模和机器人权限仍由企业微信后端控制;当前大型企业常见只开放 `doc` 类 MCP 能力。

> **从官方插件迁移:** 如果之前使用 `openclaw plugins install @wecom/wecom-openclaw-plugin`,请先卸载官方插件再安装本插件。`channels.wecom` 配置字段兼容,无需修改。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 777 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenClaw 企业微信(WeCom)增强插件
  2. [![npm](https://img.shields.io/npm/v/@sunnoy/wecom)](https://www.npmjs.com/package/@sunnoy/wecom)
  3. [![license](https://img.shields.io/npm/l/@sunnoy/wecom)](LICENSE)
  4. `@sunnoy/wecom` 是 [OpenClaw](https://github.com/openclaw/openclaw) 企业微信渠道的**社区增强插件**,基于官方 [`@wecom/wecom-openclaw-plugin`](https://github.com/WecomTeam/wecom-openclaw-plugin) 的 WebSocket 长连接骨架,提供多账号管理、动态 Agent 隔离、Agent API / Webhook 增强出站、企业微信 MCP 文档/智能表格能力、指令白名单、配额感知等企业级特性。
  5. 底层 SDK:[`@wecom/aibot-node-sdk`](https://github.com/WecomTeam/aibot-node-sdk) — 企业微信智能机器人 Node.js SDK。
  6. > **⚠️ 从 HTTP 回调迁移到长连接:** 2.0 版本完全采用企业微信 [AI 机器人 WebSocket 长连接模式](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)。如果你之前使用 HTTP 回调(Token + EncodingAESKey + 回调 URL),需要在企业微信管理后台将机器人切换到长连接模式,然后删除旧的回调配置。切换后只需 `botId` 和 `secret` 即可接入。
  7. > **2.1 新增:** 在 WS 长连接之外,2.1 版本新增了企业微信**自建应用"接收消息"HTTP 回调**作为可选入站通道。在 `channels.wecom.agent` 下配置 `callback.token`、`callback.encodingAESKey`、`callback.path` 即可同时启用,与 WS 通道并行运行,互不影响。
  8. ## 相比官方插件的增强特性
  9. 下表列出了本插件相比 [官方 WeCom OpenClaw 插件](https://github.com/WecomTeam/wecom-openclaw-plugin)([npm](https://www.npmjs.com/package/@wecom/wecom-openclaw-plugin))额外提供的能力:
  10. | 特性 | 官方插件 | 本插件 |
  11. | --- | :---: | :---: |
  12. | WebSocket 长连接 + 流式回复 | ✅ | ✅ |
  13. | 私聊 / 群聊接收 | ✅ | ✅ |
  14. | DM 准入策略(pairing / open / allowlist / disabled) | ✅ | ✅ |
  15. | 群聊准入策略(open / allowlist / disabled) | ✅ | ✅ |
  16. | 按群配置发送者白名单 | ✅ | ✅ |
  17. | 思考占位(`<think>` 占位符) | ✅ | ✅ |
  18. | CLI 交互式配置向导 | ✅ | ✅ |
  19. | **多账号管理**(多 Bot 独立配置、共享字段继承) | ❌ | ✅ |
  20. | **动态 Agent 路由**(按用户 / 群自动隔离会话与工作区) | ❌ | ✅ |
  21. | **Workspace 模板**(自动为新 Agent 复制 AGENTS.md 等引导文件) | ❌ | ✅ |
  22. | **Agent API 增强出站**(自建应用主动发送文本、图片、文件) | ❌ | ✅ |
  23. | **部门 / 标签目标发送**(`party:` / `tag:` 寻址) | ❌ | ✅ |
  24. | **Webhook Bot 群通知**(命名 webhook 映射,markdown / 图片 / 文件) | ❌ | ✅ |
  25. | **指令白名单**(限制普通用户可执行的 slash 命令) | ❌ | ✅ |
  26. | **管理员绕过**(命令白名单 + 动态 Agent 路由) | ❌ | ✅ |
  27. | **运行时配额感知**(被动回复 24h 窗口 + 主动发送额度追踪与告警) | ❌ | ✅ |
  28. | **Pending Reply 重试**(WS 断连后自动通过 Agent API 补发未送达回复) | ❌ | ✅ |
  29. | **Reasoning 流式节流**(800ms 节流防止 SDK 队列溢出) | ❌ | ✅ |
  30. | **`<think>` 标签规范化**(兼容 `<thinking>` / `<thought>` 等变体) | ❌ | ✅ |
  31. | **Reply 媒体指令解析**(自动提取 LLM 输出中的 `MEDIA:` / `FILE:` 路径) | ❌ | ✅ |
  32. | **出站代理**(`network.egressProxyUrl`) | ❌ | ✅ |
  33. | **自定义 API 基础地址**(`network.apiBaseUrl` / `WECOM_API_BASE_URL`) | ❌ | ✅ |
  34. | **Bindings 路由**(固定绑定企业微信账号到指定 Agent) | ❌ | ✅ |
  35. | **消息去重**(reqId + msgId 去重,防止重复处理) | ❌ | ✅ |
  36. | **入站图文混排**(`mixed` 消息拆解为文本 + 图片) | ❌ | ✅ |
  37. | **入站语音转写**(`voice.content` 自动提取) | ❌ | ✅ |
  38. | **入站引用消息**(`quote` 上下文透传) | ❌ | ✅ |
  39. | **自建应用回调入站**(HTTP 回调作为独立入站通道,与 WS 并行) | ❌ | ✅ |
  40. | **Agent API Markdown 回复**(回调入站回复默认 markdown 格式) | ❌ | ✅ |
  41. | **入站/出站信息日志**(WS / CB 收发日志,便于追踪消息流) | ❌ | ✅ |
  42. | **官方 MCP 2026.4.23 对齐**(doc auth、SmartPage、媒体拦截器) | ✅ | ✅ |
  43. | **MCP 多账号 fallback**(默认账号非长连接时自动选择可用 Bot) | ❌ | ✅ |
  44. | **MCP doc-only Skills 部署约束**(避免误用 contact/todo/msg 等未开通能力) | ❌ | ✅ |
  45. ## 目录
  46. - [相比官方插件的增强特性](#相比官方插件的增强特性)
  47. - [前置要求](#前置要求)
  48. - [安装](#安装)
  49. - [从 HTTP 回调迁移](#从-http-回调迁移)
  50. - [运行测试](#运行测试)
  51. - [配置](#配置)
  52. - [私聊与群聊准入策略](#私聊与群聊准入策略)
  53. - [企业微信侧配置](#企业微信侧配置)
  54. - [消息能力与投递策略](#消息能力与投递策略)
  55. - [企业微信 MCP 文档与智能表格](#企业微信-mcp-文档与智能表格)
  56. - [动态 Agent 与路由](#动态-agent-与路由)
  57. - [自建应用回调入站](#自建应用回调入站)
  58. - [常见问题](#常见问题)
  59. - [项目结构](#项目结构)
  60. - [自定义 Skills 配合沙箱使用实践](#自定义-skills-配合沙箱使用实践)
  61. - [相关链接](#相关链接)
  62. - [贡献与协议](#贡献与协议)
  63. ## 前置要求
  64. - 已安装 [OpenClaw](https://github.com/openclaw/openclaw) `2026.3.23-2+`
  65. - 企业微信管理后台权限,可创建 AI 机器人或自建应用
  66. - **机器人已切换到长连接模式**(参考[官方文档](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657))
  67. - 运行 OpenClaw 的机器可以出站访问:
  68. - `wss://openws.work.weixin.qq.com`
  69. - `https://qyapi.weixin.qq.com`(启用 Agent / Webhook 时)
  70. Bot 主链路不需要企业微信反向访问你的 HTTP 回调地址。
  71. ## 安装
  72. ```bash
  73. openclaw plugins install @sunnoy/wecom
  74. ```
  75. > **3.0 兼容性说明:** 从 `3.0.0` 开始,本插件仅支持 OpenClaw `2026.3.23-2+`。旧版 OpenClaw 请继续使用 `2.x`。
  76. > **3.1 MCP 说明:** `wecom_mcp` 已按官方 `@wecom/wecom-openclaw-plugin@2026.4.23` 协商版本与 `@wecom/aibot-node-sdk@1.0.6` 对齐。企业规模和机器人权限仍由企业微信后端控制;当前大型企业常见只开放 `doc` 类 MCP 能力。
  77. > **从官方插件迁移:** 如果之前使用 `openclaw plugins install @wecom/wecom-openclaw-plugin`,请先卸载官方插件再安装本插件。`channels.wecom` 配置字段兼容,无需修改。
  78. ## 从 HTTP 回调迁移
  79. 如果之前使用 HTTP 回调模式(Token + EncodingAESKey + 回调 URL),迁移步骤如下:
  80. 1. **企业微信后台**:进入「应用管理」→「智能机器人」,将机器人切换到长连接模式(参考[官方文档](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657))
  81. 2. **记录凭证**:切换后获取新的 `BotId` 和 `Secret`
  82. 3. **更新配置**:在 `~/.openclaw/openclaw.json` 中:
  83. - 设置 `channels.wecom.botId` 和 `channels.wecom.secret`
  84. - 删除旧的 `token`、`encodingAesKey`、回调 URL 相关配置
  85. 4. **安装插件**:`openclaw plugins install @sunnoy/wecom`
  86. 5. **重启 Gateway**:`openclaw gateway restart`
  87. 迁移后不再需要公网可达的 HTTP 回调地址,插件会主动连接企业微信 WebSocket。
  88. ## 运行测试
  89. ```bash
  90. npm test
  91. ```
  92. ## 配置
  93. ### 单账号示例
  94. 在 `~/.openclaw/openclaw.json` 中添加:
  95. ```json
  96. {
  97. "plugins": {
  98. "entries": {
  99. "wecom": {
  100. "enabled": true
  101. }
  102. }
  103. },
  104. "channels": {
  105. "wecom": {
  106. "enabled": true,
  107. "botId": "aibxxxxxxxxxxxxxxxx",
  108. "secret": "xxxxxxxxxxxxxxxx",
  109. "welcomeMessage": "你好,我是 AI 助手。",
  110. "sendThinkingMessage": true,
  111. "dmPolicy": "pairing",
  112. "allowFrom": [],
  113. "groupPolicy": "open",
  114. "groupAllowFrom": [],
  115. "adminUsers": ["admin-userid"],
  116. "commands": {
  117. "enabled": true,
  118. "allowlist": ["/new", "/compact", "/help", "/status"]
  119. },
  120. "dynamicAgents": {
  121. "enabled": true,
  122. "adminBypass": false,
  123. "persistToConfig": false
  124. },
  125. "dm": {
  126. "createAgentOnFirstMessage": true
  127. },
  128. "groupChat": {
  129. "enabled": true,
  130. "requireMention": true,
  131. "mentionPatterns": ["@"]
  132. },
  133. "workspaceTemplate": "/path/to/template-dir",
  134. "workspaceTemplateExtraFiles": ["scripts/", "requirements.txt"],
  135. "mediaLocalRoots": ["/tmp/openclaw"],
  136. "agent": {
  137. "corpId": "wwxxxxxxxxxxxxxxxx",
  138. "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  139. "agentId": 1000002
  140. },
  141. "webhooks": {
  142. "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
  143. "dev": "yyy"
  144. },
  145. "network": {
  146. "egressProxyUrl": "http://proxy.internal:8080",
  147. "apiBaseUrl": "https://qyapi.weixin.qq.com"
  148. }
  149. }
  150. }
  151. }
  152. ```
  153. `webhooks` 的 value 既可以是完整 URL,也可以只写群机器人的 `key`。
  154. ### 核心配置
  155. | 配置项 | 类型 | 必填 | 说明 |
  156. | --- | --- | --- | --- |
  157. | `plugins.entries.wecom.enabled` | boolean | 是 | 启用插件 |
  158. | `channels.wecom.enabled` | boolean | 否 | 渠道开关 |
  159. | `channels.wecom.botId` | string | 是 | 企业微信 AI 机器人 Bot ID |
  160. | `channels.wecom.secret` | string | 是 | 企业微信 AI 机器人 Secret |
  161. | `channels.wecom.websocketUrl` | string | 否 | WS 地址,默认 `wss://openws.work.weixin.qq.com` |
  162. | `channels.wecom.sendThinkingMessage` | boolean | 否 | 是否先发送 `<think></think>` 占位,默认 `true`。该配置只控制企微思考气泡/占位消息;真实推理内容还要求当前 OpenClaw session 的 `reasoningLevel` 为 `stream` |
  163. | `channels.wecom.welcomeMessage` | string | 否 | 进入会话欢迎语(非空时固定使用该字符串) |
  164. | `channels.wecom.welcomeMessagesFile` | string | 否 | 欢迎语列表文件路径。支持:`{ "messages": [ ... ] }` 或顶层数组;每条欢迎语可为**一行一个字符串的数组**(推荐,易读),或单条字符串(可含 `\\n`)。相对路径基于 OpenClaw 状态目录(`~/.openclaw` 或 `OPENCLAW_STATE_DIR`)。未设置 `welcomeMessage` 时从该文件随机选取;**修改文件后无需重启服务**(按 mtime 自动重读) |
  165. | `channels.wecom.adminUsers` | string[] | 否 | 管理员用户 ID,可绕过命令白名单 |
  166. | `channels.wecom.defaultAccount` | string | 否 | 多账号模式默认账号 |
  167. ### 准入与安全配置
  168. | 配置项 | 类型 | 必填 | 说明 |
  169. | --- | --- | --- | --- |
  170. | `channels.wecom.dmPolicy` | string | 否 | `pairing`、`allowlist`、`open`、`disabled`,默认 `pairing` |
  171. | `channels.wecom.allowFrom` | string[] | 否 | 私聊 allowlist |
  172. | `channels.wecom.groupPolicy` | string | 否 | `open`、`allowlist`、`disabled`,默认 `open` |
  173. | `channels.wecom.groupAllowFrom` | string[] | 否 | 允许触发的群聊 ID 列表 |
  174. | `channels.wecom.groups` | object | 否 | 按群覆盖配置,可为某个群单独设置 `allowFrom` |
  175. | `channels.wecom.commands.enabled` | boolean | 否 | 是否启用命令白名单,默认 `true` |
  176. | `channels.wecom.commands.allowlist` | string[] | 否 | 普通用户允许执行的命令 |
  177. ### 路由与工作区配置
  178. | 配置项 | 类型 | 必填 | 说明 |
  179. | --- | --- | --- | --- |
  180. | `channels.wecom.dynamicAgents.enabled` | boolean | 否 | 是否启用动态 Agent,默认 `true` |
  181. | `channels.wecom.dynamicAgents.adminBypass` | boolean | 否 | 管理员是否绕过动态 Agent,默认 `false` |
  182. | `channels.wecom.dynamicAgents.persistToConfig` | boolean | 否 | 首次创建动态 Agent 时是否写入 `openclaw.json`,默认 `false`。开启后新会话可能触发 gateway 配置重载 |
  183. | `channels.wecom.dm.createAgentOnFirstMessage` | boolean | 否 | 私聊是否按用户建独立 Agent,默认 `true` |
  184. | `channels.wecom.groupChat.enabled` | boolean | 否 | 是否启用群聊处理,默认 `true` |
  185. | `channels.wecom.groupChat.requireMention` | boolean | 否 | 群聊是否要求 @ 才响应,默认 `true` |
  186. | `channels.wecom.groupChat.mentionPatterns` | string[] | 否 | 群聊触发前缀,默认 `["@"]` |
  187. | `channels.wecom.workspaceTemplate` | string | 否 | 动态 Agent 工作区模板目录 |
  188. | `channels.wecom.workspaceTemplateExtraFiles` | string[] | 否 | 在默认模板文件之外额外复制的相对路径文件/目录,例如 `["scripts/", "requirements.txt"]`。会跳过绝对路径、`../`、`.git`、`node_modules`、`.env*` |
  189. | `channels.wecom.mediaLocalRoots` | string[] | 否 | 额外允许被动回复读取的宿主机目录列表。用于放行 `MEDIA:/abs/path` 或 `FILE:/abs/path` 指向的本地文件;默认只允许当前 Agent workspace 和浏览器产物目录。注意:浏览器工具返回的宿主机路径在 block reply 阶段仍可能被 core sandbox 校验拦下,建议先用 `stage_browser_media` 复制到 `/workspace/...` 后再回复。多账号模式下也可配置在 `channels.wecom.<accountId>.mediaLocalRoots`。修改后需重启 Gateway 生效 |
  190. ### 增强出站配置
  191. | 配置项 | 类型 | 必填 | 说明 |
  192. | --- | --- | --- | --- |
  193. | `channels.wecom.agent.corpId` | string | 否 | 自建应用 CorpID |
  194. | `channels.wecom.agent.corpSecret` | string | 否 | 自建应用 Secret |
  195. | `channels.wecom.agent.agentId` | number | 否 | 自建应用 AgentId |
  196. | `channels.wecom.agent.replyFormat` | string | 否 | 回调入站回复格式,`"markdown"`(默认)或 `"text"` |
  197. | `channels.wecom.agent.callback.token` | string | 否 | 回调验签 Token |
  198. | `channels.wecom.agent.callback.encodingAESKey` | string | 否 | 回调消息解密密钥(43 位) |
  199. | `channels.wecom.agent.callback.path` | string | 否 | 回调 HTTP 路由路径,如 `"/webhooks/app"` |
  200. | `channels.wecom.webhooks` | object | 否 | 群机器人 webhook 映射 |
  201. | `channels.wecom.network.egressProxyUrl` | string | 否 | Agent / Webhook 出站代理 |
  202. | `channels.wecom.network.apiBaseUrl` | string | 否 | 企业微信 API 基础地址覆盖,默认官方地址 |
  203. Agent 增强出站不需要 `token`、`encodingAesKey`、回调 URL;只有需要同时启用**回调入站**时才需配置 `agent.callback.*`。
  204. ### 多账号示例
  205. ```json
  206. {
  207. "channels": {
  208. "wecom": {
  209. "defaultAccount": "open",
  210. "adminUsers": ["admin-userid"],
  211. "commands": {
  212. "enabled": true,
  213. "allowlist": ["/new", "/compact", "/help", "/status"]
  214. },
  215. "open": {
  216. "botId": "aib-open-xxx",
  217. "secret": "secret-open-xxx",
  218. "dmPolicy": "open"
  219. },
  220. "support": {
  221. "botId": "aib-support-xxx",
  222. "secret": "secret-support-xxx",
  223. "dmPolicy": "pairing",
  224. "mediaLocalRoots": ["/tmp/openclaw"],
  225. "agent": {
  226. "corpId": "wwxxxxxxxxxxxxxxxx",
  227. "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  228. "agentId": 1000002
  229. },
  230. "webhooks": {
  231. "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
  232. }
  233. }
  234. }
  235. }
  236. }
  237. ```
  238. 多账号模式下:
  239. - 顶层共享字段会合并到各账号
  240. - `channels.wecom.<accountId>` 是每个账号自己的覆盖项
  241. - 动态 Agent ID 会自动带账号前缀
  242. - 旧的 v1 `token` / `encodingAesKey` 字段不再使用
  243. ## 私聊与群聊准入策略
  244. ### 私聊 `dmPolicy`
  245. | 值 | 含义 |
  246. | --- | --- |
  247. | `pairing` | 默认模式。陌生用户首次私聊会收到配对码,管理员执行 `openclaw pairing approve wecom <code>` 后放行 |
  248. | `allowlist` | 只允许 `allowFrom` 中的用户私聊,不自动发配对码 |
  249. | `open` | 允许所有能私聊机器人的企业微信成员直接进入会话 |
  250. | `disabled` | 禁用私聊 |
  251. `open` 的含义就是:如果机器人可见范围允许,企业内任何能私聊到这个 Bot 的成员都可以直接使用。
  252. ### 群聊策略
  253. | 配置 | 说明 |
  254. | --- | --- |
  255. | `groupPolicy: "open"` | 所有群可触发 |
  256. | `groupPolicy: "allowlist"` + `groupAllowFrom` | 只允许指定群 |
  257. | `groupPolicy: "disabled"` | 禁用群聊 |
  258. | `groupChat.requireMention` | 群聊是否必须 @ 才触发 |
  259. | `groups.<chatId>.allowFrom` | 某个群里仅允许指定成员触发 |
  260. ## 企业微信侧配置
  261. ### 1. 创建 AI 机器人(Bot 主链路)
  262. 这是 v2 的主接入方式,使用 WebSocket 长连接。
  263. 1. 登录[企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
  264. 2. 进入「应用管理」→「智能机器人」
  265. 3. 创建机器人,选择长连接模式(参考[官方文档](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657))
  266. 4. 创建完成后记录 `BotId` 和 `Secret`
  267. 5. 填入 OpenClaw 配置的 `channels.wecom.botId` 和 `channels.wecom.secret`
  268. 6. 启动 OpenClaw,插件会主动连接官方 WebSocket
  269. 长连接模式下不需要配置 HTTP 回调 URL、Token、EncodingAESKey。
  270. ### 2. 创建自建应用(Agent 增强出站 + 可选回调入站)
  271. 自建应用承担两个可选职责:
  272. **增强出站**(主动推送消息):
  273. - 主动给用户 / 群 / 部门 / 标签发消息
  274. - 上传图片和文件
  275. - 当 WS 断连时作为回复后备通道
  276. **回调入站**(可选,与 WS 并行):
  277. - 企业微信将用户消息以 HTTP POST 推送到你的服务器
  278. - 适合需要独立入站 URL 或不方便使用 WS 长连接的场景
  279. 创建步骤:
  280. 1. 在企业微信后台创建自建应用
  281. 2. 记录 `CorpID`、`AgentId`、`Secret`
  282. 3. 填入配置:
  283. - `channels.wecom.agent.corpId`
  284. - `channels.wecom.agent.agentId`
  285. - `channels.wecom.agent.corpSecret`
  286. 4. **仅启用回调入站时**,额外在应用的「接收消息」中配置回调 URL,并填入对应的 `agent.callback.*` 配置(见[自建应用回调入站](#自建应用回调入站))
  287. ### 3. 配置群机器人(Webhook 增强出站,可选)
  288. Webhook 只负责群通知。
  289. 1. 在目标群添加群机器人
  290. 2. 复制 webhook URL 或 key
  291. 3. 配置到 `channels.wecom.webhooks`
  292. 4. 发送目标使用 `webhook:<name>`
  293. ## 消息能力与投递策略
  294. ### 能力矩阵
  295. | 能力 | Bot(WS) | Agent API | Webhook |
  296. | --- | :---: | :---: | :---: |
  297. | 私聊接收 | ✅ | ✅(回调入站) | — |
  298. | 群聊接收(可配置 @ 触发) | ✅ | ✅(回调入站) | — |
  299. | 被动流式回复 | ✅ | — | — |
  300. | 被动最终帧图片 | ✅ | ✅ | ✅ |
  301. | 主动发送文本 | ✅ | ✅ | ✅ |
  302. | 主动发送图片 / 文件 | — | ✅ | ✅ |
  303. | 发送到部门 / 标签 | — | ✅ | — |
  304. | 思考过程 `<think>` | ✅ | — | — |
  305. | 欢迎语 | ✅ | — | — |
  306. | WS 断连补发 | — | ✅ | — |
  307. ### 入站消息
  308. | 类型 | 说明 |
  309. | --- | --- |
  310. | `text` | 文本消息 |
  311. | `image` | 图片(AES 加密下载 + 解密) |
  312. | `voice` | 语音(自动提取转写文本 `voice.content`) |
  313. | `file` | 文件(AES 加密下载 + 解密) |
  314. | `mixed` | 图文混排(自动拆解为文本 + 图片) |
  315. | `quote` | 引用消息(上下文透传) |
  316. ### 被动回复
  317. 被动回复统一走 WebSocket `replyStream`:
  318. - 文本内容支持 Markdown
  319. - `<thinking>`、`<thought>` 等变体会被规范化为 `<think>`
  320. - 可先发送 `<think></think>` 占位(配置 `sendThinkingMessage`)
  321. - 如果只看到“等待模型响应”而没有真实思考内容,请检查对应 session 的 `reasoningLevel` 是否为 `stream`;插件会为缺失值初始化为 `stream`,但不会覆盖用户已显式设置的 `off`
  322. - 思考流式更新采用 800ms 节流,防止 SDK 队列溢出
  323. - 最终回复 `finish=true` 时可附带图片 `msg_item`
  324. - 若最终回复包含 WS 不支持的媒体(文件等),会先文本提示再通过 Agent API 补发
  325. 本插件会自动解析模型输出中的 `MEDIA:` / `FILE:` 指令,并在回复完成后上传对应文件:
  326. - 图片使用 `MEDIA:/abs/path`
  327. - PDF、音频、视频、压缩包、Office 文档等非图片文件使用 `FILE:/abs/path`
  328. - 沙箱内当前工作区文件可直接写成 `MEDIA:/workspace/...` 或 `FILE:/workspace/...`
  329. - 浏览器生成的文件默认允许从 OpenClaw 状态目录下的浏览器媒体目录读取,但如果浏览器工具返回的是宿主机绝对路径,先调用 `stage_browser_media`,再使用它返回的 `MEDIA:/workspace/...` 或 `FILE:/workspace/...`
  330. - 宿主机其他目录默认不放行;如果需要回复 `/tmp/openclaw/report.pdf` 这类文件,请把其父目录加入 `channels.wecom.mediaLocalRoots`,多账号模式可配在 `channels.wecom.<accountId>.mediaLocalRoots`
  331. - 更新 `mediaLocalRoots` 后需重启 Gateway 生效
  332. ### 主动发送与后备策略
  333. 主动发送分层:
  334. 1. 普通文本优先走 WS `sendMessage`
  335. 2. 目标为 `webhook:<name>` 时走 Webhook
  336. 3. 目标为用户 / 群 / 部门 / 标签,且配置了 Agent 时走 Agent API
  337. 4. 发送图片 / 文件时,WS 侧给出文本提示,媒体交给 Agent / Webhook 通道
  338. 5. 未配置 Agent / Webhook 时,只保留 WS 文本提示
  339. ### WS 断连自动重试
  340. 当 WS 断连导致最终回复发送失败时:
  341. 1. 插件自动将未送达回复加入 pending 队列(TTL 5 分钟,最多 50 条)
  342. 2. WS 重连并认证成功后,自动通过 Agent API 补发所有 pending 回复
  343. 3. 过期条目自动丢弃,不会无限积压
  344. ### 运行时配额感知
  345. 插件做本地近似记账,并把状态暴露到账号 snapshot / status:
  346. - 连接占线:同一个 `botId` 被其他实例接管时,标记 `displaced`
  347. - 24h 被动回复窗口:按会话追踪 reply quota(限额 30,告警 24)
  348. - 每会话每日主动发送额度:按会话追踪 active send quota(限额 10,告警 8)
  349. - 接近上限或触顶时输出 warning
  350. 当前策略是"感知 + 告警",不做硬阻断。
  351. ### 支持的目标格式
  352. | 格式 | 示例 | 说明 |
  353. | --- | --- | --- |
  354. | `wecom:<userId>` | `wecom:zhangsan` | 发给企业微信用户 |
  355. | `group:<chatId>` | `group:wr123456` | 发给群聊 |
  356. | `party:<id>` | `party:2` | 发给部门 |
  357. | `tag:<name>` | `tag:Developers` | 发给标签 |
  358. | `webhook:<name>` | `webhook:ops` | 发给 webhook 群 |
  359. | `<chatId>` | `wr123456` | 直接写群 ID 也可识别 |
  360. ## 企业微信 MCP 文档与智能表格
  361. `wecom_mcp` 通过企业微信官方 MCP Server 调用文档和智能表格能力。本插件默认使用官方协商版本 `2026.4.23`,并保留社区增强:
  362. - 自动透传当前企业微信发送人的 `userid`,用于 MCP 后端做用户级鉴权
  363. - 保留原始大小写 `chatId/chatType`,文档权限错误时可发送企业微信授权卡片
  364. - `smartpage_create` 支持 `page_filepath`,调用前读取本地 Markdown 文件并填入 `page_content`
  365. - `smartpage_get_export_result` 会把大段 Markdown `content` 保存为本地文件,返回 `content_path`
  366. - `get_msg_media` 会把 base64 媒体保存为本地文件,避免把大文件塞进模型上下文
  367. - 默认账号不是长连接机器人时,自动回退到第一个配置了 `botId/secret` 的账号获取 MCP 配置
  368. 推荐只部署当前机器人实际开通的 doc 类 skills:
  369. - `wecom-preflight`
  370. - `wecom-doc-manager`
  371. - `wecom-smartsheet-schema`
  372. - `wecom-smartsheet-data`
  373. 如果企业微信返回 `errcode: 846609` / `unsupported mcp biz type`,表示当前机器人未开通对应 MCP category。不要改用其他 category 或反复探路。
  374. 如果返回 `forbidden for current apikey`,表示企业微信 MCP 后端拒绝当前机器人/apikey 访问目标文档或智能表格。插件无法绕过该限制,需要在企业微信侧给机器人或当前用户开通访问权限,或改用机器人可访问的文档/智能表格链接。
  375. 从源码仓库同步到自管 OpenClaw 主机时,可参考运维脚本:
  376. ```bash
  377. scripts/install-plugin.sh
  378. ```
  379. 该脚本会把插件代码同步到远端插件目录、在远端执行 `npm ci --omit=dev`、只同步 doc 相关 WeCom skills、清空插件本地 `skills/`,并保持远端文件 ownership 为 `root:root`。脚本默认参数面向本仓库的自管部署环境,其他环境请按实际主机和目录传入参数。
  380. ## 动态 Agent 与路由
  381. ### 动态 Agent
  382. 默认路由规则:
  383. - 私聊:`wecom-dm-<userId>`
  384. - 群聊:`wecom-group-<chatId>`
  385. - 多账号私聊:`wecom-<accountId>-dm-<userId>`
  386. - 多账号群聊:`wecom-<accountId>-group-<chatId>`
  387. 好处:
  388. - 每个用户 / 群聊独立上下文
  389. - 每个动态 Agent 独立工作区
  390. - 可以按账号进一步隔离
  391. ### Workspace 模板
  392. `workspaceTemplate` 目录中的模板文件会在动态 Agent 首次创建时复制到工作区:
  393. - `AGENTS.md`、`BOOTSTRAP.md`、`CLAUDE.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`system-prompt.md`
  394. 如果需要额外复制脚本或数据文件,可以配置 `workspaceTemplateExtraFiles`,值必须是 `workspaceTemplate` 下的相对路径:
  395. ```json
  396. {
  397. "channels": {
  398. "wecom": {
  399. "workspaceTemplate": "/path/to/template-dir",
  400. "workspaceTemplateExtraFiles": ["scripts/", "requirements.txt", "tools/helper.py"]
  401. }
  402. }
  403. }
  404. ```
  405. 插件会递归复制目录,并跳过绝对路径、`../` 路径穿越、`.git`、`node_modules`、`.env*` 等敏感项。
  406. 插件会在工作区里写入 `.openclaw/wecom-template-state.json` 记录首次模板同步状态。已有 state 的工作区后续只补缺,不覆盖已有文件。
  407. `BOOTSTRAP.md` 只会在工作区还没有 `memory/` 或 `MEMORY.md` 时参与同步;一旦工作区已经出现记忆痕迹,插件就不再回种 bootstrap,避免打断已完成 onboarding 的会话。
  408. 历史工作区如果还没有 state,插件会先补写 state,再按“只补缺、不覆盖”处理,避免存量工作区被重新整批同步。
  409. ### Bindings
  410. 如果 OpenClaw 配置了 `bindings`,则优先按 binding 路由,不会被动态 Agent 覆盖。
  411. ## 自建应用回调入站
  412. 自建应用的「接收消息」HTTP 回调可作为额外的入站通道,与 WS 长连接并行运行,互不干扰。适合已有自建应用的场景,或需要独立回调 URL 的情况。
  413. ### 配置
  414. 在 `channels.wecom.agent` 下增加 `callback` 子对象:
  415. ```json
  416. {
  417. "channels": {
  418. "wecom": {
  419. "botId": "aib-xxx",
  420. "secret": "bot-secret-xxx",
  421. "agent": {
  422. "corpId": "wwxxxxxxxxxxxx",
  423. "corpSecret": "app-secret-xxx",
  424. "agentId": 1000002,
  425. "replyFormat": "markdown",
  426. "callback": {
  427. "token": "YourToken",
  428. "encodingAESKey": "43位密钥",
  429. "path": "/webhooks/app"
  430. }
  431. }
  432. }
  433. }
  434. }
  435. ```
  436. | 字段 | 说明 |
  437. | --- | --- |
  438. | `agent.callback.token` | 企业微信「接收消息」里配置的 Token |
  439. | `agent.callback.encodingAESKey` | 43 位 EncodingAESKey |
  440. | `agent.callback.path` | Gateway 监听的 HTTP 路径,需与企业微信后台填写的 URL 一致 |
  441. | `agent.replyFormat` | 回复格式,`"markdown"`(默认)或 `"text"` |
  442. ### 企业微信侧配置
  443. 1. 进入自建应用 → 「接收消息」
  444. 2. 填写 URL:`https://<your-gateway-host>:<port><path>`(例如 `https://example.com:18789/webhooks/app`)
  445. 3. 填写 Token 和 EncodingAESKey(与配置保持一致)
  446. 4. 点击「保存」,企业微信将发送 GET 请求验证(gateway 会自动回复 echostr)
  447. 5. 验证通过后,用户发给自建应用的消息将通过 HTTP POST 推送到 gateway
  448. ### 支持的消息类型
  449. | 类型 | 说明 |
  450. | --- | --- |
  451. | `text` | 文本消息 |
  452. | `image` | 图片(通过 Agent API 下载) |
  453. | `voice` | 语音文件 |
  454. | `file` | 文件 |
  455. | `video` | 视频文件 |
  456. 事件类消息(关注、进入会话等)会被静默忽略。
  457. ## 常见问题
  458. ### Q: 2.0 和之前最大的区别是什么?
  459. 2.0 完全采用 WebSocket 长连接,不再使用 HTTP 回调。需要在企业微信后台将机器人切换到[长连接模式](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)。
  460. ### Q: 3.0 为什么不能再装在旧 OpenClaw 上?
  461. 3.0 开始直接适配 OpenClaw `2026.3.23-2+` 的新版 plugin SDK 导出和媒体/runtime 约定,旧版 core 缺少这些接口。旧环境请固定使用 `2.x`。
  462. ### Q: 之前用的官方插件 `@wecom/wecom-openclaw-plugin`,怎么迁移?
  463. ```bash
  464. # 卸载官方插件
  465. openclaw plugins uninstall wecom-openclaw-plugin
  466. # 安装本插件
  467. openclaw plugins install @sunnoy/wecom
  468. # 重启
  469. openclaw gateway restart
  470. ```
  471. `channels.wecom` 配置字段兼容,无需修改。
  472. ### Q: `dmPolicy: "open"` 是不是企业里任何人都能私聊?
  473. 是。前提是该成员对这个机器人可见,并且能在企业微信里私聊到它。
  474. ### Q: `pairing` 模式怎么放行用户?
  475. 用户第一次私聊会收到配对码。管理员执行:
  476. ```bash
  477. openclaw pairing approve wecom <code>
  478. ```
  479. ### Q: Agent 还需要配置 `token` / `encodingAesKey` 吗?
  480. 不需要。Agent 只做增强出站,保留 `corpId`、`corpSecret`、`agentId` 即可。
  481. ### Q: 入站图片还依赖全局 `EncodingAESKey` 吗?
  482. 不依赖。WS 消息体里的图片 / 文件自带独立 `aeskey`,插件按 `image.aeskey` 或 `file.aeskey` 下载与解密。
  483. ### Q: 收到 `disconnected_event` 是什么情况?
  484. 通常表示同一个 `botId` 被另一个实例接管了。企业微信同一时刻只允许一个活跃长连接。
  485. ### Q: 什么时候会走 Agent 或 Webhook?
  486. - `webhook:<name>` 目标固定走 Webhook
  487. - 发送部门 / 标签 / 媒体消息时优先走 Agent
  488. - WS 断连后的 pending 回复通过 Agent API 补发
  489. - WS 文本主动发送失败时,尝试回退到 Agent
  490. ### Q: 回复本地文件时提示“没有权限访问路径”怎么办?
  491. 先确认文件路径是否在允许目录里:
  492. - 当前 Agent 工作区文件默认允许,可直接用 `FILE:/workspace/...` 或 `MEDIA:/workspace/...`
  493. - 浏览器生成的文件默认允许,但浏览器工具返回的宿主机路径建议先用 `stage_browser_media` 转成 `/workspace/...`
  494. - 宿主机其他目录需要把父目录加入 `channels.wecom.mediaLocalRoots`
  495. - 多账号模式如果只想对某个账号生效,可配置 `channels.wecom.<accountId>.mediaLocalRoots`
  496. 例如:
  497. ```json
  498. {
  499. "channels": {
  500. "wecom": {
  501. "mediaLocalRoots": ["/tmp/openclaw"]
  502. }
  503. }
  504. }
  505. ```
  506. 修改后重启 Gateway。`v2.2.1+` 已支持把 `mediaLocalRoots` 并入被动回复文件允许目录。
  507. ### Q: `60020 not allow to access from your ip` 是什么问题?
  508. 企业微信自建应用 API 的可信 IP 限制。把当前服务器出口 IP 加入企业微信应用的可信 IP 白名单即可。
  509. ## 项目结构
  510. ```text
  511. openclaw-plugin-wecom/
  512. ├── index.js # 插件入口、生命周期、onboarding
  513. ├── dynamic-agent.js # 动态 Agent 路由判断
  514. ├── image-processor.js # 图片格式检测、MD5、Base64
  515. ├── logger.js # 结构化日志
  516. ├── think-parser.js # <think> 标签规范化
  517. ├── utils.js # 工具函数
  518. ├── openclaw.plugin.json # 插件元数据
  519. ├── wecom/
  520. │ ├── accounts.js # 多账号管理与配置继承
  521. │ ├── agent-api.js # Agent API(Token、发送、上传)
  522. │ ├── allow-from.js # allowlist 规范化与匹配
  523. │ ├── callback-crypto.js # 回调 AES 解密与签名验证
  524. │ ├── callback-inbound.js # 自建应用回调入站处理
  525. │ ├── callback-media.js # 回调媒体下载
  526. │ ├── channel-plugin.js # 核心通道(sendNotice / sendMedia)
  527. │ ├── commands.js # 指令白名单与命令拦截
  528. │ ├── constants.js # 常量定义
  529. │ ├── dm-policy.js # 私聊准入策略
  530. │ ├── group-policy.js # 群聊准入策略
  531. │ ├── http.js # HTTP 请求 + 代理
  532. │ ├── mcp-tool.js # 企业微信 MCP Streamable HTTP 调用与拦截器
  533. │ ├── onboarding.js # CLI 交互式配置向导
  534. │ ├── runtime-telemetry.js # 运行时配额追踪
  535. │ ├── sandbox.js # 沙箱集成
  536. │ ├── state.js # 插件状态管理
  537. │ ├── target.js # 目标解析(user / group / party / tag / webhook)
  538. │ ├── webhook-bot.js # Webhook Bot 发送
  539. │ ├── workspace-template.js # 工作区模板同步
  540. │ ├── ws-monitor.js # WS 消息处理、流式回复、节流、重试
  541. │ └── ws-state.js # WS 状态 + pending reply 队列
  542. └── tests/
  543. ├── accounts-reserved-keys.test.js
  544. ├── api-base-url.test.js
  545. ├── callback-crypto.test.js
  546. ├── callback-inbound.test.js
  547. ├── channel-plugin.media-type.test.js
  548. ├── channel-plugin.notice.test.js
  549. ├── dynamic-agent.test.js
  550. ├── image-processor.test.js
  551. ├── issue-fixes.test.js
  552. ├── mcp-tool.test.js
  553. ├── reply-media-directive.test.js
  554. ├── runtime-telemetry.test.js
  555. ├── target.test.js
  556. ├── think-parser.test.js
  557. ├── workspace-template.test.js
  558. ├── ws-monitor.quote-mixed.test.js
  559. └── ws.e2e.test.js
  560. ```
  561. ## 自定义 Skills 配合沙箱使用实践
  562. OpenClaw 支持自定义 Skills 并通过沙箱(Docker)隔离执行,下面保留一份生产环境常见配置示例:
  563. ```json
  564. {
  565. "agents": {
  566. "defaults": {
  567. "sandbox": {
  568. "mode": "all",
  569. "workspaceAccess": "rw",
  570. "scope": "agent",
  571. "docker": {
  572. "image": "your-registry.com/openclaw-agent:v2026.x.x",
  573. "readOnlyRoot": false,
  574. "network": "bridge",
  575. "extraHosts": [
  576. "your-domain.internal:xxx.xxx.xxx.xxx"
  577. ],
  578. "binds": [
  579. "/path/to/skills:/workspace/skills:ro"
  580. ],
  581. "dangerouslyAllowReservedContainerTargets": true,
  582. "dangerouslyAllowExternalBindSources": true
  583. },
  584. "prune": {
  585. "idleHours": 87600,
  586. "maxAgeDays": 3650
  587. }
  588. }
  589. }
  590. },
  591. "skills": {
  592. "allowBundled": ["_none_"],
  593. "load": {
  594. "extraDirs": ["/path/to/skills"],
  595. "watch": true,
  596. "watchDebounceMs": 250
  597. }
  598. }
  599. }
  600. ```
  601. 关键点:
  602. - `sandbox.mode: "all"` 表示所有操作都走沙箱
  603. - `sandbox.workspaceAccess: "rw"` 允许 Agent 读写工作区
  604. - `sandbox.scope: "agent"` 表示每个 Agent 独立沙箱
  605. - `sandbox.docker.binds` 可把宿主机技能目录映射到容器内 `/workspace/skills`
  606. - `skills.load.extraDirs` 用于声明自定义 Skills 加载目录
  607. - `skills.load.watch` 改动 Skill 后自动热加载
  608. ## 相关链接
  609. - [OpenClaw](https://github.com/openclaw/openclaw) — 开源 AI Agent 运行时
  610. - [官方 WeCom OpenClaw 插件](https://github.com/WecomTeam/wecom-openclaw-plugin)([npm](https://www.npmjs.com/package/@wecom/wecom-openclaw-plugin))
  611. - [`@wecom/aibot-node-sdk`](https://github.com/WecomTeam/aibot-node-sdk) — 企业微信智能机器人 Node.js SDK
  612. - [企业微信 AI 机器人官方文档](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)
  613. ## 贡献与协议
  614. - 贡献说明见 `CONTRIBUTING.md`
  615. - 许可证为 `ISC`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.