💡 快速上手指引 & 交流群

📖 点击查看完整接入指引文档 — 包含配置步骤、产品介绍、常见问题解答等。

💬 扫码加入企业微信交流群：

特别说明

*2026.3.22 版本 OpenClaw 兼容说明*

如果你的 OpenClaw 是 2026.3.22 及以上的版本，请升级插件到 2026.3.24 及以上版本。

如果你的 OpenClaw 是 2026.3.22 以下的版本，请保持插件版本在 2026.3.20 版本。

你可以使用以下命令快速安装： npx -y @wecom/wecom-openclaw-cli install --force

🤖 WeCom OpenClaw Plugin

WeCom channel plugin for OpenClaw — by the Tencent WeCom team.

A channel plugin powered by WeCom. Supports Bot mode (WebSocket long-polling or HTTP webhook with JSON callbacks) and Agent mode (HTTP webhook with XML encrypted callbacks). Direct messages, group chats, streaming replies, and proactive messaging.

---

📖 WeCom AI Bot Official Documentation

✨ Features

• 🔗 Dual-mode: Bot (WebSocket / Webhook) and Agent (HTTP webhook) can run independently or together
• 💬 Supports both direct messages (DM) and group chat
• 📤 Proactive messaging to specific users, groups, departments, or tags
• 🖼️ Receives and processes image, voice, video, file, and mixed (图文混排) messages with automatic downloading
• 🗣️ Voice-to-text: automatically extracts transcribed text from voice messages
• 💬 Quote message support: processes quoted text, image, voice, and file messages
• ⏳ Streaming replies with "thinking" placeholder messages (Bot mode)
• 🔐 Agent mode: AES-256-CBC encrypted XML callbacks with SHA1 signature verification
• 📝 Markdown formatting support for replies
• 🃏 Template card messages (text_notice, news_notice, button_interaction, vote_interaction, multiple_interaction) with event callback handling
• 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
• 🔑 Command authorization: per-account command permission control with access group support
• 👥 Multi-account support: run multiple WeCom accounts with independent bot/agent configs
• 🧩 MCP tool integration (wecom_mcp) with interceptor pipeline (biz-error, media, smartpage-create, smartpage-export)
• 🎯 15 built-in Skills: contact lookup, doc management, todo, meeting, schedule, messaging, smartsheet, template cards, and more
• 🔀 Dynamic Agent routing: auto-create isolated agents per user/group
• 📁 Local file sending with configurable media path allowlist (mediaLocalRoots)
• 📊 Smart media size limits with auto-downgrade (image 10MB → file, video 10MB → file, voice 2MB/AMR-only → file, max 20MB)
• 🔄 Bot-first, Agent-fallback outbound delivery: auto fallback to Agent HTTP API when Bot WS is unavailable
• ⚡ Auto heartbeat keep-alive and reconnection (up to 10 reconnect attempts, 5 auth failure retries)
• 🛡️ Anti-kick protection: suppresses auto-restart on server-side disconnection to prevent mutual kicking loops
• 🧙 Interactive CLI setup wizard

---

🚀 Getting Started

Requirements

• OpenClaw >= 2026.3.28

Quick Install

Use the CLI tool to automatically install the plugin and complete bot configuration in one step:

# Automatically install the channel plugin and quickly complete configuration; also works for updates
npx -y @wecom/wecom-openclaw-cli install

More Options

# If installation fails, try force install
npx -y @wecom/wecom-openclaw-cli install --force

# Use --help to learn more about the tool
npx -y @wecom/wecom-openclaw-cli --help

Manual Install

openclaw plugins install @wecom/wecom-openclaw-plugin

Configuration

Option 1: Interactive Setup

openclaw channels add

Follow the prompts to enter your WeCom bot's Bot ID and Secret.

Option 2: CLI Quick Setup

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

Mode Overview

The plugin supports two connection modes that can be used independently or together:

Mode	Connection	Message Format	Use Case
Bot (智能体)	WebSocket (default) or HTTP webhook	JSON	Quick setup, streaming replies
Agent (自建应用)	HTTP webhook callbacks	XML	Enterprise apps, API-driven messaging

Note: Bot mode supports two connection methods via connectionMode: - websocket (default) — WebSocket long-polling, requires botId + secret - webhook — HTTP callback, requires token + encodingAESKey

Bot Mode Configuration

Core Settings

Config Path	Description	Options	Default
channels.wecom.enabled	Enable the channel	true / false	false
channels.wecom.connectionMode	Bot connection mode	websocket / webhook	websocket
channels.wecom.name	Account display name	—	企业微信

WebSocket Mode (default)

Config Path	Description	Options	Default
channels.wecom.botId	WeCom bot ID	—	—
channels.wecom.secret	WeCom bot secret	—	—
channels.wecom.websocketUrl	WebSocket endpoint	—	wss://openws.work.weixin.qq.com
channels.wecom.sendThinkingMessage	Send "thinking" placeholder	true / false	true

Webhook Mode (connectionMode: "webhook")

Config Path	Description	Options	Default
channels.wecom.token	Webhook verification token	—	—
channels.wecom.encodingAESKey	AES encryption key (43 chars Base64)	—	—
channels.wecom.receiveId	Receiver ID (for decryption verification)	—	—
channels.wecom.welcomeText	Welcome message on enter_chat event	—	—
channels.wecom.streamPlaceholderContent	Stream placeholder content	—	—

Access Control

Config Path	Description	Options	Default
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.groups	Per-group config (e.g. sender allowlist)	—	{}

Media Settings

Config Path	Description	Default
channels.wecom.mediaLocalRoots	Extra local paths allowed for media sending (supports ~)	[]
channels.wecom.media.maxBytes	Max media file size in bytes	20971520 (20MB)
channels.wecom.media.tempDir	Temp directory for media processing	—
channels.wecom.media.retentionHours	Media file retention hours	—
channels.wecom.media.cleanupOnStart	Clean temp media on startup	—

Media Size Limits & Auto-Downgrade:

Media Type	Max Size	Downgrade Behavior
Image	10 MB	Exceeds → sent as file
Video	10 MB	Exceeds → sent as file
Voice	2 MB (AMR only)	Non-AMR format or exceeds → sent as file
File	20 MB	Exceeds → rejected (cannot send)

Network Settings

Config Path	Description	Default
channels.wecom.network.timeoutMs	HTTP request timeout (ms)	—
channels.wecom.network.retries	Number of retries	—
channels.wecom.network.retryDelayMs	Delay between retries (ms)	—
channels.wecom.network.egressProxyUrl	Egress proxy URL for trusted IP scenarios	—

Egress Proxy Priority: channels.wecom.network.egressProxyUrl > OPENCLAW_WECOM_EGRESS_PROXY_URL > WECOM_EGRESS_PROXY_URL > HTTPS_PROXY > ALL_PROXY > HTTP_PROXY

Agent Mode Configuration

Agent mode uses HTTP webhook callbacks with XML encrypted messages. You need to configure the callback URL in the WeCom admin console under "API Receive" settings.

Prerequisites

1. Create a self-built app in WeCom Admin Console
2. Note down the CorpID, CorpSecret (from app settings), and AgentId
3. In the app settings, go to "API Receive" (API接收):
4. Note down the Token and EncodingAESKey (auto-generated or custom)
5. Do NOT click save yet — WeCom will verify the callback URL immediately when you save

Setup Steps

Important: You must configure the Gateway before saving the callback URL in WeCom admin console. WeCom sends a verification request (GET with echostr) immediately when you save, and the Gateway needs the token and encodingAESKey to decrypt and respond correctly.

Step 1: Configure Gateway

openclaw config set channels.wecom.agent.corpId <YOUR_CORP_ID>
openclaw config set channels.wecom.agent.corpSecret <YOUR_CORP_SECRET>
openclaw config set channels.wecom.agent.agentId <YOUR_AGENT_ID>
openclaw config set channels.wecom.agent.token <YOUR_CALLBACK_TOKEN>
openclaw config set channels.wecom.agent.encodingAESKey <YOUR_ENCODING_AES_KEY>
openclaw config set channels.wecom.enabled true
openclaw gateway restart

Step 2: Save callback URL in WeCom admin console

Go back to the "API Receive" settings and enter the callback URL: - URL: https://<your-gateway-host>/plugins/wecom/agent/<accountId> (e.g. /plugins/wecom/agent/default); single-account mode can also use /plugins/wecom/agent

Now click save — the verification should pass.

JSON Configuration

{
  "channels": {
    "wecom": {
      "enabled": true,
      "agent": {
        "corpId": "ww1234567890abcdef",
        "corpSecret": "your-corp-secret",
        "agentId": 1000002,
        "token": "your-callback-token",
        "encodingAESKey": "your-encoding-aes-key-43-chars"
      }
    }
  }
}

Agent Config Reference

Config Path	Description	Required
channels.wecom.agent.corpId	Enterprise Corp ID	Yes
channels.wecom.agent.corpSecret	App secret	Yes
channels.wecom.agent.agentId	App agent ID	No (needed for proactive messaging)
channels.wecom.agent.token	Callback verification token	Yes
channels.wecom.agent.encodingAESKey	Callback encryption key (43 chars)	Yes
channels.wecom.agent.welcomeText	Welcome message	No
channels.wecom.agent.dmPolicy	DM access policy (overrides top-level)	No
channels.wecom.agent.allowFrom	DM allowlist (overrides top-level)	No

Webhook Paths

Agent Mode:

Path	Description
/plugins/wecom/agent/<accountId>	推荐路径（例如 /plugins/wecom/agent/default）
/plugins/wecom/agent/default	多账号模式下自动路由到默认账号（即使默认账号 ID 不是 default）
/plugins/wecom/agent	兼容路径（单账号 / 多账号签名匹配）
/wecom/agent	Legacy 兼容路径

Bot Webhook Mode (connectionMode: "webhook"):

Path	Description
/plugins/wecom/bot	Recommended path (single account)
/plugins/wecom/bot/<accountId>	Multi-account path
/wecom/bot	Legacy compatible path
/wecom	Legacy compatible path

Outbound Delivery (Bot WS → Agent HTTP Fallback)

The plugin uses a Bot-first, Agent-fallback strategy for outbound message delivery:

1. Bot WebSocket available → send via WS (supports markdown, streaming)
2. Bot WS unavailable → automatically fallback to Agent HTTP API (cgi-bin/message/send)

This means: - Agent-only accounts (no Bot configured) can still send proactive messages, cron deliveries, and broadcasts - Target formats like party:1, tag:Ops, user:zhangsan are fully supported in both paths - Media fallback: when Bot WS is unavailable, media files are downloaded, uploaded to WeCom via Agent API, then sent; if upload fails, falls back to text + URL - No manual switching needed — the plugin handles fallback transparently

Using Both Modes Together

Bot and Agent can run simultaneously on the same account. Bot handles WebSocket streaming; Agent handles HTTP webhook callbacks with API-driven replies.

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "your-bot-id",
      "secret": "your-bot-secret",
      "agent": {
        "corpId": "ww1234567890abcdef",
        "corpSecret": "your-corp-secret",
        "agentId": 1000002,
        "token": "your-callback-token",
        "encodingAESKey": "your-encoding-aes-key-43-chars"
      }
    }
  }
}

Multi-Account Configuration

Use accounts to configure multiple WeCom accounts, each with optional bot and/or agent sub-configs. Account-level fields override top-level fields of the same name.

{
  "channels": {
    "wecom": {
      "enabled": true,
      "defaultAccount": "main",
      "dmPolicy": "open",
      "accounts": {
        "main": {
          "botId": "bot-id-1",
          "secret": "secret-1",
          "agent": {
            "corpId": "ww1234567890abcdef",
            "corpSecret": "secret-a",
            "agentId": 1000002,
            "token": "token-a",
            "encodingAESKey": "aes-key-a"
          }
        },
        "support": {
          "dmPolicy": "allowlist",
          "allowFrom": ["admin1"],
          "agent": {
            "corpId": "ww1234567890abcdef",
            "corpSecret": "secret-b",
            "agentId": 1000003,
            "token": "token-b",
            "encodingAESKey": "aes-key-b"
          }
        }
      }
    }
  }
}

Note: In multi-account mode, accounts without explicit bindings will not fall back to the default agent. Configure bindings for each account: json { "bindings": [ { "agentId": "your-agent", "match": { "channel": "wecom", "accountId": "main" } } ] }

Dynamic Agent Configuration

Dynamic Agent routing automatically creates isolated agents per user or group, enabling session isolation.

```j