WeCom Notification OpenClaw

Name: WeCom Notification OpenClaw
Rating: 3.5 (1 reviews)
Author: FJLYLeoQiu

By FJLYLeoQiu 👁 12 views ▲ 0 votes

A WeCom notification channel plugin for OpenClaw.

GitHub

Configuration Example

{
  "channels": {
    "wecom-notification": {
      "corpId": "wwXXXXXXXXXXXXXXXX",
      "secret": "YOUR_APP_SECRET_HERE",
      "agentId": "1000000",
      "toUser": "@all",
      "enabled": true
    }
  },
  "plugins": {
    "entries": {
      "wecom-notification": {
        "enabled": true
      }
    }
  }
}

README

# WeCom Notification — OpenClaw 企业微信通知渠道插件

> **版本**: 2026.2.24  
> **类型**: OpenClaw 渠道扩展（Channel Plugin）  
> **用途**: 通过企业微信应用消息 API，向企业成员主动推送 AI 通知消息

---

## 📁 目录结构

```
extensions/wecom-notification/
├── index.ts                  # 插件入口，向 OpenClaw 注册渠道
├── package.json              # 包元数据
├── openclaw.plugin.json      # 插件清单（ID、渠道声明）
└── src/
    └── channel.ts            # 核心渠道实现（出站、配置、状态适配器）

src/wecom/                    # 共享核心模块（位于 OpenClaw 主仓库）
├── accounts.ts               # 配置读取与账户解析
└── send.ts                   # access_token 管理 + 消息发送 API
```

---

## 🏗️ 架构概述

```
OpenClaw Gateway
      │
      ├── [wecom-notification 插件]
      │         │
      │         ├── channel.ts ─── configSchema    ← UI 配置面板
      │         │             ├── config adapter   ← 读取账户
      │         │             ├── status adapter   ← 运行状态
      │         │             └── outbound adapter ← 发送逻辑
      │         │
      │         └── 调用 src/wecom/
      │                   ├── accounts.ts  → 从 openclaw.json 读取凭据
      │                   └── send.ts      → 调用企业微信 API
      │
      └── openclaw.json  (channels["wecom-notification"])
                ├── corpId
                ├── secret
                ├── agentId
                └── toUser
```

---

## ⚙️ 配置说明

### 在 openclaw.json 中手动配置

```json
{
  "channels": {
    "wecom-notification": {
      "corpId": "wwXXXXXXXXXXXXXXXX",
      "secret": "YOUR_APP_SECRET_HERE",
      "agentId": "1000000",
      "toUser": "@all",
      "enabled": true
    }
  },
  "plugins": {
    "entries": {
      "wecom-notification": {
        "enabled": true
      }
    }
  }
}
```

| 字段 | 说明 | 示例值 |
|------|------|--------|
| `corpId` | 企业 ID，在企业微信管理后台「我的企业」页面查看 | `wwxxxxxxxx` |
| `secret` | 应用 Secret，在「应用管理 → 应用详情」查看 | `evYwlGm...` |
| `agentId` | 应用 AgentID，在「应用管理 → 应用详情」查看 | `1000000` |
| `toUser` | 接收人；`@all` 表示全部可见成员，多人用 `\|` 分隔 | `zhangsan\|lisi` 或 `@all` |
| `enabled` | 是否启用此渠道 | `true` |

### 通过 UI 配置（推荐）

1. 打开 OpenClaw Gateway Dashboard → Channels
2. 找到 **WeCom Notification** 卡片
3. 填写 corpId、Secret、AgentID、接收用户
4. 点击 **Save** → **Reload**

---

## 🔑 企业微信后台设置

### 1. 创建自建应用

1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/apps)
2. 「应用管理」→「创建应用」
3. 记录 **AgentId** 和 **Secret**

### 2. IP 白名单（重要！）

企业微信应用消息发送需要将**服务器出口 IP** 加入白名单：

1. 应用详情 → 「企业可信IP」→ 「配置企业可信IP」或「IP 白名单」
2. 添加你的服务器 IP 地址

> ⚠️ **如果服务在云端（如 AWS/阿里云），则需添加实例的弹性公网 IP（EIP）。**
> 例如：本项目使用的 IP 为 `xx.xx.xx.xx`

### 3. 配置可见范围

确保「应用可见范围」包含你要接收消息的成员或部门。

---

## 📡 API 调用链路

```
1. 获取 access_token
   GET https://qyapi.weixin.qq.com/cgi-bin/gettoken
       ?corpid=xxx&corpsecret=xxx
   → { access_token, expires_in: 7200 }

2. 发送消息
   POST https://qyapi.weixin.qq.com/cgi-bin/message/send
        ?access_token=xxx
   Body: {
     "touser": "@all",
     "msgtype": "text",
     "agentid": 1000000,
     "text": { "content": "..." }
   }
   → { errcode: 0, msgid: "..." }
```

**access_token 缓存策略**：有效期 7200 秒，提前 300 秒自动刷新，按 `corpId:secret` 独立缓存。

---

## 🚀 使用方式

### 命令行发送

```bash
# 发送文本消息给全部成员
node openclaw.mjs message send \
  --channel wecom-notification \
  --target "@all" \
  --message "这是一条系统通知"

# 发送给指定成员
node openclaw.mjs message send \
  --channel wecom-notification \
  --target "zhangsan" \
  --message "你好，张三！"
```

### Agent 内部触发

在 OpenClaw 的 heartbeat prompt 或 agent 执行中，可通过工具调用直接发送：

```
openclaw.json → agents.defaults.heartbeat.prompt:
"执行完成后，请通过 WeCom Notification 发送摘要"
```

### 通过 Linkage（联动）配置

可将 `wecom-notification` 绑定为任意事件的通知出口，例如：
- 定时报告
- 监控告警
- AI 任务完成通知

---

## 🧩 支持的消息类型

| 类型 | 支持 | 说明 |
|------|------|------|
| 文本 (text) | ✅ | 最大 2048 字节 |
| Markdown | ✅ | 最大 4096 字节，部分客户端支持 |
| 图片 | ⚠️ 降级为文本 | 纯通知渠道，媒体类型降级 |
| 视频 | ⚠️ 降级为文本 | 同上 |
| 文件 | ⚠️ 降级为文本 | 同上 |

---

## 🔧 渠道特性

```
chatTypes:      ["direct"]     # 仅支持下行通知，不接收用户消息
media:          false          # 不处理媒体（纯文本通知）
threads:        false          # 不支持线程
reactions:      false          # 不支持 emoji 反应
nativeCommands: false          # 不支持原生命令（/slash）
deliveryMode:   "direct"       # 直接调用 API，不经过 WebSocket 网关
textChunkLimit: 4000           # 单条消息最大字符数
```

---

## 🗂️ 核心文件说明

### `extensions/wecom-notification/index.ts`

OpenClaw 插件入口。向 OpenClaw Plugin API 注册 `wecom-notification` 渠道。

### `extensions/wecom-notification/src/channel.ts`

渠道核心实现，包含三个适配器：

- **`config` 适配器**：读取账户列表、解析账户、判断是否配置完整（`isConfigured`）
- **`status` 适配器**：向 UI 汇报运行状态（`resolveAccountState`、`buildAccountSnapshot`）
- **`outbound` 适配器**：实际消息发送（`sendText`、`sendMedia`、`sendPayload`）

### `src/wecom/accounts.ts`

账户配置解析。读取优先级：
1. `channels["wecom-notification"]`（UI 保存的配置）
2. `channels.wecom`（向后兼容，旧机器人插件遗留）

### `src/wecom/send.ts`

底层 HTTP 通信：
- `getAccessToken()` — 获取并缓存企业微信 access_token
- `sendMessageWeCom()` — 发送文本消息
- `sendMarkdownWeCom()` — 发送 Markdown 消息

---

## 🐛 常见问题排查

### Q: 发送失败 `errcode=60020`（不合法的访问来源）

**A**: IP 白名单未配置。请将服务器出口 IP 添加到企业微信「应用可信 IP」。

### Q: 发送失败 `errcode=40013`（不合法的 corpid）

**A**: `corpId` 填写错误。注意区分大小写，格式为 `ww` + 16位字符。

### Q: 发送失败 `errcode=40001`（Secret 错误）

**A**: `secret` 拷贝不完整，请重新从管理后台复制。

### Q: `Configured: No`（Channel 面板显示未配置）

**A**: `corpId`、`secret`、`agentId` 三个字段缺一不可。点击 Channel 卡片展开配置表单，填写后 Save → Reload。

### Q: `Running: No`

**A**: 纯通知渠道（无 WebSocket 长连接）。只要 `Configured: Yes`，渠道即可正常发送，`Running` 状态指示器仅适用于需要长连接的双向渠道（如 WeCom 机器人）。

---

## 📋 与 Enterprise WeChat (wecom) 机器人的区别

| 特性 | WeCom Notification (本插件) | Enterprise WeChat (wecom 机器人) |
|------|---------------------------|--------------------------------|
| 方向 | 仅下行（OpenClaw → 成员） | 双向（支持接收成员消息） |
| WebSocket | 不需要 | 需要（企业微信回调服务器） |
| IP 白名单 | 需要（消息发送 API） | 需要（更多回调白名单） |
| 动态 Agent | 不支持 | 支持（每个用户独立会话） |
| 适用场景 | 系统通知、定时报告、告警 | AI 对话助手、命令执行 |

---

## 📅 变更历史

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-02-24 | 1.0.0 | 初始版本：基础出站发送、access_token 缓存 |
| 2026-02-24 | 1.1.0 | 添加 configSchema（修复 UI 配置面板）、status 适配器 |
| 2026-02-24 | 1.2.0 | 修复命名空间优先级、agentId schema type、禁用旧 wecom 插件 |

---

## 📚 参考文档

- [企业微信开发者文档 — 获取 access_token](https://developer.work.weixin.qq.com/document/path/91039)
- [企业微信开发者文档 — 发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)
- [企业微信管理后台](https://work.weixin.qq.com/wework_admin/)
- [OpenClaw Plugin SDK 文档](https://docs.openclaw.ai/plugin-sdk)

channels