openclaw-plugin-wecom: a community WeCom channel layer for OpenClaw bots

A community layer on the official WeCom plugin skeleton

@sunnoy/wecom is positioned as a community enhancement plugin for the WeCom channel of OpenClaw, and it is built on the WebSocket long connection skeleton of the official @wecom/wecom-openclaw-plugin. The underlying SDK is @wecom/aibot-node-sdk, the Node.js SDK for WeCom AI robots. The package itself is plain JavaScript, published to npm as @sunnoy/wecom with a channel id of wecom and aliases wecom and wework.

The project is explicit about the division of labour. The official plugin already handles the WebSocket long connection with streaming replies, private and group chat reception, DM admission policies of pairing, open, allowlist or disabled, group admission policies of open, allowlist or disabled, per group sender allowlists, the thinking placeholder, and an interactive CLI configuration wizard. Every one of those is listed as present in both plugins. What this package adds is the row of features the official plugin does not have, and the comparison table in the documentation is long.

That framing is the honest way to evaluate the project. It is a layer of additional channels, routing and safety controls on a working base, not a replacement for it. If you only need a bot that answers in a group chat, the official plugin is the shorter path.

The licensing is permissive. The package manifest carries the ISC licence, and the plugin distribution is listed on npm.

Version 2.0 removed the public HTTP callback from the main path

The most consequential change in the project is structural. From version 2.0 the plugin relies entirely on the WeCom AI robot WebSocket long connection mode. An installation that previously used the HTTP callback arrangement, with a Token, an EncodingAESKey and a callback URL, has to be migrated: the robot must be switched to long connection mode in the WeCom admin console, a new BotId and Secret must be recorded, the old token, encodingAesKey and callback URL settings must be removed, and the Gateway must be restarted.

The configuration file that changes is ~/.openclaw/openclaw.json, where channels.wecom.botId and channels.wecom.secret are set. The migration sequence in the documentation is:

openclaw plugins install @sunnoy/wecom

followed by a Gateway restart so the plugin connects out to the WeCom WebSocket. After the move, no publicly reachable HTTP callback address is needed, which removes a whole class of deployment friction: the machine running OpenClaw only has to make outbound connections.

Those outbound destinations are listed explicitly. The machine must be able to reach wss://openws.work.weixin.qq.com, and https://qyapi.weixin.qq.com when the Agent API or webhook features are enabled. The documentation states plainly that the bot main path does not require WeCom to reach your HTTP callback address. In a corporate network with an egress proxy, that is the difference between a deployment that works and one that never connects.

The self-built application callback runs beside the WebSocket channel

Version 2.1 added a second inbound path, so the plugin is not strictly WebSocket only. A WeCom self-built application can deliver messages through an HTTP receive callback, enabled by setting callback.token, callback.encodingAESKey and callback.path under channels.wecom.agent. The documentation states that it runs in parallel with the WebSocket channel and that the two do not interfere with each other.

The same agent block is also the outbound path. It carries corpId, corpSecret and agentId, and it is what lets a self-built application push text, images and files proactively rather than only replying. Replies sent through the callback inbound path default to markdown format.

The Agent API is what makes several other features possible. The pending reply retry feature resends undelivered replies through the Agent API after a WebSocket disconnection, which turns a dropped connection from a silent loss into a delayed delivery. Department and tag targeting uses party: and tag: addressing, and named webhook mappings under channels.wecom.webhooks can post to group robots, with markdown, image and file payloads. A webhook value may be a full URL or just the group robot key.

The outbound side is also where the network configuration lives, with network.egressProxyUrl for a proxy and network.apiBaseUrl, or the WECOM_API_BASE_URL environment variable, to point at a different API base address.

Dynamic agents and workspaces isolate one chat group from another

The feature set with the most operational weight is dynamic agent routing. With dynamicAgents enabled, a session and a workspace are isolated per user or per group automatically, so two conversations do not share context or files. A related setting, dm.createAgentOnFirstMessage, creates the agent on the first private message. The workspace template feature copies guiding files such as AGENTS.md into a new agent, and workspaceTemplateExtraFiles names further files or directories such as scripts/ or requirements.txt to copy alongside.

Access control is layered on top of that. The commands block restricts which slash commands ordinary users may run, with an allowlist such as /new, /compact, /help and /status, and an adminBypass option that lets administrators run beyond the allowlist when combined with dynamic agent routing. The bindings routing feature pins a particular WeCom account to a named agent, which is how a team gives a specific bot a specific persona. Group chat behaviour is controlled separately, with groupChat.requireMention and mentionPatterns.

Two details are easy to miss and worth reading twice. The sendThinkingMessage option only controls the WeCom thinking bubble and placeholder message; actual streaming reasoning content also requires the current OpenClaw session to have reasoningLevel set to stream. And the welcomeMessage option, when non empty, always uses that fixed string, while welcomeMessagesFile loads a list of greetings from a file whose relative path is resolved against the OpenClaw state directory, either ~/.openclaw or OPENCLAW_STATE_DIR.

Quota awareness, retry and the 800ms reasoning throttle

A WeCom bot has to respect the platform's message quotas, and this plugin tracks them. The runtime quota awareness feature covers both the passive reply window of 24 hours and the quota for proactive sending, with alerting when the budget is in danger. For a bot that replies in a chat and also pushes scheduled announcements, that is the difference between a service that degrades gracefully and one that silently stops delivering.

Reliability features cover the other half. Message deduplication uses reqId and msgId together so a repeated message is not processed twice, which matters when both the WebSocket channel and the callback channel can deliver the same event. Pending reply retry resends undelivered replies through the Agent API after a disconnect. The reasoning streaming throttle runs at 800ms to keep the SDK queue from overflowing, and the think tag normaliser accepts variants such as <thinking> and <thought> in addition to the standard placeholder, so a model that emits a different variant does not leak the tag into the chat. The reply media command parser extracts MEDIA: and FILE: paths from the model output, and inbound mixed messages are split into text and image, inbound voice content is extracted, and quoted message context is passed through.

None of this is exotic, and all of it is the kind of detail that decides whether a bot survives contact with real users.

Installing the plugin and checking it locally

Prerequisites are specific. OpenClaw 2026.3.23-2 or newer must be installed, you need WeCom admin console rights to create an AI robot or a self-built application, the robot must already be switched to long connection mode, and the machine running OpenClaw must be able to reach the two outbound endpoints.

The install itself is a single command:

openclaw plugins install @sunnoy/wecom

From version 3.0 the plugin only supports OpenClaw 2026.3.23-2 and later, and older OpenClaw releases should stay on the 2.x line of this plugin. If you previously used the official plugin, the documentation says to uninstall it before installing this one, because the channels.wecom configuration fields are compatible and no configuration rewrite is needed.

The package manifest gives the rest of the shape. The plugin is an ES module whose entry point is index.js, it declares openclaw as a peer dependency at ^2026.3.23-2, and it depends on @wecom/aibot-node-sdk, file-type and pinyin-pro, with undici as an optional dependency. The channel manifest registers the extension, sets the label Enterprise WeChat, and points the install flow at the npm spec @sunnoy/wecom.

A minimal working configuration looks like this:

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aibxxxxxxxxxxxxxxxx",
      "secret": "xxxxxxxxxxxxxxxx",
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/compact", "/help", "/status"]
      }

The test suite runs with the standard Node test runner, and the manifest maps the test script to the unit test script:

npm test

which executes node --test tests/*.test.js. The repository also ships a tests directory, a skills directory, a CHANGELOG and a CONTRIBUTING file.

What the WeCom backend will still refuse to give you

The plugin cannot grant capabilities the WeCom side does not open. The documentation is blunt about this: enterprise scale and bot permissions are still controlled by the WeCom backend, and in large enterprises the common case is that only the doc class of MCP capabilities is exposed. The MCP alignment notes state that wecom_mcp follows the negotiated version of the official plugin and the aibot SDK, and there is a separate deployment constraint that limits MCP skills to doc only, so that contact, todo or msg capabilities are not attempted when they are not enabled.

That is the main reason this plugin can disappoint. A feature that looks complete in the configuration, such as department targeting or proactive sending, still fails if the organisation has not granted the underlying permission, and the failure appears as a WeCom API error rather than as a configuration problem in OpenClaw.

The other limits are structural. The plugin depends on a specific OpenClaw version line, and version 3.0 dropped support for anything older, so upgrading OpenClaw is not optional and upgrading it may force a plugin upgrade too. The repository has no independent documentation site of its own; the guidance lives in the README and the docs folder.

On maintenance, the picture is mixed and worth stating as it is. The repository is not archived, the package version is 3.4.0, and the release notes for that version describe disabling the OpenClaw message tool on WeCom WebSocket dispatch. The last push was on 2026-05-25, and earlier releases v3.2.0 and v3.1.0 both landed on 2026-04-27. The ISC licence is permissive and adds no obligations to a team embedding the plugin, while the WeCom SDK and the file-type and pinyin-pro dependencies carry their own terms.

Editorial conclusion

Adopt @sunnoy/wecom if you already run OpenClaw, your bot has to serve a real WeCom organisation, and you need per user isolation, command allowlists and outbound sending through the Agent API. Do not adopt it if your WeCom tenant exposes only the doc class of MCP capabilities or if you have not switched the robot to long connection mode, since the plugin requires that mode and OpenClaw 2026.3.23-2 or newer. Verify first that your machine can reach wss://openws.work.weixin.qq.com and https://qyapi.weixin.qq.com, then run npm test before pointing the channel at real users.

Frequently asked questions

Official sources

1. License: ISC
2. Project website
3. README
4. Releases
5. sunnoy/openclaw-plugin-wecom on GitHub