177 lines
4.4 KiB
Markdown
177 lines
4.4 KiB
Markdown
# 🤖 WeCom OpenClaw Plugin
|
|
|
|
**WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.
|
|
|
|
> A bot plugin powered by WeCom AI Bot WebSocket persistent connections. Supports direct messages & group chats, streaming replies, and proactive messaging.
|
|
|
|
---
|
|
|
|
📖 [WeCom AI Bot Official Documentation](https://open.work.weixin.qq.com/help?doc_id=21657)
|
|
|
|
|
|
## ✨ Features
|
|
|
|
- 🔗 WebSocket persistent connection for stable communication
|
|
- 💬 Supports both direct messages (DM) and group chat
|
|
- 📤 Proactive messaging to specific users or groups
|
|
- 🖼️ Receives and processes image and file messages with automatic downloading
|
|
- ⏳ Streaming replies with "thinking" placeholder messages
|
|
- 📝 Markdown formatting support for replies
|
|
- 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
|
|
- ⚡ Auto heartbeat keep-alive and reconnection (up to 100 reconnect attempts)
|
|
- 🧙 Interactive CLI setup wizard
|
|
|
|
---
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Requirements
|
|
|
|
- OpenClaw `>= 2026.2.13`
|
|
|
|
### Installation
|
|
|
|
```shell
|
|
openclaw plugins install @wecom/wecom-openclaw-plugin
|
|
```
|
|
|
|
### Configuration
|
|
|
|
#### Option 1: Interactive Setup
|
|
|
|
```shell
|
|
openclaw channels add
|
|
```
|
|
|
|
Follow the prompts to enter your WeCom bot's **Bot ID** and **Secret**.
|
|
|
|
#### Option 2: CLI Quick Setup
|
|
|
|
```shell
|
|
openclaw config set channels.wecom.botId <YOUR_BOT_ID>
|
|
openclaw config set channels.wecom.secret <YOUR_BOT_SECRET>
|
|
openclaw config set channels.wecom.enabled true
|
|
openclaw gateway restart
|
|
```
|
|
|
|
### Configuration Reference
|
|
|
|
| Config Path | Description | Options | Default |
|
|
|---|---|---|---|
|
|
| `channels.wecom.botId` | WeCom bot ID | — | — |
|
|
| `channels.wecom.secret` | WeCom bot secret | — | — |
|
|
| `channels.wecom.enabled` | Enable the channel | `true` / `false` | `false` |
|
|
| `channels.wecom.websocketUrl` | WebSocket endpoint | — | `wss://openws.work.weixin.qq.com` |
|
|
| `channels.wecom.dmPolicy` | DM access policy | `pairing` / `open` / `allowlist` / `disabled` | `open` |
|
|
| `channels.wecom.allowFrom` | DM allowlist (user IDs) | — | `[]` |
|
|
| `channels.wecom.groupPolicy` | Group chat access policy | `open` / `allowlist` / `disabled` | `open` |
|
|
| `channels.wecom.groupAllowFrom` | Group allowlist (group IDs) | — | `[]` |
|
|
| `channels.wecom.sendThinkingMessage` | Send "thinking" placeholder | `true` / `false` | `true` |
|
|
|
|
---
|
|
|
|
## 🔒 Access Control
|
|
|
|
### DM (Direct Message) Access
|
|
|
|
**Default**: `dmPolicy: "open"` — all users can send direct messages without approval.
|
|
|
|
#### Approve Pairing
|
|
|
|
```shell
|
|
openclaw pairing list wecom # View pending pairing requests
|
|
openclaw pairing approve wecom <CODE> # Approve a pairing request
|
|
```
|
|
|
|
#### Allowlist Mode
|
|
|
|
Configure allowed user IDs via `channels.wecom.allowFrom`:
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"wecom": {
|
|
"dmPolicy": "allowlist",
|
|
"allowFrom": ["user_id_1", "user_id_2"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Open Mode
|
|
|
|
Set `dmPolicy: "open"` to allow all users to send direct messages without approval.
|
|
|
|
#### Disabled Mode
|
|
|
|
Set `dmPolicy: "disabled"` to completely block all direct messages.
|
|
|
|
### Group Access
|
|
|
|
#### Group Policy (`channels.wecom.groupPolicy`)
|
|
|
|
- `"open"` — Allow messages from all groups (default)
|
|
- `"allowlist"` — Only allow groups listed in `groupAllowFrom`
|
|
- `"disabled"` — Disable all group messages
|
|
|
|
### Group Configuration Examples
|
|
|
|
#### Allow All Groups (Default Behavior)
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"wecom": {
|
|
"groupPolicy": "open"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Allow Only Specific Groups
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"wecom": {
|
|
"groupPolicy": "allowlist",
|
|
"groupAllowFrom": ["group_id_1", "group_id_2"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Allow Only Specific Senders Within a Group (Sender Allowlist)
|
|
|
|
In addition to the group allowlist, you can restrict which members within a group are allowed to interact with the bot. Only messages from users listed in `groups.<chatId>.allowFrom` will be processed; messages from other members will be silently ignored. This is a sender-level allowlist that applies to **all messages**.
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"wecom": {
|
|
"groupPolicy": "allowlist",
|
|
"groupAllowFrom": ["group_id_1"],
|
|
"groups": {
|
|
"group_id_1": {
|
|
"allowFrom": ["user_id_1", "user_id_2"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Update
|
|
|
|
```shell
|
|
openclaw plugins update wecom-openclaw-plugin
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
MIT
|