💡 快速上手指引 & 交流群

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

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

特别说明

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接收):
   • Note down the Token and EncodingAESKey (auto-generated or custom)
   • 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:

{
  "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.

{
  "channels": {
    "wecom": {
      "dynamicAgents": {
        "enabled": true,
        "dmCreateAgent": true,
        "groupEnabled": true,
        "adminUsers": ["admin_user_id"]
      }
    }
  }
}

| Config Path | Description | Default | |---|---|---| | channels.wecom.dynamicAgents.enabled | Enable dynamic agent routing | false | | channels.wecom.dynamicAgents.dmCreateAgent | Create isolated agent per DM user | true | | channels.wecom.dynamicAgents.groupEnabled | Enable dynamic agent for group chats | true | | channels.wecom.dynamicAgents.adminUsers | Admin users (bypass dynamic routing, use main agent) | [] |

🔒 Access Control

DM (Direct Message) Access

Default: dmPolicy: "open" — all users can send direct messages without approval.

Approve Pairing

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:

{
  "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)

{
  "channels": {
    "wecom": {
      "groupPolicy": "open"
    }
  }
}

Allow Only Specific Groups

{
  "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.

{
  "channels": {
    "wecom": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["group_id_1"],
      "groups": {
        "group_id_1": {
          "allowFrom": ["user_id_1", "user_id_2"]
        }
      }
    }
  }
}

⏰ Cronjob (Scheduled Tasks)

The plugin supports scheduled message delivery via OpenClaw's built-in Cron service. Cron jobs run through the Agent outbound channel, so Agent mode must be configured.

Target Formats

The delivery.to field supports the following target formats:

| Format | Target | Example | |--------|--------|--------| | party:<id> | Department (all members) | party:1 (root dept = all employees) | | dept:<id> | Department (alias for party) | dept:5 | | tag:<id> | Tag group | tag:Ops | | user:<id> | Specific user | user:zhangsan | | group:<id> | External group chat | group:wr123abc | | chat:<id> | Group chat (alias for group) | chat:wc456def | | Pure number | Auto-detected as department | 1 → party:1 | | wr... / wc... | Auto-detected as group chat | wr123 → chatid | | Other string | Auto-detected as user | zhangsan → touser |

Namespace prefixes (wecom:, qywx:, wework:, wechatwork:, wecom-agent:) are automatically stripped before parsing.

Method 1: CLI (Recommended — takes effect immediately)

openclaw cron add \
  --name "daily-report" \
  --agent main \
  --cron "0 9 * * 1-5" \
  --tz "Asia/Shanghai" \
  --message "Good morning! Here is your daily briefing." \
  --announce \
  --channel wecom \
  --to "party:1"

Note: --announce enables delivery mode (broadcasts the AI response to the target chat). Use --no-deliver to keep output internal. The deprecated --deliver flag is an alias for --announce.

Common CLI commands:

openclaw cron list              # List all cron jobs
openclaw cron show <id>         # Show job details
openclaw cron enable <id>       # Enable a job
openclaw cron disable <id>      # Disable a job
openclaw cron remove <id>       # Remove a job
openclaw cron run <id>          # Manually trigger a job
openclaw cron runs --id <id>    # View run history
openclaw cron edit <id> --message "New prompt"  # Edit a job

Method 2: Edit jobs.json (requires gateway restart)

File path: ~/.openclaw/cron/jobs.json

{
  "version": 1,
  "jobs": [
    {
      "id": "daily-report",
      "name": "Daily Report",
      "agentId": "main",
      "enabled": true,
      "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Shanghai" },
      "sessionTarget": "isolated",
      "wakeMode": "now",
      "payload": {
        "kind": "agentTurn",
        "message": "Generate today's briefing and send it."
      },
      "delivery": {
        "mode": "announce",
        "channel": "wecom",
        "to": "party:1",
        "accountId": "main"
      },
      "state": {}
    }
  ]
}

After editing, restart the gateway:

openclaw gateway restart

Method 3: Create via chat (takes effect immediately)

You can ask the AI agent directly in a WeCom conversation:

"Create a scheduled task: send a daily briefing to the entire company at 9am every weekday"

The agent will call the Cron API to create the job — no restart needed.

Notes

• Cron jobs use the Agent outbound path — Agent mode (corpId / corpSecret / agentId) must be configured.
• The server IP must be in the WeCom trusted IP allowlist, or configure egressProxyUrl for a fixed egress proxy.
• Jobs created via CLI or chat API take effect immediately. Manual edits to jobs.json require openclaw gateway restart.
• For multi-account setups, set delivery.accountId to the target account (e.g. "main", "support").

📦 Update

openclaw plugins update wecom-openclaw-plugin

📄 License

MIT