Skip to content
Back to search

openclaw-wechat

🤖 OpenClaw 企业微信插件(支持直接加到微信)

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/xueheng-li--openclaw-wechat/badge.svg)](/listings/xueheng-li--openclaw-wechat)

HTML

<a href="/listings/xueheng-li--openclaw-wechat"><img src="/api/listings/xueheng-li--openclaw-wechat/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.

方式一:CLI 安装

openclaw plugin install --path /path/to/openclaw-wechat

方式二:手动安装

1. 克隆本仓库:

git clone https://github.com/Xueheng-Li/openclaw-wechat.git
cd openclaw-wechat
npm install

2. 在 OpenClaw 配置文件 `~/.openclaw/openclaw.json` 中注册插件:

{
  "plugins": {
    "load": {
      "paths": [
        "/path/to/openclaw-wechat"
      ]
    },
    "entries": {
      "wecom": {
        "enabled": true
      }
    }
  }
}

> 💡 **注意**:插件 ID 为 `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 · 708 lines

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

  1. # 🤖 OpenClaw 企业微信插件(支持直接加到微信)
  2. > ⭐ 如果觉得有用,请点击右上角的 **Star** 支持一下!
  3. ### 🔍 项目概述
  4. **openclaw-wechat** 是一个 [OpenClaw](https://openclaw.ai)(原 ClawdBot/Moltbot)的 <img src="docs/images/wecom-icon.png" width="16" height="16"> **企业微信渠道插件**,让你的 AI 智能体通过企业微信自建应用与用户对话。接入企业微信后,<img src="docs/images/wechat-icon.png" width="16" height="16"> **个人微信用户也可以直接对话**——只需在企业微信管理后台「我的企业 → 微信插件」中扫码关联即可。
  5. > 🍴 本项目 fork 自 [dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat)(v0.1.0,作者:勾勾的数字生命),并进行了大量功能扩展以兼容新版 OpenClaw。
  6. ### 🧠 v0.3.7 — OpenClaw 2026.3+ 兼容修复
  7. **修复了 OpenClaw 2026.3+ 中企业微信“能发不能收”的典型故障**,核心兼容点包括:
  8. - ✅ 补齐 `status` 运行态信息,避免 health-monitor 持续误判渠道已停止
  9. - ✅ `gateway.startAccount` 改为常驻直到 `abortSignal`,不再反复 auto-restart
  10. - ✅ `registerHttpRoute()` 显式增加 `auth: "plugin"` 和 `match: "exact"`
  11. - ✅ `/wecom/callback` 不再被 Control UI 的 SPA fallback 覆盖,健康检查稳定返回 `wecom webhook ok`
  12. - ✅ 实战验证:错误绑定 `AgentId` 也会导致“能发不能收”,现在 README 已加入对齐检查
  13. ### 🧠 v0.3.6 — 对话记忆系统(与官方 Telegram Channel 实现一致)
  14. **解决了企业微信渠道"失忆"问题**:之前每条消息都是独立对话,AI 无法记住上下文。
  15. 现在使用 OpenClaw SDK 的 `recordPendingHistoryEntry` + `buildPendingHistoryContextFromMap` 实现对话历史管理,**与官方 Telegram/Discord 渠道完全一致**:
  16. - 📝 自动记录用户消息和 AI 回复到内存历史
  17. - 🔄 每次对话自动携带最近 20 条历史上下文
  18. - 🗑️ `/clear` 命令同时清除 session 和内存历史
  19. - 📊 `/status` 显示当前历史消息数量
  20. ### ✨ 与上游的主要区别
  21. | 特性 | 上游 (OpenClaw-Wechat v0.1.0) | 本 Fork (v0.3.7) |
  22. |------|------|------|
  23. | 🎯 平台兼容 | ClawdBot | OpenClaw(同时保留 ClawdBot 兼容) |
  24. | 📄 插件描述文件 | `clawdbot.plugin.json` | `openclaw.plugin.json` + `clawdbot.plugin.json` |
  25. | ⚙️ 配置文件 | `~/.clawdbot/clawdbot.json` | `~/.openclaw/openclaw.json` |
  26. | 📨 消息类型 | 文本、图片、语音 | 文本、图片、语音、**视频**、**文件**、**链接** |
  27. | 📤 发送类型 | 仅文本 | 文本、**图片**、**视频**、**文件**(自动类型识别) |
  28. | 🎙️ 语音识别 | 仅企业微信自带 | 企业微信自带 + **远程 Qwen3-ASR** / 本地 FunASR(自动降级) |
  29. | 🧠 对话历史 | 无 | **SDK 级对话记忆(与官方 Telegram 一致)** |
  30. | 🖥️ Chat UI | 无 | **消息同步到 Transcript + 实时广播** |
  31. | 🌐 代理支持 | 无 | **WECOM_PROXY 环境变量** |
  32. | 📝 消息分段 | 按字符 | **按字节(UTF-8),二分查找分割** |
  33. ### 📋 功能特性
  34. #### 🔌 核心功能
  35. - [x] ✅ 支持个人微信对话(通过企业微信桥接)
  36. - [x] ✅ 接收/发送企业微信消息
  37. - [x] ✅ 自动调用 AI 代理处理消息
  38. - [x] ✅ 消息签名验证(SHA1)和 AES-256-CBC 加解密
  39. - [x] ✅ Webhook URL 验证
  40. - [x] ✅ OpenClaw 2026.3+ 渠道生命周期兼容
  41. - [x] ✅ access_token 自动缓存和刷新
  42. #### 🎬 媒体功能
  43. - [x] 🖼️ 图片消息收发 + AI Vision 识别
  44. - [x] 🎙️ 语音消息转文字(企业微信自带 + 远程 Qwen3-ASR + 本地 FunASR 降级)
  45. - [x] 📹 视频消息接收、下载、发送
  46. - [x] 📎 文件消息接收(支持 .txt/.md/.json/.pdf 等自动读取)
  47. - [x] 🔗 链接分享消息接收
  48. #### 🎨 用户体验
  49. - [x] 📝 命令系统(`/help`、`/status`、`/clear`)
  50. - [x] 🔄 Markdown → 纯文本自动转换(企业微信不支持 Markdown 渲染)
  51. - [x] ✂️ 长消息自动分段(2048 字节限制,按 UTF-8 字节精确分割)
  52. - [x] 🧠 对话历史记忆(SDK 级,与官方 Telegram 一致)
  53. - [x] 🛡️ API 限流保护(10 并发,100ms 间隔)
  54. - [x] ⏳ 处理中提示("收到您的消息,正在处理中...")
  55. #### 🚀 高级功能
  56. - [x] 👥 多账户支持(`WECOM_<ACCOUNT>_*` 格式)
  57. - [x] 🔒 Token 并发安全(Promise 锁)
  58. - [x] 🖥️ Chat UI 集成(Transcript 写入 + Gateway 实时广播)
  59. - [x] 🌐 HTTP 代理支持(`WECOM_PROXY`)
  60. - [x] 🩺 渠道状态探测(status/probe,兼容新版 OpenClaw health monitor)
  61. ### 🆕 OpenClaw 2026.3+ 兼容说明
  62. OpenClaw 2026.3+ 对渠道插件的要求比旧版本更严格。企业微信插件如果只保留旧版写法,常见症状是:
  63. - 能主动发送消息
  64. - `/wecom/callback` 返回的是 Control UI HTML,而不是 `wecom webhook ok`
  65. - `health-monitor` 日志里反复出现 `restarting (reason: stopped)`
  66. - 企业微信后台显示消息发送成功,但 OpenClaw 没有任何 `wecom inbound` 日志
  67. 本插件从 `v0.3.7` 起已补齐以下兼容点:
  68. - `status`:提供运行态摘要、账户快照、探测结果
  69. - `gateway.startAccount`:保持常驻直到 `abortSignal`
  70. - `api.registerHttpRoute()`:显式使用 `auth: "plugin"` 和 `match: "exact"`
  71. 如果你升级到 OpenClaw `2026.3.x` 或更高版本,建议至少验证这三项:
  72. ```bash
  73. openclaw channels status --probe
  74. curl https://你的域名/wecom/callback
  75. openclaw logs -f | grep wecom
  76. ```
  77. 期望结果:
  78. - 渠道状态显示 `running`
  79. - callback 返回 `wecom webhook ok`
  80. - 收到消息时能看到 `wecom inbound:`、`session registered`、`sent AI reply`
  81. ### 📊 支持的消息类型
  82. | 类型 | 接收 | 发送 | 说明 |
  83. |:----:|:----:|:----:|------|
  84. | 📝 文本 | ✅ | ✅ | 完全支持,超长消息自动按字节分段 |
  85. | 🖼️ 图片 | ✅ | ✅ | 支持 AI Vision 识别,下载后保存到临时文件 |
  86. | 🎙️ 语音 | ✅ | ❌ | 企业微信自带识别 + 远程 Qwen3-ASR / 本地 FunASR 降级(AMR→WAV→文本) |
  87. | 📹 视频 | ✅ | ✅ | 自动下载保存,支持发送视频消息 |
  88. | 📎 文件 | ✅ | ✅ | 自动下载,可读类型自动交给 AI 分析 |
  89. ### 📦 前置要求
  90. - [OpenClaw](https://openclaw.ai) 已安装并正常运行(`openclaw doctor` 通过)
  91. - Node.js 环境(npm 可用)
  92. - 企业微信管理员权限
  93. - 公网可访问的服务器或隧道(用于接收企业微信回调)
  94. - (可选)FFmpeg + 语音转文字后端(二选一):
  95. - **远程 Qwen3-ASR**(推荐):需要 GPU 服务器运行 `asr_server.py`,详见 [`asr_api_README.md`](asr_api_README.md)
  96. - **本地 FunASR**:Python 3 + [FunASR](https://github.com/modelscope/FunASR) + PyTorch(支持 CUDA / Apple MPS / CPU)
  97. ### 🛠️ 安装
  98. #### 方式一:CLI 安装
  99. ```bash
  100. openclaw plugin install --path /path/to/openclaw-wechat
  101. ```
  102. #### 方式二:手动安装
  103. 1. 克隆本仓库:
  104. ```bash
  105. git clone https://github.com/Xueheng-Li/openclaw-wechat.git
  106. cd openclaw-wechat
  107. npm install
  108. ```
  109. 2. 在 OpenClaw 配置文件 `~/.openclaw/openclaw.json` 中注册插件:
  110. ```json
  111. {
  112. "plugins": {
  113. "load": {
  114. "paths": [
  115. "/path/to/openclaw-wechat"
  116. ]
  117. },
  118. "entries": {
  119. "wecom": {
  120. "enabled": true
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. > 💡 **注意**:插件 ID 为 `wecom`(与渠道名一致)。
  127. ### ⚙️ 配置(详细步骤)
  128. #### 第一步:创建企业微信自建应用 🏢
  129. 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
  130. 2. 进入 **应用管理** → **自建** → **创建应用**
  131. 3. 填写应用名称、Logo、可见范围等信息
  132. 4. 创建完成后,记录:
  133. - **AgentId**:应用的 AgentId
  134. - **Secret**:应用的 Secret
  135. #### 第二步:获取企业信息 🆔
  136. 1. 在管理后台首页,点击 **我的企业**
  137. 2. 记录 **企业ID (CorpId)**
  138. #### 第三步:配置接收消息 📨
  139. 1. 进入你创建的应用 → **接收消息** → **设置API接收**
  140. 2. 填写:
  141. - **URL**:`https://你的域名/wecom/callback`
  142. - **Token**:自定义一个 Token(随机字符串)
  143. - **EncodingAESKey**:点击随机生成
  144. 3. ⚠️ **先不要保存!** 需要先完成后续步骤启动 OpenClaw 服务
  145. > ⚠️ **务必记住这组配置与具体应用绑定**:`AgentId`、`Secret`、`Token`、`EncodingAESKey` 是针对某一个企业微信自建应用的,不能和另一套应用参数混用。混用时常见现象是“OpenClaw 可以发消息,但收不到你从企业微信发回来的消息”。
  146. #### 第四步:配置环境变量 🔑
  147. 在 `~/.openclaw/openclaw.json` 中添加环境变量:
  148. ```json
  149. {
  150. "env": {
  151. "vars": {
  152. "WECOM_CORP_ID": "你的企业ID",
  153. "WECOM_CORP_SECRET": "你的应用Secret",
  154. "WECOM_AGENT_ID": "你的应用AgentId",
  155. "WECOM_CALLBACK_TOKEN": "你设置的Token",
  156. "WECOM_CALLBACK_AES_KEY": "你生成的EncodingAESKey",
  157. "WECOM_WEBHOOK_PATH": "/wecom/callback",
  158. "WECOM_PROXY": ""
  159. }
  160. }
  161. }
  162. ```
  163. ##### 多账户配置
  164. 支持配置多个企业微信账户,使用 `WECOM_<ACCOUNT>_*` 格式:
  165. ```json
  166. {
  167. "env": {
  168. "vars": {
  169. "WECOM_CORP_ID": "默认账户企业ID",
  170. "WECOM_CORP_SECRET": "默认账户Secret",
  171. "WECOM_AGENT_ID": "默认账户AgentId",
  172. "WECOM_CALLBACK_TOKEN": "默认账户Token",
  173. "WECOM_CALLBACK_AES_KEY": "默认账户AESKey",
  174. "WECOM_SALES_CORP_ID": "销售账户企业ID",
  175. "WECOM_SALES_CORP_SECRET": "销售账户Secret",
  176. "WECOM_SALES_AGENT_ID": "销售账户AgentId",
  177. "WECOM_SALES_CALLBACK_TOKEN": "销售账户Token",
  178. "WECOM_SALES_CALLBACK_AES_KEY": "销售账户AESKey"
  179. }
  180. }
  181. }
  182. ```
  183. #### 第五步:配置公网访问 🔗
  184. 企业微信需要能够访问你的回调 URL。推荐使用 Cloudflare Tunnel:
  185. ```bash
  186. # 安装 cloudflared
  187. brew install cloudflared # macOS
  188. # 或 apt install cloudflared # Linux
  189. # 创建隧道
  190. cloudflared tunnel create openclaw
  191. # 配置隧道路由
  192. cloudflared tunnel route dns openclaw 你的域名
  193. # 启动隧道(将流量转发到本地 Gateway 端口)
  194. cloudflared tunnel --url http://localhost:18789 run openclaw
  195. ```
  196. 其他方案:SSH 隧道、Tailscale、Nginx 反向代理 + 端口转发等。
  197. #### 第六步:配置企业可信 IP 🛡️
  198. 企业微信要求调用 API(发送消息、获取 token 等)的服务器 IP 在白名单中。
  199. 1. 查询你服务器的**出口公网 IP**:
  200. ```bash
  201. curl -s https://ifconfig.me
  202. ```
  203. > ⚠️ 注意:这里需要的是你服务器**发出请求时的 IP**(出口 IP),不是 Cloudflare Tunnel 的 IP。Cloudflare Tunnel 只处理入站流量,服务器调用企业微信 API 时仍然走自己的公网出口。
  204. 2. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
  205. 3. 进入 **应用管理** → 选择你创建的自建应用
  206. 4. 滚动到页面底部,找到 **企业可信 IP**,点击 **配置**:
  207. ![企业可信 IP 位置](docs/images/ip-whitelist.png)
  208. 5. 添加上一步查到的 IP 地址
  209. > ⚠️ **IP 白名单是按应用隔离的**:每个自建应用(AgentId)有独立的「企业可信 IP」列表。为应用 A 添加的 IP **不会**自动对应用 B 生效。创建新应用后,必须单独为该应用添加可信 IP,否则会报 `60020` 错误。
  210. >
  211. > 💡 如果调用 API 报错 `60020`(not allow to access from your ip),检查日志中提示的 IP 并添加到**当前应用**的白名单即可。
  212. **动态 IP 场景(家用宽带 / 无固定公网 IP 的服务器)**:
  213. 如果你的服务器没有固定公网 IP,推荐通过一台有固定 IP 的 VPS 做正向代理:
  214. 1. 在 VPS 上安装代理(如 tinyproxy):
  215. ```bash
  216. sudo apt-get install -y tinyproxy
  217. ```
  218. 2. 编辑 `/etc/tinyproxy/tinyproxy.conf`,设置监听地址和访问控制(建议只允许内网访问)
  219. 3. 在插件配置中设置 `WECOM_PROXY` 环境变量指向代理:
  220. ```jsonc
  221. // ~/.openclaw/openclaw.json
  222. {
  223. "env": {
  224. "vars": {
  225. "WECOM_PROXY": "http://你的VPS内网IP:8888"
  226. }
  227. }
  228. }
  229. ```
  230. 4. 将 VPS 的**公网 IP** 添加到企业可信 IP 白名单
  231. > 插件内置了 `wecomFetch()` 函数,会自动通过 `WECOM_PROXY` 代理所有发往 `qyapi.weixin.qq.com` 的请求。如果使用 ZeroTier / Tailscale 等虚拟内网连接 VPS,代理地址填内网 IP 即可。
  232. #### 第七步:启动并验证 🚀
  233. 1. 重启 OpenClaw Gateway:
  234. ```bash
  235. openclaw gateway restart
  236. ```
  237. 2. 检查插件是否加载:
  238. ```bash
  239. openclaw plugin list
  240. ```
  241. 3. 验证 Webhook 可达:
  242. ```bash
  243. curl https://你的域名/wecom/callback
  244. # 应返回 "wecom webhook ok"
  245. ```
  246. 4. 回到企业微信管理后台,点击**保存**回调配置
  247. 5. 如果验证通过,配置完成!🎉
  248. #### 第七步补充:核对 AgentId 与回调参数是否是同一套应用
  249. 这一步非常关键,尤其是你创建过多个自建应用时。
  250. 必须逐项一致:
  251. - 企业微信后台显示的 `AgentId`
  252. - OpenClaw 配置里的 `WECOM_AGENT_ID` / `channels.wecom.agentId`
  253. - 当前应用对应的 `Secret`
  254. - 当前应用对应的 `Token`
  255. - 当前应用对应的 `EncodingAESKey`
  256. 推荐这样核对:
  257. ```bash
  258. openclaw config get channels.wecom
  259. curl https://你的域名/wecom/callback
  260. ```
  261. 如果你遇到下面这种情况,优先怀疑绑错了应用:
  262. - OpenClaw 主动发消息给你能成功
  263. - 你从企业微信回消息后,日志里没有新的 `wecom inbound`
  264. - callback 健康检查正常,但回调始终不进插件
  265. 一个真实案例是:本机误绑到 `agentId=1000002`,而企业微信后台实际配置的是 `agentId=1000003`。切回正确应用后,入站和回复立即恢复。
  266. #### 第八步:关联个人微信 📱(可选)
  267. 如果希望**个人微信**也能直接与 AI 对话,需在企业微信管理后台开启微信插件:
  268. 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
  269. 2. 进入 **我的企业** → **微信插件**
  270. 3. 用个人微信扫描页面上的二维码,关联到企业
  271. 4. 关联后,个人微信中会出现企业的应用入口,直接发消息即可
  272. <p align="center">
  273. <img src="docs/images/wecom2wechat.jpg" alt="企业微信管理后台 → 我的企业 → 微信插件" width="600">
  274. <br>
  275. <em>在企业微信管理后台「我的企业 → 微信插件」中,用个人微信扫码即可关联</em>
  276. </p>
  277. ### 🎙️ 语音转文字(stt.py)
  278. `stt.py` 支持两种语音识别模式,自动选择最优方案:
  279. | 模式 | 模型 | 运行位置 | 配置 |
  280. |------|------|---------|------|
  281. | 🌐 远程 ASR(推荐) | [Qwen3-ASR-0.6B](https://modelscope.cn/models/Qwen/Qwen3-ASR-0.6B) | GPU 服务器 | 设置 `WECOM_STT_URL` |
  282. | 💻 本地 ASR(降级) | [FunASR SenseVoice-Small](https://modelscope.cn/models/iic/SenseVoiceSmall) | 本地 CPU/MPS/CUDA | 设置 `WECOM_STT_PYTHON` |
  283. **优先级:** 企业微信自带识别 → 远程 Qwen3-ASR → 本地 FunASR
  284. **工作流程:**
  285. 1. 收到语音消息 → 下载 AMR 音频文件
  286. 2. 使用 FFmpeg 转换为 WAV(16kHz 单声道)
  287. 3. 调用 `stt.py`:优先 POST 到远程 ASR 服务,失败时降级到本地 FunASR
  288. 4. 将识别结果作为文本消息发送给 AI 代理
  289. **方式一:远程 ASR(推荐)**
  290. 在 `openclaw.json` 中配置远程 ASR 服务地址:
  291. ```jsonc
  292. "env": {
  293. "vars": {
  294. "WECOM_STT_URL": "http://your-gpu-server:8990/transcribe"
  295. }
  296. }
  297. ```
  298. 远程 ASR 服务部署详情参见 [`asr_api_README.md`](asr_api_README.md)。快速搭建:
  299. ```bash
  300. # GPU 服务器上
  301. python3 -m venv ~/qwen-asr-env && source ~/qwen-asr-env/bin/activate
  302. pip install qwen-asr fastapi uvicorn python-multipart
  303. # 下载模型(首次需联网)
  304. python3 -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen3-ASR-0.6B')"
  305. # 启动服务
  306. TRANSFORMERS_OFFLINE=1 python3 asr_server.py
  307. # 监听 0.0.0.0:8990,POST /transcribe 接收音频,GET /health 健康检查
  308. ```
  309. 生产部署建议使用 systemd 服务(`Restart=always`),详见 [`asr_api_README.md`](asr_api_README.md)。
  310. **性能参考(RTX 4090D):** 模型加载 ~3.7s,显存占用 ~3.7GB,短语音 ~2-4s 推理,支持 52 种语言 + 22 种中国方言。
  311. **方式二:本地 FunASR(无 GPU 服务器时)**
  312. ```bash
  313. # FFmpeg(音频格式转换)
  314. brew install ffmpeg # macOS
  315. # 或 apt install ffmpeg # Linux
  316. # Python 依赖
  317. pip install funasr modelscope torch torchaudio torchcodec
  318. ```
  319. > 🍎 **Apple Silicon (M1/M2/M3/M4) 支持:** `stt.py` 会自动检测并使用 MPS (Metal Performance Shaders) 加速推理。首次运行时模型会从 ModelScope 自动下载(约 1GB)。
  320. >
  321. > ⚠️ **macOS launchd 部署注意:** 如果 OpenClaw 以 launchd 服务运行,默认 `python3` 可能找不到 ML 依赖。需在 plist 中设置环境变量 `WECOM_STT_PYTHON` 指向正确的 Python 路径(如 conda 环境的 python3)。
  322. **独立使用:**
  323. ```bash
  324. # 远程模式
  325. WECOM_STT_URL=http://gpu-server:8990/transcribe python3 stt.py /path/to/audio.wav
  326. # 本地模式
  327. python3 stt.py /path/to/audio.wav
  328. ```
  329. > 💡 如果企业微信已开启语音识别(Recognition 字段),会优先使用企业微信的结果;仅在无 Recognition 字段时才会调用本地 STT。
  330. > 🤖 **AI Agent 自动部署:** 详细的多环境(CUDA / MPS / CPU)安装部署指南见 [`docs/stt-deploy-guide.md`](docs/stt-deploy-guide.md),可供 Claude Code 等 AI 编程助手直接参照执行自动化安装。
  331. ### 📝 使用
  332. 配置完成后,在企业微信或个人微信中找到你的应用,直接发送消息即可:
  333. 1. 📱 在企业微信中找到你创建的应用
  334. 2. 💬 发送文字、图片、语音、视频、文件消息
  335. 3. 🤖 AI 会自动回复
  336. **<img src="docs/images/wechat-icon.png" width="16" height="16"> 个人微信接入:** 在企业微信管理后台「我的企业 → 微信插件」中,用个人微信扫码关联即可。
  337. #### 命令系统
  338. | 命令 | 说明 |
  339. |------|------|
  340. | `/help` | 📋 显示帮助信息 |
  341. | `/status` | 📊 查看系统状态(含账户信息) |
  342. | `/clear` | 🗑️ 清除会话历史,开始新对话 |
  343. ### 🔧 环境变量参考
  344. | 变量名 | 必填 | 默认值 | 说明 |
  345. |--------|:----:|--------|------|
  346. | `WECOM_CORP_ID` | ✅ | — | 企业微信企业 ID |
  347. | `WECOM_CORP_SECRET` | ✅ | — | 自建应用的 Secret |
  348. | `WECOM_AGENT_ID` | ✅ | — | 自建应用的 AgentId |
  349. | `WECOM_CALLBACK_TOKEN` | ✅ | — | 回调配置的 Token |
  350. | `WECOM_CALLBACK_AES_KEY` | ✅ | — | 回调配置的 EncodingAESKey(43 字符 Base64) |
  351. | `WECOM_WEBHOOK_PATH` | ❌ | `/wecom/callback` | Webhook 路径 |
  352. | `WECOM_PROXY` | ❌ | — | 出站 WeCom API 的 HTTP 代理地址(如 `http://10.x.x.x:8888`) |
  353. ### 🔍 故障排查
  354. #### ❌ 回调验证失败
  355. 1. 检查 URL 是否可公网访问:
  356. ```bash
  357. curl https://你的域名/wecom/callback
  358. # 应返回 "wecom webhook ok"
  359. ```
  360. 2. 检查环境变量是否正确配置(Token 和 AESKey 必须与企业微信后台一致)
  361. 3. 查看 OpenClaw 日志:
  362. ```bash
  363. openclaw logs -f | grep wecom
  364. ```
  365. #### ❌ 消息没有回复
  366. 1. 检查日志中是否有 `wecom inbound` 记录
  367. 2. 确认 AI 模型配置正确(检查 `agents.defaults.model`)
  368. 3. 检查是否有错误日志
  369. 如果完全没有 `wecom inbound` 记录,再重点排查这 4 项是否来自**同一个自建应用**:
  370. 1. `AgentId`
  371. 2. `Secret`
  372. 3. `Token`
  373. 4. `EncodingAESKey`
  374. 很多“能发不能收”不是模型问题,而是本机绑定到了错误的企业微信应用。
  375. #### ❌ OpenClaw 2026.3+ 升级后,`/wecom/callback` 返回 Control UI 页面
  376. 这是新版 Gateway 兼容问题的典型症状。请确认:
  377. 1. 插件版本至少为 `0.3.7`
  378. 2. `openclaw channels status --probe` 中 WeCom 账户状态为 `running`
  379. 3. `curl https://你的域名/wecom/callback` 返回 `wecom webhook ok`
  380. 4. 日志中不再出现持续的 `health-monitor: restarting (reason: stopped)`
  381. 如果第 3 项返回的是 HTML 页面,通常说明 webhook 路由没有正确命中插件处理器。
  382. #### ❌ access_token 获取失败
  383. 1. 确认 `WECOM_CORP_ID` 和 `WECOM_CORP_SECRET` 正确
  384. 2. 检查应用的可见范围是否包含测试用户
  385. 3. 确认服务器能访问 `qyapi.weixin.qq.com`(如有代理需设置 `WECOM_PROXY`)
  386. #### ❌ 报错 `60020` (not allow to access from your ip)
  387. 企业微信 API 拒绝了你服务器的出口 IP。解决方法:
  388. 1. 查看错误日志中提示的 IP 地址
  389. 2. 将该 IP 添加到企业微信管理后台 → 应用管理 → 企业可信 IP
  390. 3. 如果服务器是动态 IP,参考第六步配置代理方案
  391. #### ❌ 报错 "Outbound not configured"
  392. OpenClaw 要求插件同时提供 `sendText` **和** `sendMedia` 两个出站方法。如果缺少任一方法,`createPluginHandler()` 会返回 null,导致此错误。确认插件版本包含完整的出站配置。
  393. #### ❌ 语音识别失败
  394. 1. 确认已安装 FFmpeg:`ffmpeg -version`
  395. 2. 如果使用远程 ASR:检查 `WECOM_STT_URL` 是否可达(`curl $WECOM_STT_URL`),检查 GPU 服务器上 `qwen3-asr.service` 是否运行
  396. 3. 如果使用本地 FunASR:确认已安装 Python 依赖 `python3 -c "from funasr import AutoModel"`
  397. 4. 首次本地运行会从 ModelScope 下载模型(约 1GB),需要网络连接
  398. 5. 本地 `stt.py` 会自动检测设备:CUDA GPU → Apple MPS → CPU(按优先级依次降级)
  399. #### ❌ 语音消息发送了但 AI 没收到内容
  400. `RawBody` 为空字符串 `""` 时会短路 `??` 运算符的回退链,导致 AI 收到空消息。确认插件版本中 `RawBody` 设置为 `content || messageText || ""`(而非 `content || ""`)。
  401. #### ❌ macOS 上 STT 找不到 Python / 模型加载失败
  402. macOS 通过 launchd 启动 OpenClaw 时,PATH 不包含 conda 环境。解决方法:
  403. 1. 在 `openclaw.json` 的 `env.vars` 中设置 `WECOM_STT_PYTHON` 指向 conda 环境中的 Python:
  404. ```jsonc
  405. {
  406. "env": {
  407. "vars": {
  408. "WECOM_STT_PYTHON": "/path/to/anaconda3/envs/sci/bin/python3"
  409. }
  410. }
  411. }
  412. ```
  413. 2. 如遇 Apple Silicon MPS 不支持某些操作,设置 `PYTORCH_ENABLE_MPS_FALLBACK=1`
  414. 3. 较新版本 torchaudio 需要额外安装 `torchcodec`:`pip install torchcodec`
  415. #### ❌ AI 无法"看到"用户发送的图片
  416. 图片会保存到本地磁盘并通过工具指令告知 AI 读取,而非以 base64 多模态方式传入。AI 需要主动调用 Read 工具才能看到图片内容,这取决于模型是否正确使用了工具。
  417. #### ❌ sendMedia 发送文件失败 / 文件被静默拦截
  418. OpenClaw 核心层通过 `mediaLocalRoots` 限制可发送的本地文件路径,仅允许以下目录:
  419. - `tmpdir`(系统临时目录)
  420. - `~/.openclaw/media`
  421. - `~/.openclaw/agents`
  422. - `~/.openclaw/workspace`
  423. - `~/.openclaw/sandboxes`
  424. 目录外的文件会被 `assertLocalMediaAllowed()` 静默拦截。解决方法:先将文件复制到 `~/.openclaw/workspace/` 再发送。
  425. #### ❌ Node.js `fetch()` 不走代理
  426. Node.js 原生 `fetch()` **不支持** `HTTPS_PROXY` 环境变量。插件使用 `undici.ProxyAgent` 配合 `dispatcher` 参数实现代理,仅需设置 `WECOM_PROXY` 环境变量即可,无需额外配置系统代理。
  427. ### 🏗️ 架构
  428. ```
  429. ┌──────────────┐ ┌──────────────────┐ ┌───────────────┐
  430. │ 企业微信 │ ──XML──▶│ OpenClaw Gateway │ ──────▶ │ AI Agent │
  431. │ / 个人微信 │ │ (port 18789) │ │ (LLM) │
  432. │ │ ◀──API──│ │ ◀────── │ │
  433. └──────────────┘ └──────┬───────────┘ └───────────────┘
  434. │
  435. ┌───────────┼───────────┐
  436. ▼ ▼ ▼
  437. ┌──────────┐ ┌────────┐ ┌──────────┐
  438. │ 消息加解密 │ │ STT │ │ Chat UI │
  439. │ AES-256 │ │ FunASR │ │ Broadcast│
  440. └──────────┘ └────────┘ └──────────┘
  441. ```
  442. **消息流程:**
  443. 1. 📩 用户在企业微信/个人微信发送消息
  444. 2. 🔒 企业微信服务器将加密的 XML 回调发送到你的 Webhook URL
  445. 3. 🔓 插件验证签名,解密消息(AES-256-CBC)
  446. 4. ⚡ 立即返回 HTTP 200(企业微信要求 5 秒内响应)
  447. 5. 🔄 异步处理:根据消息类型分发处理
  448. - 📝 文本 → 直接交给 AI
  449. - 🖼️ 图片 → 下载保存 → AI Vision 分析
  450. - 🎙️ 语音 → 下载 AMR → FFmpeg 转 WAV → 远程 Qwen3-ASR / 本地 FunASR → 文本交给 AI
  451. - 📹 视频/📎 文件 → 下载保存 → 通知 AI
  452. - 🔗 链接 → 提取元信息 → 交给 AI
  453. 6. 🤖 AI 代理生成回复
  454. 7. 📤 回复经 Markdown 转换后,自动分段发送回企业微信
  455. 8. 🖥️ 同时写入 Transcript + 广播到 Chat UI
  456. ### 📁 项目结构
  457. ```
  458. openclaw-wechat/
  459. ├── index.js # 入口文件(重导出)
  460. ├── src/
  461. │ └── index.js # 插件主逻辑(1400+ 行)
  462. ├── stt.py # 🎙️ 语音识别(远程 Qwen3-ASR + 本地 FunASR 降级)
  463. ├── asr_server.py # 🖥️ 远程 ASR 服务(FastAPI + Qwen3-ASR,部署到 GPU 服务器)
  464. ├── openclaw.plugin.json # OpenClaw 插件描述文件(新格式)
  465. ├── clawdbot.plugin.json # ClawdBot 插件描述文件(兼容旧版)
  466. ├── package.json # npm 包配置 (v0.3.7)
  467. ├── .env.example # 环境变量示例
  468. ├── skills/
  469. │ └── wecom-notify/ # 📨 Claude Code WeCom 通知技能
  470. │ ├── SKILL.md
  471. │ └── scripts/
  472. │ └── send_wecom.py
  473. ├── docs/
  474. │ └── channels/
  475. │ └── wecom.md # 渠道文档
  476. ├── CHANGELOG.md # 版本变更日志
  477. └── LICENSE # MIT 许可证
  478. ```
  479. ### 📨 Claude Code WeCom 通知技能
  480. 本仓库还包含一个独立的 **Claude Code 技能**(`wecom-notify`),可以在 Claude Code 中直接发送企业微信消息。这是一个**独立工具**,不依赖 OpenClaw 插件,直接调用企业微信 API。
  481. #### 安装技能
  482. 将 `skills/wecom-notify/` 目录复制到 `~/.claude/skills/` 即可:
  483. ```bash
  484. cp -r skills/wecom-notify ~/.claude/skills/
  485. ```
  486. #### 使用方式
  487. 在 Claude Code 中可以直接使用 `/wecom-notify` 命令,或让 AI 自动调用:
  488. ```bash
  489. # 发送文本消息
  490. python3 skills/wecom-notify/scripts/send_wecom.py "你好,这是一条测试消息"
  491. # 指定接收人
  492. python3 skills/wecom-notify/scripts/send_wecom.py "消息内容" --to UserName
  493. # 发送图片
  494. python3 skills/wecom-notify/scripts/send_wecom.py --image /path/to/photo.png
  495. # 发送文件
  496. python3 skills/wecom-notify/scripts/send_wecom.py --file /path/to/report.pdf
  497. ```
  498. #### 特点
  499. - 🔧 **零依赖**:仅使用 Python 标准库(`urllib.request`、`json`),无需 `pip install`
  500. - 📄 自动从 `~/.openclaw/openclaw.json` 读取 WeCom 配置(复用 OpenClaw 的环境变量)
  501. - 📝 支持文本(2048 字节限制)、图片(jpg/png/gif,≤2MB)、文件(任意格式,≤20MB)
  502. - 🌐 支持 `WECOM_PROXY` 代理
  503. ### 📜 版本历史
  504. 查看 [CHANGELOG.md](./CHANGELOG.md) 了解完整版本历史。
  505. ---
  506. ## 🔗 相关链接
  507. - 🌐 [OpenClaw 官方网站](https://openclaw.ai)
  508. - 📖 [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
  509. - 🔐 [企业微信消息加解密](https://developer.work.weixin.qq.com/document/path/90968)
  510. - 🍴 [上游项目:dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat)
  511. - 🎙️ [FunASR SenseVoice](https://modelscope.cn/models/iic/SenseVoiceSmall)
  512. ## 📄 许可证
  513. [MIT License](./LICENSE)
  514. ## 🙏 致谢
  515. - 🍴 原始项目:[dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat),作者 **勾勾的数字生命** ([@dingxiang-me](https://github.com/dingxiang-me))
  516. - 🤖 [OpenClaw](https://openclaw.ai),由 Peter Steinberger 和 OpenClaw 社区开发
  517. - 🎙️ [FunASR SenseVoice](https://github.com/modelscope/FunASR),由阿里巴巴达摩院开发
  518. ## 🤝 贡献
  519. 欢迎提交 Issue 和 Pull Request!

Ratings and comments

Sign in to rate this skill.

Sign in

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