wecom-notify
xueheng-li/openclaw-wechat · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por xueheng-li/openclaw-wechat no skills.sh. Instale com: npx skills add xueheng-li/openclaw-wechat@wecom-notify
Details
- Kind
- Agent skills
- Publisher
- xueheng-li
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 152
- Forks
- 21
- Last push
- 2026-03-07T15:30:06Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-10-06 04:47:38
- Updated
- 2026-10-06 04:47:38
- Origin id
xueheng-li/openclaw-wechat/wecom-notify
README
# 🤖 OpenClaw 企业微信插件（支持直接加到微信）
> ⭐ 如果觉得有用，请点击右上角的 **Star** 支持一下！
### 🔍 项目概述
**openclaw-wechat** 是一个 [OpenClaw](https://openclaw.ai)（原 ClawdBot/Moltbot）的 <img src="https://raw.githubusercontent.com/xueheng-li/openclaw-wechat/HEAD/docs/images/wecom-icon.png" width="16" height="16"> **企业微信渠道插件**，让你的 AI 智能体通过企业微信自建应用与用户对话。接入企业微信后，<img src="https://raw.githubusercontent.com/xueheng-li/openclaw-wechat/HEAD/docs/images/wechat-icon.png" width="16" height="16"> **个人微信用户也可以直接对话**——只需在企业微信管理后台「我的企业 → 微信插件」中扫码关联即可。
> 🍴 本项目 fork 自 [dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat)（v0.1.0，作者：勾勾的数字生命），并进行了大量功能扩展以兼容新版 OpenClaw。
### 🧠 v0.3.7 — OpenClaw 2026.3+ 兼容修复
**修复了 OpenClaw 2026.3+ 中企业微信“能发不能收”的典型故障**，核心兼容点包括：
- ✅ 补齐 `status` 运行态信息，避免 health-monitor 持续误判渠道已停止
- ✅ `gateway.startAccount` 改为常驻直到 `abortSignal`，不再反复 auto-restart
- ✅ `registerHttpRoute()` 显式增加 `auth: "plugin"` 和 `match: "exact"`
- ✅ `/wecom/callback` 不再被 Control UI 的 SPA fallback 覆盖，健康检查稳定返回 `wecom webhook ok`
- ✅ 实战验证：错误绑定 `AgentId` 也会导致“能发不能收”，现在 README 已加入对齐检查
### 🧠 v0.3.6 — 对话记忆系统（与官方 Telegram Channel 实现一致）
**解决了企业微信渠道"失忆"问题**：之前每条消息都是独立对话，AI 无法记住上下文。
现在使用 OpenClaw SDK 的 `recordPendingHistoryEntry` + `buildPendingHistoryContextFromMap` 实现对话历史管理，**与官方 Telegram/Discord 渠道完全一致**：
- 📝 自动记录用户消息和 AI 回复到内存历史
- 🔄 每次对话自动携带最近 20 条历史上下文
- 🗑️ `/clear` 命令同时清除 session 和内存历史
- 📊 `/status` 显示当前历史消息数量
### ✨ 与上游的主要区别
| 特性 | 上游 (OpenClaw-Wechat v0.1.0) | 本 Fork (v0.3.7) |
|------|------|------|
| 🎯 平台兼容 | ClawdBot | OpenClaw（同时保留 ClawdBot 兼容） |
| 📄 插件描述文件 | `clawdbot.plugin.json` | `openclaw.plugin.json` + `clawdbot.plugin.json` |
| ⚙️ 配置文件 | `~/.clawdbot/clawdbot.json` | `~/.openclaw/openclaw.json` |
| 📨 消息类型 | 文本、图片、语音 | 文本、图片、语音、**视频**、**文件**、**链接** |
| 📤 发送类型 | 仅文本 | 文本、**图片**、**视频**、**文件**（自动类型识别） |
| 🎙️ 语音识别 | 仅企业微信自带 | 企业微信自带 + **远程 Qwen3-ASR** / 本地 FunASR（自动降级） |
| 🧠 对话历史 | 无 | **SDK 级对话记忆（与官方 Telegram 一致）** |
| 🖥️ Chat UI | 无 | **消息同步到 Transcript + 实时广播** |
| 🌐 代理支持 | 无 | **WECOM_PROXY 环境变量** |
| 📝 消息分段 | 按字符 | **按字节（UTF-8），二分查找分割** |
### 📋 功能特性
#### 🔌 核心功能
- [x] ✅ 支持个人微信对话（通过企业微信桥接）
- [x] ✅ 接收/发送企业微信消息
- [x] ✅ 自动调用 AI 代理处理消息
- [x] ✅ 消息签名验证（SHA1）和 AES-256-CBC 加解密
- [x] ✅ Webhook URL 验证
- [x] ✅ OpenClaw 2026.3+ 渠道生命周期兼容
- [x] ✅ access_token 自动缓存和刷新
#### 🎬 媒体功能
- [x] 🖼️ 图片消息收发 + AI Vision 识别
- [x] 🎙️ 语音消息转文字（企业微信自带 + 远程 Qwen3-ASR + 本地 FunASR 降级）
- [x] 📹 视频消息接收、下载、发送
- [x] 📎 文件消息接收（支持 .txt/.md/.json/.pdf 等自动读取）
- [x] 🔗 链接分享消息接收
#### 🎨 用户体验
- [x] 📝 命令系统（`/help`、`/status`、`/clear`）
- [x] 🔄 Markdown → 纯文本自动转换（企业微信不支持 Markdown 渲染）
- [x] ✂️ 长消息自动分段（2048 字节限制，按 UTF-8 字节精确分割）
- [x] 🧠 对话历史记忆（SDK 级，与官方 Telegram 一致）
- [x] 🛡️ API 限流保护（10 并发，100ms 间隔）
- [x] ⏳ 处理中提示（"收到您的消息，正在处理中..."）
#### 🚀 高级功能
- [x] 👥 多账户支持（`WECOM_<ACCOUNT>_*` 格式）
- [x] 🔒 Token 并发安全（Promise 锁）
- [x] 🖥️ Chat UI 集成（Transcript 写入 + Gateway 实时广播）
- [x] 🌐 HTTP 代理支持（`WECOM_PROXY`）
- [x] 🩺 渠道状态探测（status/probe，兼容新版 OpenClaw health monitor）
### 🆕 OpenClaw 2026.3+ 兼容说明
OpenClaw 2026.3+ 对渠道插件的要求比旧版本更严格。企业微信插件如果只保留旧版写法，常见症状是：
- 能主动发送消息
- `/wecom/callback` 返回的是 Control UI HTML，而不是 `wecom webhook ok`
- `health-monitor` 日志里反复出现 `restarting (reason: stopped)`
- 企业微信后台显示消息发送成功，但 OpenClaw 没有任何 `wecom inbound` 日志
本插件从 `v0.3.7` 起已补齐以下兼容点：
- `status`：提供运行态摘要、账户快照、探测结果
- `gateway.startAccount`：保持常驻直到 `abortSignal`
- `api.registerHttpRoute()`：显式使用 `auth: "plugin"` 和 `match: "exact"`
如果你升级到 OpenClaw `2026.3.x` 或更高版本，建议至少验证这三项：
```bash
openclaw channels status --probe
curl https://你的域名/wecom/callback
openclaw logs -f | grep wecom
```
期望结果：
- 渠道状态显示 `running`
- callback 返回 `wecom webhook ok`
- 收到消息时能看到 `wecom inbound:`、`session registered`、`sent AI reply`
### 📊 支持的消息类型
| 类型 | 接收 | 发送 | 说明 |
|:----:|:----:|:----:|------|
| 📝 文本 | ✅ | ✅ | 完全支持，超长消息自动按字节分段 |
| 🖼️ 图片 | ✅ | ✅ | 支持 AI Vision 识别，下载后保存到临时文件 |
| 🎙️ 语音 | ✅ | ❌ | 企业微信自带识别 + 远程 Qwen3-ASR / 本地 FunASR 降级（AMR→WAV→文本） |
| 📹 视频 | ✅ | ✅ | 自动下载保存，支持发送视频消息 |
| 📎 文件 | ✅ | ✅ | 自动下载，可读类型自动交给 AI 分析 |
### 📦 前置要求
- [OpenClaw](https://openclaw.ai) 已安装并正常运行（`openclaw doctor` 通过）
- Node.js 环境（npm 可用）
- 企业微信管理员权限
- 公网可访问的服务器或隧道（用于接收企业微信回调）
- （可选）FFmpeg + 语音转文字后端（二选一）：
- **远程 Qwen3-ASR**（推荐）：需要 GPU 服务器运行 `asr_server.py`，详见 [`asr_api_README.md`](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/asr_api_README.md)
- **本地 FunASR**：Python 3 + [FunASR](https://github.com/modelscope/FunASR) + PyTorch（支持 CUDA / Apple MPS / CPU）
### 🛠️ 安装
#### 方式一：CLI 安装
```bash
openclaw plugin install --path /path/to/openclaw-wechat
```
#### 方式二：手动安装
1. 克隆本仓库：
```bash
git clone https://github.com/Xueheng-Li/openclaw-wechat.git
cd openclaw-wechat
npm install
```
2. 在 OpenClaw 配置文件 `~/.openclaw/openclaw.json` 中注册插件：
```json
{
"plugins": {
"load": {
"paths": [
"/path/to/openclaw-wechat"
]
},
"entries": {
"wecom": {
"enabled": true
}
}
}
}
```
> 💡 **注意**：插件 ID 为 `wecom`（与渠道名一致）。
### ⚙️ 配置（详细步骤）
#### 第一步：创建企业微信自建应用 🏢
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
2. 进入 **应用管理** → **自建** → **创建应用**
3. 填写应用名称、Logo、可见范围等信息
4. 创建完成后，记录：
- **AgentId**：应用的 AgentId
- **Secret**：应用的 Secret
#### 第二步：获取企业信息 🆔
1. 在管理后台首页，点击 **我的企业**
2. 记录 **企业ID (CorpId)**
#### 第三步：配置接收消息 📨
1. 进入你创建的应用 → **接收消息** → **设置API接收**
2. 填写：
- **URL**：`https://你的域名/wecom/callback`
- **Token**：自定义一个 Token（随机字符串）
- **EncodingAESKey**：点击随机生成
3. ⚠️ **先不要保存！** 需要先完成后续步骤启动 OpenClaw 服务
> ⚠️ **务必记住这组配置与具体应用绑定**：`AgentId`、`Secret`、`Token`、`EncodingAESKey` 是针对某一个企业微信自建应用的，不能和另一套应用参数混用。混用时常见现象是“OpenClaw 可以发消息，但收不到你从企业微信发回来的消息”。
#### 第四步：配置环境变量 🔑
在 `~/.openclaw/openclaw.json` 中添加环境变量：
```json
{
"env": {
"vars": {
"WECOM_CORP_ID": "你的企业ID",
"WECOM_CORP_SECRET": "你的应用Secret",
"WECOM_AGENT_ID": "你的应用AgentId",
"WECOM_CALLBACK_TOKEN": "你设置的Token",
"WECOM_CALLBACK_AES_KEY": "你生成的EncodingAESKey",
"WECOM_WEBHOOK_PATH": "/wecom/callback",
"WECOM_PROXY": ""
}
}
}
```
##### 多账户配置
支持配置多个企业微信账户，使用 `WECOM_<ACCOUNT>_*` 格式：
```json
{
"env": {
"vars": {
"WECOM_CORP_ID": "默认账户企业ID",
"WECOM_CORP_SECRET": "默认账户Secret",
"WECOM_AGENT_ID": "默认账户AgentId",
"WECOM_CALLBACK_TOKEN": "默认账户Token",
"WECOM_CALLBACK_AES_KEY": "默认账户AESKey",
"WECOM_SALES_CORP_ID": "销售账户企业ID",
"WECOM_SALES_CORP_SECRET": "销售账户Secret",
"WECOM_SALES_AGENT_ID": "销售账户AgentId",
"WECOM_SALES_CALLBACK_TOKEN": "销售账户Token",
"WECOM_SALES_CALLBACK_AES_KEY": "销售账户AESKey"
}
}
}
```
#### 第五步：配置公网访问 🔗
企业微信需要能够访问你的回调 URL。推荐使用 Cloudflare Tunnel：
```bash
# 安装 cloudflared
brew install cloudflared # macOS
# 或 apt install cloudflared # Linux
# 创建隧道
cloudflared tunnel create openclaw
# 配置隧道路由
cloudflared tunnel route dns openclaw 你的域名
# 启动隧道（将流量转发到本地 Gateway 端口）
cloudflared tunnel --url http://localhost:18789 run openclaw
```
其他方案：SSH 隧道、Tailscale、Nginx 反向代理 + 端口转发等。
#### 第六步：配置企业可信 IP 🛡️
企业微信要求调用 API（发送消息、获取 token 等）的服务器 IP 在白名单中。
1. 查询你服务器的**出口公网 IP**：
```bash
curl -s https://ifconfig.me
```
> ⚠️ 注意：这里需要的是你服务器**发出请求时的 IP**（出口 IP），不是 Cloudflare Tunnel 的 IP。Cloudflare Tunnel 只处理入站流量，服务器调用企业微信 API 时仍然走自己的公网出口。
2. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
3. 进入 **应用管理** → 选择你创建的自建应用
4. 滚动到页面底部，找到 **企业可信 IP**，点击 **配置**：
5. 添加上一步查到的 IP 地址
> ⚠️ **IP 白名单是按应用隔离的**：每个自建应用（AgentId）有独立的「企业可信 IP」列表。为应用 A 添加的 IP **不会**自动对应用 B 生效。创建新应用后，必须单独为该应用添加可信 IP，否则会报 `60020` 错误。
>
> 💡 如果调用 API 报错 `60020`（not allow to access from your ip），检查日志中提示的 IP 并添加到**当前应用**的白名单即可。
**动态 IP 场景（家用宽带 / 无固定公网 IP 的服务器）**：
如果你的服务器没有固定公网 IP，推荐通过一台有固定 IP 的 VPS 做正向代理：
1. 在 VPS 上安装代理（如 tinyproxy）：
```bash
sudo apt-get install -y tinyproxy
```
2. 编辑 `/etc/tinyproxy/tinyproxy.conf`，设置监听地址和访问控制（建议只允许内网访问）
3. 在插件配置中设置 `WECOM_PROXY` 环境变量指向代理：
```jsonc
// ~/.openclaw/openclaw.json
{
"env": {
"vars": {
"WECOM_PROXY": "http://你的VPS内网IP:8888"
}
}
}
```
4. 将 VPS 的**公网 IP** 添加到企业可信 IP 白名单
> 插件内置了 `wecomFetch()` 函数，会自动通过 `WECOM_PROXY` 代理所有发往 `qyapi.weixin.qq.com` 的请求。如果使用 ZeroTier / Tailscale 等虚拟内网连接 VPS，代理地址填内网 IP 即可。
#### 第七步：启动并验证 🚀
1. 重启 OpenClaw Gateway：
```bash
openclaw gateway restart
```
2. 检查插件是否加载：
```bash
openclaw plugin list
```
3. 验证 Webhook 可达：
```bash
curl https://你的域名/wecom/callback
# 应返回 "wecom webhook ok"
```
4. 回到企业微信管理后台，点击**保存**回调配置
5. 如果验证通过，配置完成！🎉
#### 第七步补充：核对 AgentId 与回调参数是否是同一套应用
这一步非常关键，尤其是你创建过多个自建应用时。
必须逐项一致：
- 企业微信后台显示的 `AgentId`
- OpenClaw 配置里的 `WECOM_AGENT_ID` / `channels.wecom.agentId`
- 当前应用对应的 `Secret`
- 当前应用对应的 `Token`
- 当前应用对应的 `EncodingAESKey`
推荐这样核对：
```bash
openclaw config get channels.wecom
curl https://你的域名/wecom/callback
```
如果你遇到下面这种情况，优先怀疑绑错了应用：
- OpenClaw 主动发消息给你能成功
- 你从企业微信回消息后，日志里没有新的 `wecom inbound`
- callback 健康检查正常，但回调始终不进插件
一个真实案例是：本机误绑到 `agentId=1000002`，而企业微信后台实际配置的是 `agentId=1000003`。切回正确应用后，入站和回复立即恢复。
#### 第八步：关联个人微信 📱（可选）
如果希望**个人微信**也能直接与 AI 对话，需在企业微信管理后台开启微信插件：
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
2. 进入 **我的企业** → **微信插件**
3. 用个人微信扫描页面上的二维码，关联到企业
4. 关联后，个人微信中会出现企业的应用入口，直接发消息即可
<p align="center">
<img src="https://raw.githubusercontent.com/xueheng-li/openclaw-wechat/HEAD/docs/images/wecom2wechat.jpg" alt="企业微信管理后台 → 我的企业 → 微信插件" width="600">
<br>
<em>在企业微信管理后台「我的企业 → 微信插件」中，用个人微信扫码即可关联</em>
</p>
### 🎙️ 语音转文字（stt.py）
`stt.py` 支持两种语音识别模式，自动选择最优方案：
| 模式 | 模型 | 运行位置 | 配置 |
|------|------|---------|------|
| 🌐 远程 ASR（推荐） | [Qwen3-ASR-0.6B](https://modelscope.cn/models/Qwen/Qwen3-ASR-0.6B) | GPU 服务器 | 设置 `WECOM_STT_URL` |
| 💻 本地 ASR（降级） | [FunASR SenseVoice-Small](https://modelscope.cn/models/iic/SenseVoiceSmall) | 本地 CPU/MPS/CUDA | 设置 `WECOM_STT_PYTHON` |
**优先级：** 企业微信自带识别 → 远程 Qwen3-ASR → 本地 FunASR
**工作流程：**
1. 收到语音消息 → 下载 AMR 音频文件
2. 使用 FFmpeg 转换为 WAV（16kHz 单声道）
3. 调用 `stt.py`：优先 POST 到远程 ASR 服务，失败时降级到本地 FunASR
4. 将识别结果作为文本消息发送给 AI 代理
**方式一：远程 ASR（推荐）**
在 `openclaw.json` 中配置远程 ASR 服务地址：
```jsonc
"env": {
"vars": {
"WECOM_STT_URL": "http://your-gpu-server:8990/transcribe"
}
}
```
远程 ASR 服务部署详情参见 [`asr_api_README.md`](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/asr_api_README.md)。快速搭建：
```bash
# GPU 服务器上
python3 -m venv ~/qwen-asr-env && source ~/qwen-asr-env/bin/activate
pip install qwen-asr fastapi uvicorn python-multipart
# 下载模型（首次需联网）
python3 -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen3-ASR-0.6B')"
# 启动服务
TRANSFORMERS_OFFLINE=1 python3 asr_server.py
# 监听 0.0.0.0:8990，POST /transcribe 接收音频，GET /health 健康检查
```
生产部署建议使用 systemd 服务（`Restart=always`），详见 [`asr_api_README.md`](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/asr_api_README.md)。
**性能参考（RTX 4090D）：** 模型加载 ~3.7s，显存占用 ~3.7GB，短语音 ~2-4s 推理，支持 52 种语言 + 22 种中国方言。
**方式二：本地 FunASR（无 GPU 服务器时）**
```bash
# FFmpeg（音频格式转换）
brew install ffmpeg # macOS
# 或 apt install ffmpeg # Linux
# Python 依赖
pip install funasr modelscope torch torchaudio torchcodec
```
> 🍎 **Apple Silicon (M1/M2/M3/M4) 支持：** `stt.py` 会自动检测并使用 MPS (Metal Performance Shaders) 加速推理。首次运行时模型会从 ModelScope 自动下载（约 1GB）。
>
> ⚠️ **macOS launchd 部署注意：** 如果 OpenClaw 以 launchd 服务运行，默认 `python3` 可能找不到 ML 依赖。需在 plist 中设置环境变量 `WECOM_STT_PYTHON` 指向正确的 Python 路径（如 conda 环境的 python3）。
**独立使用：**
```bash
# 远程模式
WECOM_STT_URL=http://gpu-server:8990/transcribe python3 stt.py /path/to/audio.wav
# 本地模式
python3 stt.py /path/to/audio.wav
```
> 💡 如果企业微信已开启语音识别（Recognition 字段），会优先使用企业微信的结果；仅在无 Recognition 字段时才会调用本地 STT。
> 🤖 **AI Agent 自动部署：** 详细的多环境（CUDA / MPS / CPU）安装部署指南见 [`docs/stt-deploy-guide.md`](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/docs/stt-deploy-guide.md)，可供 Claude Code 等 AI 编程助手直接参照执行自动化安装。
### 📝 使用
配置完成后，在企业微信或个人微信中找到你的应用，直接发送消息即可：
1. 📱 在企业微信中找到你创建的应用
2. 💬 发送文字、图片、语音、视频、文件消息
3. 🤖 AI 会自动回复
**<img src="https://raw.githubusercontent.com/xueheng-li/openclaw-wechat/HEAD/docs/images/wechat-icon.png" width="16" height="16"> 个人微信接入：** 在企业微信管理后台「我的企业 → 微信插件」中，用个人微信扫码关联即可。
#### 命令系统
| 命令 | 说明 |
|------|------|
| `/help` | 📋 显示帮助信息 |
| `/status` | 📊 查看系统状态（含账户信息） |
| `/clear` | 🗑️ 清除会话历史，开始新对话 |
### 🔧 环境变量参考
| 变量名 | 必填 | 默认值 | 说明 |
|--------|:----:|--------|------|
| `WECOM_CORP_ID` | ✅ | — | 企业微信企业 ID |
| `WECOM_CORP_SECRET` | ✅ | — | 自建应用的 Secret |
| `WECOM_AGENT_ID` | ✅ | — | 自建应用的 AgentId |
| `WECOM_CALLBACK_TOKEN` | ✅ | — | 回调配置的 Token |
| `WECOM_CALLBACK_AES_KEY` | ✅ | — | 回调配置的 EncodingAESKey（43 字符 Base64） |
| `WECOM_WEBHOOK_PATH` | ❌ | `/wecom/callback` | Webhook 路径 |
| `WECOM_PROXY` | ❌ | — | 出站 WeCom API 的 HTTP 代理地址（如 `http://10.x.x.x:8888`） |
### 🔍 故障排查
#### ❌ 回调验证失败
1. 检查 URL 是否可公网访问：
```bash
curl https://你的域名/wecom/callback
# 应返回 "wecom webhook ok"
```
2. 检查环境变量是否正确配置（Token 和 AESKey 必须与企业微信后台一致）
3. 查看 OpenClaw 日志：
```bash
openclaw logs -f | grep wecom
```
#### ❌ 消息没有回复
1. 检查日志中是否有 `wecom inbound` 记录
2. 确认 AI 模型配置正确（检查 `agents.defaults.model`）
3. 检查是否有错误日志
如果完全没有 `wecom inbound` 记录，再重点排查这 4 项是否来自**同一个自建应用**：
1. `AgentId`
2. `Secret`
3. `Token`
4. `EncodingAESKey`
很多“能发不能收”不是模型问题，而是本机绑定到了错误的企业微信应用。
#### ❌ OpenClaw 2026.3+ 升级后，`/wecom/callback` 返回 Control UI 页面
这是新版 Gateway 兼容问题的典型症状。请确认：
1. 插件版本至少为 `0.3.7`
2. `openclaw channels status --probe` 中 WeCom 账户状态为 `running`
3. `curl https://你的域名/wecom/callback` 返回 `wecom webhook ok`
4. 日志中不再出现持续的 `health-monitor: restarting (reason: stopped)`
如果第 3 项返回的是 HTML 页面，通常说明 webhook 路由没有正确命中插件处理器。
#### ❌ access_token 获取失败
1. 确认 `WECOM_CORP_ID` 和 `WECOM_CORP_SECRET` 正确
2. 检查应用的可见范围是否包含测试用户
3. 确认服务器能访问 `qyapi.weixin.qq.com`（如有代理需设置 `WECOM_PROXY`）
#### ❌ 报错 `60020` (not allow to access from your ip)
企业微信 API 拒绝了你服务器的出口 IP。解决方法：
1. 查看错误日志中提示的 IP 地址
2. 将该 IP 添加到企业微信管理后台 → 应用管理 → 企业可信 IP
3. 如果服务器是动态 IP，参考第六步配置代理方案
#### ❌ 报错 "Outbound not configured"
OpenClaw 要求插件同时提供 `sendText` **和** `sendMedia` 两个出站方法。如果缺少任一方法，`createPluginHandler()` 会返回 null，导致此错误。确认插件版本包含完整的出站配置。
#### ❌ 语音识别失败
1. 确认已安装 FFmpeg：`ffmpeg -version`
2. 如果使用远程 ASR：检查 `WECOM_STT_URL` 是否可达（`curl $WECOM_STT_URL`），检查 GPU 服务器上 `qwen3-asr.service` 是否运行
3. 如果使用本地 FunASR：确认已安装 Python 依赖 `python3 -c "from funasr import AutoModel"`
4. 首次本地运行会从 ModelScope 下载模型（约 1GB），需要网络连接
5. 本地 `stt.py` 会自动检测设备：CUDA GPU → Apple MPS → CPU（按优先级依次降级）
#### ❌ 语音消息发送了但 AI 没收到内容
`RawBody` 为空字符串 `""` 时会短路 `??` 运算符的回退链，导致 AI 收到空消息。确认插件版本中 `RawBody` 设置为 `content || messageText || ""`（而非 `content || ""`）。
#### ❌ macOS 上 STT 找不到 Python / 模型加载失败
macOS 通过 launchd 启动 OpenClaw 时，PATH 不包含 conda 环境。解决方法：
1. 在 `openclaw.json` 的 `env.vars` 中设置 `WECOM_STT_PYTHON` 指向 conda 环境中的 Python：
```jsonc
{
"env": {
"vars": {
"WECOM_STT_PYTHON": "/path/to/anaconda3/envs/sci/bin/python3"
}
}
}
```
2. 如遇 Apple Silicon MPS 不支持某些操作，设置 `PYTORCH_ENABLE_MPS_FALLBACK=1`
3. 较新版本 torchaudio 需要额外安装 `torchcodec`：`pip install torchcodec`
#### ❌ AI 无法"看到"用户发送的图片
图片会保存到本地磁盘并通过工具指令告知 AI 读取，而非以 base64 多模态方式传入。AI 需要主动调用 Read 工具才能看到图片内容，这取决于模型是否正确使用了工具。
#### ❌ sendMedia 发送文件失败 / 文件被静默拦截
OpenClaw 核心层通过 `mediaLocalRoots` 限制可发送的本地文件路径，仅允许以下目录：
- `tmpdir`（系统临时目录）
- `~/.openclaw/media`
- `~/.openclaw/agents`
- `~/.openclaw/workspace`
- `~/.openclaw/sandboxes`
目录外的文件会被 `assertLocalMediaAllowed()` 静默拦截。解决方法：先将文件复制到 `~/.openclaw/workspace/` 再发送。
#### ❌ Node.js `fetch()` 不走代理
Node.js 原生 `fetch()` **不支持** `HTTPS_PROXY` 环境变量。插件使用 `undici.ProxyAgent` 配合 `dispatcher` 参数实现代理，仅需设置 `WECOM_PROXY` 环境变量即可，无需额外配置系统代理。
### 🏗️ 架构
```
┌──────────────┐ ┌──────────────────┐ ┌───────────────┐
│ 企业微信 │ ──XML──▶│ OpenClaw Gateway │ ──────▶ │ AI Agent │
│ / 个人微信 │ │ (port 18789) │ │ (LLM) │
│ │ ◀──API──│ │ ◀────── │ │
└──────────────┘ └──────┬───────────┘ └───────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌──────────┐ ┌────────┐ ┌──────────┐
│ 消息加解密 │ │ STT │ │ Chat UI │
│ AES-256 │ │ FunASR │ │ Broadcast│
└──────────┘ └────────┘ └──────────┘
```
**消息流程：**
1. 📩 用户在企业微信/个人微信发送消息
2. 🔒 企业微信服务器将加密的 XML 回调发送到你的 Webhook URL
3. 🔓 插件验证签名，解密消息（AES-256-CBC）
4. ⚡ 立即返回 HTTP 200（企业微信要求 5 秒内响应）
5. 🔄 异步处理：根据消息类型分发处理
- 📝 文本 → 直接交给 AI
- 🖼️ 图片 → 下载保存 → AI Vision 分析
- 🎙️ 语音 → 下载 AMR → FFmpeg 转 WAV → 远程 Qwen3-ASR / 本地 FunASR → 文本交给 AI
- 📹 视频/📎 文件 → 下载保存 → 通知 AI
- 🔗 链接 → 提取元信息 → 交给 AI
6. 🤖 AI 代理生成回复
7. 📤 回复经 Markdown 转换后，自动分段发送回企业微信
8. 🖥️ 同时写入 Transcript + 广播到 Chat UI
### 📁 项目结构
```
openclaw-wechat/
├── index.js # 入口文件（重导出）
├── src/
│ └── index.js # 插件主逻辑（1400+ 行）
├── stt.py # 🎙️ 语音识别（远程 Qwen3-ASR + 本地 FunASR 降级）
├── asr_server.py # 🖥️ 远程 ASR 服务（FastAPI + Qwen3-ASR，部署到 GPU 服务器）
├── openclaw.plugin.json # OpenClaw 插件描述文件（新格式）
├── clawdbot.plugin.json # ClawdBot 插件描述文件（兼容旧版）
├── package.json # npm 包配置 (v0.3.7)
├── .env.example # 环境变量示例
├── skills/
│ └── wecom-notify/ # 📨 Claude Code WeCom 通知技能
│ ├── SKILL.md
│ └── scripts/
│ └── send_wecom.py
├── docs/
│ └── channels/
│ └── wecom.md # 渠道文档
├── CHANGELOG.md # 版本变更日志
└── LICENSE # MIT 许可证
```
### 📨 Claude Code WeCom 通知技能
本仓库还包含一个独立的 **Claude Code 技能**（`wecom-notify`），可以在 Claude Code 中直接发送企业微信消息。这是一个**独立工具**，不依赖 OpenClaw 插件，直接调用企业微信 API。
#### 安装技能
将 `skills/wecom-notify/` 目录复制到 `~/.claude/skills/` 即可：
```bash
cp -r skills/wecom-notify ~/.claude/skills/
```
#### 使用方式
在 Claude Code 中可以直接使用 `/wecom-notify` 命令，或让 AI 自动调用：
```bash
# 发送文本消息
python3 skills/wecom-notify/scripts/send_wecom.py "你好，这是一条测试消息"
# 指定接收人
python3 skills/wecom-notify/scripts/send_wecom.py "消息内容" --to UserName
# 发送图片
python3 skills/wecom-notify/scripts/send_wecom.py --image /path/to/photo.png
# 发送文件
python3 skills/wecom-notify/scripts/send_wecom.py --file /path/to/report.pdf
```
#### 特点
- 🔧 **零依赖**：仅使用 Python 标准库（`urllib.request`、`json`），无需 `pip install`
- 📄 自动从 `~/.openclaw/openclaw.json` 读取 WeCom 配置（复用 OpenClaw 的环境变量）
- 📝 支持文本（2048 字节限制）、图片（jpg/png/gif，≤2MB）、文件（任意格式，≤20MB）
- 🌐 支持 `WECOM_PROXY` 代理
### 📜 版本历史
查看 [CHANGELOG.md](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/CHANGELOG.md) 了解完整版本历史。
---
## 🔗 相关链接
- 🌐 [OpenClaw 官方网站](https://openclaw.ai)
- 📖 [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
- 🔐 [企业微信消息加解密](https://developer.work.weixin.qq.com/document/path/90968)
- 🍴 [上游项目：dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat)
- 🎙️ [FunASR SenseVoice](https://modelscope.cn/models/iic/SenseVoiceSmall)
## 📄 许可证
[MIT License](https://github.com/xueheng-li/openclaw-wechat/blob/HEAD/LICENSE)
## 🙏 致谢
- 🍴 原始项目：[dingxiang-me/OpenClaw-Wechat](https://github.com/dingxiang-me/OpenClaw-Wechat)，作者 **勾勾的数字生命** ([@dingxiang-me](https://github.com/dingxiang-me))
- 🤖 [OpenClaw](https://openclaw.ai)，由 Peter Steinberger 和 OpenClaw 社区开发
- 🎙️ [FunASR SenseVoice](https://github.com/modelscope/FunASR)，由阿里巴巴达摩院开发
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！