{"_id":"@brycehuang/wecom-openclaw-plugin","_rev":"4-f28d2c16782a97bd43f55b60470d31e4","name":"@brycehuang/wecom-openclaw-plugin","dist-tags":{"latest":"2026.4.30"},"versions":{"2026.4.22":{"name":"@brycehuang/wecom-openclaw-plugin","version":"2026.4.22","keywords":["wecom","openclaw","wecom-openclaw-plugin"],"author":"","license":"MIT","_id":"@brycehuang/wecom-openclaw-plugin@2026.4.22","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"homepage":"https://github.com/WecomTeam/wecom-openclaw-plugin#readme","bugs":{"url":"https://github.com/WecomTeam/wecom-openclaw-plugin/issues"},"dist":{"shasum":"ec7e55e2dc345502132d516a67e0bb59bb33d165","tarball":"https://registry.npmjs.org/@brycehuang/wecom-openclaw-plugin/-/wecom-openclaw-plugin-2026.4.22.tgz","fileCount":168,"integrity":"sha512-flRrgNgSM3os52KaA//8LwKRL5XMZL5YISxR5/MSTkU+393vkRMtwqCG7hzIWkH/DGKLtCrpT1zyzKcP/TRY1w==","signatures":[{"sig":"MEUCIQDw+LSg9Oe9flaJi8P7d2M0vNoYfUyJ0d6PBQaqkOxx6wIgCRmZQo4bgRrXJTaMhzUy/MzENhheqMnO+vrHP1vp8jw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":833573},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c507c0b2557bd0f4e825fabd99d3eb5dc994856b","scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist","release":"node scripts/publish-all.mjs","prebuild":"npm run clean","release:dry":"node scripts/publish-all.mjs --dry-run","deploy:local":"bash scripts/dev-deploy.sh"},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"openclaw":{"channel":{"id":"wecom","blurb":"企业微信机器人接入插件","label":"企业微信","order":80,"docsPath":"/channels/wecom","docsLabel":"wecom-openclaw-plugin","selectionLabel":"企业微信 (WeCom)","quickstartAllowFrom":true},"install":{"npmSpec":"@brycehuang/wecom-openclaw-plugin","localPath":"extensions/wecom-openclaw-plugin","defaultChoice":"npm"},"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/WecomTeam/wecom-openclaw-plugin.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw WeCom (企业微信) channel plugin (official by Tencent WeCom team)","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^4.3.6","undici":"^7.24.6","file-type":"^21.3.0","fast-xml-parser":"^5.5.9","@brycehuang/aibot-node-sdk":"^1.0.9"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.1","openclaw":">=2026.3.28","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/wecom-openclaw-plugin_2026.4.22_1777374240814_0.1046004673470966","host":"s3://npm-registry-packages-npm-production"}},"2026.4.27":{"name":"@brycehuang/wecom-openclaw-plugin","version":"2026.4.27","keywords":["wecom","openclaw","wecom-openclaw-plugin"],"author":"","license":"MIT","_id":"@brycehuang/wecom-openclaw-plugin@2026.4.27","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"homepage":"https://github.com/WecomTeam/wecom-openclaw-plugin#readme","bugs":{"url":"https://github.com/WecomTeam/wecom-openclaw-plugin/issues"},"dist":{"shasum":"dbe3da95a530dce2e0fb276482913ae66020df13","tarball":"https://registry.npmjs.org/@brycehuang/wecom-openclaw-plugin/-/wecom-openclaw-plugin-2026.4.27.tgz","fileCount":170,"integrity":"sha512-m6Jn6kR9G8T/AJtx6l+a4CRc80jp057XWkxj3UXw9dJqNZ9twEnsaqr3wHVRYGrcwoHLTJ8nBlwVXJ3oYLeFWA==","signatures":[{"sig":"MEQCICRx5LwZ+1RUzfQhfW/eHlQY60Dpt2Ye+R5fivbPxb48AiBDcpN7i+won3v7LVGDLehHvisURRsea3sJ843jDBwDqw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":855707},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c507c0b2557bd0f4e825fabd99d3eb5dc994856b","scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist","release":"node scripts/publish-all.mjs","prebuild":"npm run clean","release:dry":"node scripts/publish-all.mjs --dry-run","deploy:local":"bash scripts/dev-deploy.sh"},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"openclaw":{"channel":{"id":"wecom","blurb":"企业微信机器人接入插件","label":"企业微信","order":80,"docsPath":"/channels/wecom","docsLabel":"wecom-openclaw-plugin","selectionLabel":"企业微信 (WeCom)","quickstartAllowFrom":true},"install":{"npmSpec":"@brycehuang/wecom-openclaw-plugin","localPath":"extensions/wecom-openclaw-plugin","defaultChoice":"npm"},"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/WecomTeam/wecom-openclaw-plugin.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw WeCom (企业微信) channel plugin (official by Tencent WeCom team)","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^4.3.6","undici":"^7.24.6","file-type":"^21.3.0","fast-xml-parser":"^5.5.9","@brycehuang/aibot-node-sdk":"^1.0.6"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.1","openclaw":">=2026.3.28","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/wecom-openclaw-plugin_2026.4.27_1777375179104_0.7030878332234689","host":"s3://npm-registry-packages-npm-production"}},"2026.4.29":{"name":"@brycehuang/wecom-openclaw-plugin","version":"2026.4.29","keywords":["wecom","openclaw","wecom-openclaw-plugin"],"author":"","license":"MIT","_id":"@brycehuang/wecom-openclaw-plugin@2026.4.29","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"homepage":"https://github.com/WecomTeam/wecom-openclaw-plugin#readme","bugs":{"url":"https://github.com/WecomTeam/wecom-openclaw-plugin/issues"},"dist":{"shasum":"b84d0f87404685cf33b0ac15358d6332cc927eeb","tarball":"https://registry.npmjs.org/@brycehuang/wecom-openclaw-plugin/-/wecom-openclaw-plugin-2026.4.29.tgz","fileCount":170,"integrity":"sha512-xw7YabVeI5JzAwKj8f6q4o6c8mnbo8yBAd+Uag2rmYNXPez0RNkZ0XMkvOgCegkFHHpdDdZfnxkAGKqIEOYwzA==","signatures":[{"sig":"MEUCIQCW+uRYL41KVQGiem+ZOJ6Xop7V7bwTdnQtH1qpV5o2PgIgTU2JvLjIsjWAyAvR/9d1qymhWX8hs1HY7O6hfSEHXWo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":851340},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"59a34f6df66839ff0669f8849d0add5cb89a96e3","scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist","release":"node scripts/publish-all.mjs","prebuild":"npm run clean","release:dry":"node scripts/publish-all.mjs --dry-run","deploy:local":"bash scripts/dev-deploy.sh"},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"openclaw":{"channel":{"id":"wecom","blurb":"企业微信机器人接入插件","label":"企业微信","order":80,"docsPath":"/channels/wecom","docsLabel":"wecom-openclaw-plugin","selectionLabel":"企业微信 (WeCom)","quickstartAllowFrom":true},"install":{"npmSpec":"@brycehuang/wecom-openclaw-plugin","localPath":"extensions/wecom-openclaw-plugin","defaultChoice":"npm"},"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/WecomTeam/wecom-openclaw-plugin.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw WeCom (企业微信) channel plugin (official by Tencent WeCom team)","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^4.3.6","undici":"^7.24.6","file-type":"^21.3.0","fast-xml-parser":"^5.5.9","@brycehuang/aibot-node-sdk":"^1.0.6"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.1","openclaw":">=2026.3.28","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/wecom-openclaw-plugin_2026.4.29_1777518569711_0.24897123027949952","host":"s3://npm-registry-packages-npm-production"}},"2026.4.30":{"name":"@brycehuang/wecom-openclaw-plugin","version":"2026.4.30","type":"module","main":"dist/index.mjs","types":"dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"build":"tsdown","dev":"tsdown --watch","clean":"rm -rf dist","prebuild":"npm run clean","release":"node scripts/publish-all.mjs","release:dry":"node scripts/publish-all.mjs --dry-run","deploy:local":"bash scripts/dev-deploy.sh"},"keywords":["wecom","openclaw","wecom-openclaw-plugin"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/WecomTeam/wecom-openclaw-plugin.git"},"homepage":"https://github.com/WecomTeam/wecom-openclaw-plugin#readme","bugs":{"url":"https://github.com/WecomTeam/wecom-openclaw-plugin/issues"},"description":"OpenClaw WeCom (企业微信) channel plugin (official by Tencent WeCom team)","openclaw":{"extensions":["./dist/index.mjs"],"channel":{"id":"wecom","label":"企业微信","selectionLabel":"企业微信 (WeCom)","docsPath":"/channels/wecom","docsLabel":"wecom-openclaw-plugin","blurb":"企业微信机器人接入插件","order":80,"quickstartAllowFrom":true},"install":{"npmSpec":"@brycehuang/wecom-openclaw-plugin","localPath":"extensions/wecom-openclaw-plugin","defaultChoice":"npm"}},"dependencies":{"@brycehuang/aibot-node-sdk":"^1.0.6","fast-xml-parser":"^5.5.9","file-type":"^21.3.0","undici":"^7.24.6","zod":"^4.3.6"},"devDependencies":{"openclaw":">=2026.3.28","tsdown":"^0.21.10","typescript":"^5.3.3","vitest":"^4.1.1"},"gitHead":"59a34f6df66839ff0669f8849d0add5cb89a96e3","_id":"@brycehuang/wecom-openclaw-plugin@2026.4.30","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Wr1/kAf0EPX/uvKB7vB+n9kDM3sLhZFg5cnmBsy3ItUqRnx/oqwHOhvxYstwVyrx1HTvVlJHNVZq6V+b/tcrHA==","shasum":"376375cab948091dd8b238f2b34e654038ae7b77","tarball":"https://registry.npmjs.org/@brycehuang/wecom-openclaw-plugin/-/wecom-openclaw-plugin-2026.4.30.tgz","fileCount":43,"unpackedSize":2266750,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBNAN+RHf8di9y1uEI/HkjNlTm/CWg0oPhey2aQbg4GYAiEAvoq/A/U4wb9+VSSYXfILU+825+CkfxW1ny1vPLjGHEI="}]},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"directories":{},"maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wecom-openclaw-plugin_2026.4.30_1777521205784_0.20200976866083376"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T11:04:00.740Z","modified":"2026-04-30T03:53:26.075Z","2026.4.22":"2026-04-28T11:04:01.012Z","2026.4.27":"2026-04-28T11:19:39.314Z","2026.4.29":"2026-04-30T03:09:29.865Z","2026.4.30":"2026-04-30T03:53:25.970Z"},"bugs":{"url":"https://github.com/WecomTeam/wecom-openclaw-plugin/issues"},"license":"MIT","homepage":"https://github.com/WecomTeam/wecom-openclaw-plugin#readme","keywords":["wecom","openclaw","wecom-openclaw-plugin"],"repository":{"type":"git","url":"git+https://github.com/WecomTeam/wecom-openclaw-plugin.git"},"description":"OpenClaw WeCom (企业微信) channel plugin (official by Tencent WeCom team)","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"readme":"> 💡 **快速上手指引 & 交流群**\n>\n> 📖 [点击查看完整接入指引文档](https://doc.weixin.qq.com/doc/w3_AFYA1wY6ACoCNRxfnyGRJQaSa6jjJ?scode=AJEAIQdfAAo0RJmzxLAFYA1wY6ACo) — 包含配置步骤、产品介绍、常见问题解答等。\n>\n> 💬 扫码加入企业微信交流群：\n>\n> <img src=\"https://wwcdn.weixin.qq.com/node/wework/images/202603241759.3fb01c32cc.png\" alt=\"扫码入群交流\" width=\"200\" />\n\n# 特别说明\n> ****2026.3.22 版本 OpenClaw 兼容说明****\n> \n> 如果你的 OpenClaw 是 2026.3.22 及以上的版本，请升级插件到 2026.3.24 及以上版本。\n> \n> 如果你的 OpenClaw 是 2026.3.22 以下的版本，请保持插件版本在 2026.3.20 版本。\n> \n> 你可以使用以下命令快速安装： `npx -y @wecom/wecom-openclaw-cli install --force`\n\n# 🤖 WeCom OpenClaw Plugin\n\n**WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.\n\n> 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.\n\n---\n\n📖 [WeCom AI Bot Official Documentation](https://open.work.weixin.qq.com/help?doc_id=21657)\n\n\n## ✨ Features\n\n- 🔗 **Dual-mode**: Bot (WebSocket / Webhook) and Agent (HTTP webhook) can run independently or together\n- 💬 Supports both direct messages (DM) and group chat\n- 📤 Proactive messaging to specific users, groups, departments, or tags\n- 🖼️ Receives and processes image, voice, video, file, and **mixed (图文混排)** messages with automatic downloading\n- 🗣️ Voice-to-text: automatically extracts transcribed text from voice messages\n- 💬 Quote message support: processes quoted text, image, voice, and file messages\n- ⏳ Streaming replies with \"thinking\" placeholder messages (Bot mode)\n- 🔐 Agent mode: AES-256-CBC encrypted XML callbacks with SHA1 signature verification\n- 📝 Markdown formatting support for replies\n- 🃏 Template card messages (text_notice, news_notice, button_interaction, vote_interaction, multiple_interaction) with **event callback handling**\n- 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)\n- 🔑 Command authorization: per-account command permission control with access group support\n- 👥 Multi-account support: run multiple WeCom accounts with independent bot/agent configs\n- 🧩 MCP tool integration (`wecom_mcp`) with interceptor pipeline (biz-error, media, smartpage-create, smartpage-export)\n- 🎯 **15 built-in Skills**: contact lookup, doc management, todo, meeting, schedule, messaging, smartsheet, template cards, and more\n- 🔀 Dynamic Agent routing: auto-create isolated agents per user/group\n- 📁 Local file sending with configurable media path allowlist (`mediaLocalRoots`)\n- 📊 Smart media size limits with auto-downgrade (image 10MB → file, video 10MB → file, voice 2MB/AMR-only → file, max 20MB)\n- 🔄 **Bot-first, Agent-fallback** outbound delivery: auto fallback to Agent HTTP API when Bot WS is unavailable\n- ⚡ Auto heartbeat keep-alive and reconnection (up to 10 reconnect attempts, 5 auth failure retries)\n- 🛡️ Anti-kick protection: suppresses auto-restart on server-side disconnection to prevent mutual kicking loops\n- 🧙 Interactive CLI setup wizard\n\n---\n\n## 🚀 Getting Started\n\n### Requirements\n\n- OpenClaw `>= 2026.3.28`\n\n### Quick Install\n\nUse the CLI tool to automatically install the plugin and complete bot configuration in one step:\n\n```shell\n# Automatically install the channel plugin and quickly complete configuration; also works for updates\nnpx -y @wecom/wecom-openclaw-cli install\n```\n\nMore Options\n```shell\n# If installation fails, try force install\nnpx -y @wecom/wecom-openclaw-cli install --force\n\n# Use --help to learn more about the tool\nnpx -y @wecom/wecom-openclaw-cli --help\n```\n\n### Manual Install\n\n```shell\nopenclaw plugins install @wecom/wecom-openclaw-plugin\n```\n\n### Configuration\n\n#### Option 1: Interactive Setup\n\n```shell\nopenclaw channels add\n```\n\nFollow the prompts to enter your WeCom bot's **Bot ID** and **Secret**.\n\n#### Option 2: CLI Quick Setup\n\n```shell\nopenclaw config set channels.wecom.botId <YOUR_BOT_ID>\nopenclaw config set channels.wecom.secret <YOUR_BOT_SECRET>\nopenclaw config set channels.wecom.enabled true\nopenclaw gateway restart\n```\n\n### Mode Overview\n\nThe plugin supports two connection modes that can be used independently or together:\n\n| Mode | Connection | Message Format | Use Case |\n|------|-----------|---------------|----------|\n| **Bot** (智能体) | WebSocket (default) or HTTP webhook | JSON | Quick setup, streaming replies |\n| **Agent** (自建应用) | HTTP webhook callbacks | XML | Enterprise apps, API-driven messaging |\n\n> **Note**: Bot mode supports two connection methods via `connectionMode`:\n> - `websocket` (default) — WebSocket long-polling, requires `botId` + `secret`\n> - `webhook` — HTTP callback, requires `token` + `encodingAESKey`\n\n### Bot Mode Configuration\n\n#### Core Settings\n\n| Config Path | Description | Options | Default |\n|---|---|---|---|\n| `channels.wecom.enabled` | Enable the channel | `true` / `false` | `false` |\n| `channels.wecom.connectionMode` | Bot connection mode | `websocket` / `webhook` | `websocket` |\n| `channels.wecom.name` | Account display name | — | `企业微信` |\n\n#### WebSocket Mode (default)\n\n| Config Path | Description | Options | Default |\n|---|---|---|---|\n| `channels.wecom.botId` | WeCom bot ID | — | — |\n| `channels.wecom.secret` | WeCom bot secret | — | — |\n| `channels.wecom.websocketUrl` | WebSocket endpoint | — | `wss://openws.work.weixin.qq.com` |\n| `channels.wecom.sendThinkingMessage` | Send \"thinking\" placeholder | `true` / `false` | `true` |\n\n#### Webhook Mode (`connectionMode: \"webhook\"`)\n\n| Config Path | Description | Options | Default |\n|---|---|---|---|\n| `channels.wecom.token` | Webhook verification token | — | — |\n| `channels.wecom.encodingAESKey` | AES encryption key (43 chars Base64) | — | — |\n| `channels.wecom.receiveId` | Receiver ID (for decryption verification) | — | — |\n| `channels.wecom.welcomeText` | Welcome message on enter_chat event | — | — |\n| `channels.wecom.streamPlaceholderContent` | Stream placeholder content | — | — |\n\n#### Access Control\n\n| Config Path | Description | Options | Default |\n|---|---|---|---|\n| `channels.wecom.dmPolicy` | DM access policy | `pairing` / `open` / `allowlist` / `disabled` | `open` |\n| `channels.wecom.allowFrom` | DM allowlist (user IDs) | — | `[]` |\n| `channels.wecom.groupPolicy` | Group chat access policy | `open` / `allowlist` / `disabled` | `open` |\n| `channels.wecom.groupAllowFrom` | Group allowlist (group IDs) | — | `[]` |\n| `channels.wecom.groups` | Per-group config (e.g. sender allowlist) | — | `{}` |\n\n#### Media Settings\n\n| Config Path | Description | Default |\n|---|---|---|\n| `channels.wecom.mediaLocalRoots` | Extra local paths allowed for media sending (supports `~`) | `[]` |\n| `channels.wecom.media.maxBytes` | Max media file size in bytes | `20971520` (20MB) |\n| `channels.wecom.media.tempDir` | Temp directory for media processing | — |\n| `channels.wecom.media.retentionHours` | Media file retention hours | — |\n| `channels.wecom.media.cleanupOnStart` | Clean temp media on startup | — |\n\n**Media Size Limits & Auto-Downgrade:**\n\n| Media Type | Max Size | Downgrade Behavior |\n|---|---|---|\n| Image | 10 MB | Exceeds → sent as file |\n| Video | 10 MB | Exceeds → sent as file |\n| Voice | 2 MB (AMR only) | Non-AMR format or exceeds → sent as file |\n| File | 20 MB | Exceeds → rejected (cannot send) |\n\n#### Network Settings\n\n| Config Path | Description | Default |\n|---|---|---|\n| `channels.wecom.network.timeoutMs` | HTTP request timeout (ms) | — |\n| `channels.wecom.network.retries` | Number of retries | — |\n| `channels.wecom.network.retryDelayMs` | Delay between retries (ms) | — |\n| `channels.wecom.network.egressProxyUrl` | Egress proxy URL for trusted IP scenarios | — |\n\n> **Egress Proxy Priority**: `channels.wecom.network.egressProxyUrl` > `OPENCLAW_WECOM_EGRESS_PROXY_URL` > `WECOM_EGRESS_PROXY_URL` > `HTTPS_PROXY` > `ALL_PROXY` > `HTTP_PROXY`\n\n### Agent Mode Configuration\n\nAgent 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.\n\n#### Prerequisites\n\n1. Create a self-built app in [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps)\n2. Note down the **CorpID**, **CorpSecret** (from app settings), and **AgentId**\n3. In the app settings, go to \"API Receive\" (API接收):\n   - Note down the **Token** and **EncodingAESKey** (auto-generated or custom)\n   - **Do NOT click save yet** — WeCom will verify the callback URL immediately when you save\n\n#### Setup Steps\n\n> **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.\n\n**Step 1: Configure Gateway**\n\n```shell\nopenclaw config set channels.wecom.agent.corpId <YOUR_CORP_ID>\nopenclaw config set channels.wecom.agent.corpSecret <YOUR_CORP_SECRET>\nopenclaw config set channels.wecom.agent.agentId <YOUR_AGENT_ID>\nopenclaw config set channels.wecom.agent.token <YOUR_CALLBACK_TOKEN>\nopenclaw config set channels.wecom.agent.encodingAESKey <YOUR_ENCODING_AES_KEY>\nopenclaw config set channels.wecom.enabled true\nopenclaw gateway restart\n```\n\n**Step 2: Save callback URL in WeCom admin console**\n\nGo back to the \"API Receive\" settings and enter the callback URL:\n- **URL**: `https://<your-gateway-host>/plugins/wecom/agent/<accountId>` (e.g. `/plugins/wecom/agent/default`); single-account mode can also use `/plugins/wecom/agent`\n\nNow click save — the verification should pass.\n\n#### JSON Configuration\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"agent\": {\n        \"corpId\": \"ww1234567890abcdef\",\n        \"corpSecret\": \"your-corp-secret\",\n        \"agentId\": 1000002,\n        \"token\": \"your-callback-token\",\n        \"encodingAESKey\": \"your-encoding-aes-key-43-chars\"\n      }\n    }\n  }\n}\n```\n\n#### Agent Config Reference\n\n| Config Path | Description | Required |\n|---|---|---|\n| `channels.wecom.agent.corpId` | Enterprise Corp ID | Yes |\n| `channels.wecom.agent.corpSecret` | App secret | Yes |\n| `channels.wecom.agent.agentId` | App agent ID | No (needed for proactive messaging) |\n| `channels.wecom.agent.token` | Callback verification token | Yes |\n| `channels.wecom.agent.encodingAESKey` | Callback encryption key (43 chars) | Yes |\n| `channels.wecom.agent.welcomeText` | Welcome message | No |\n| `channels.wecom.agent.dmPolicy` | DM access policy (overrides top-level) | No |\n| `channels.wecom.agent.allowFrom` | DM allowlist (overrides top-level) | No |\n\n#### Webhook Paths\n\n**Agent Mode:**\n\n| Path | Description |\n|---|---|\n| `/plugins/wecom/agent/<accountId>` | 推荐路径（例如 `/plugins/wecom/agent/default`） |\n| `/plugins/wecom/agent/default` | 多账号模式下自动路由到默认账号（即使默认账号 ID 不是 `default`） |\n| `/plugins/wecom/agent` | 兼容路径（单账号 / 多账号签名匹配） |\n| `/wecom/agent` | Legacy 兼容路径 |\n\n**Bot Webhook Mode** (`connectionMode: \"webhook\"`):\n\n| Path | Description |\n|---|---|\n| `/plugins/wecom/bot` | Recommended path (single account) |\n| `/plugins/wecom/bot/<accountId>` | Multi-account path |\n| `/wecom/bot` | Legacy compatible path |\n| `/wecom` | Legacy compatible path |\n\n### Outbound Delivery (Bot WS → Agent HTTP Fallback)\n\nThe plugin uses a **Bot-first, Agent-fallback** strategy for outbound message delivery:\n\n1. **Bot WebSocket available** → send via WS (supports markdown, streaming)\n2. **Bot WS unavailable** → automatically fallback to **Agent HTTP API** (`cgi-bin/message/send`)\n\nThis means:\n- **Agent-only accounts** (no Bot configured) can still send proactive messages, cron deliveries, and broadcasts\n- **Target formats** like `party:1`, `tag:Ops`, `user:zhangsan` are fully supported in both paths\n- **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\n- No manual switching needed — the plugin handles fallback transparently\n\n### Using Both Modes Together\n\nBot and Agent can run simultaneously on the same account. Bot handles WebSocket streaming; Agent handles HTTP webhook callbacks with API-driven replies.\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"botId\": \"your-bot-id\",\n      \"secret\": \"your-bot-secret\",\n      \"agent\": {\n        \"corpId\": \"ww1234567890abcdef\",\n        \"corpSecret\": \"your-corp-secret\",\n        \"agentId\": 1000002,\n        \"token\": \"your-callback-token\",\n        \"encodingAESKey\": \"your-encoding-aes-key-43-chars\"\n      }\n    }\n  }\n}\n```\n\n### Multi-Account Configuration\n\nUse `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.\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"main\",\n      \"dmPolicy\": \"open\",\n      \"accounts\": {\n        \"main\": {\n          \"botId\": \"bot-id-1\",\n          \"secret\": \"secret-1\",\n          \"agent\": {\n            \"corpId\": \"ww1234567890abcdef\",\n            \"corpSecret\": \"secret-a\",\n            \"agentId\": 1000002,\n            \"token\": \"token-a\",\n            \"encodingAESKey\": \"aes-key-a\"\n          }\n        },\n        \"support\": {\n          \"dmPolicy\": \"allowlist\",\n          \"allowFrom\": [\"admin1\"],\n          \"agent\": {\n            \"corpId\": \"ww1234567890abcdef\",\n            \"corpSecret\": \"secret-b\",\n            \"agentId\": 1000003,\n            \"token\": \"token-b\",\n            \"encodingAESKey\": \"aes-key-b\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n> **Note**: In multi-account mode, accounts without explicit `bindings` will not fall back to the default agent. Configure bindings for each account:\n> ```json\n> {\n>   \"bindings\": [\n>     { \"agentId\": \"your-agent\", \"match\": { \"channel\": \"wecom\", \"accountId\": \"main\" } }\n>   ]\n> }\n> ```\n\n### Dynamic Agent Configuration\n\nDynamic Agent routing automatically creates isolated agents per user or group, enabling session isolation.\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"dynamicAgents\": {\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"admin_user_id\"]\n      }\n    }\n  }\n}\n```\n\n| Config Path | Description | Default |\n|---|---|---|\n| `channels.wecom.dynamicAgents.enabled` | Enable dynamic agent routing | `false` |\n| `channels.wecom.dynamicAgents.dmCreateAgent` | Create isolated agent per DM user | `true` |\n| `channels.wecom.dynamicAgents.groupEnabled` | Enable dynamic agent for group chats | `true` |\n| `channels.wecom.dynamicAgents.adminUsers` | Admin users (bypass dynamic routing, use main agent) | `[]` |\n\n---\n\n## 🔒 Access Control\n\n### DM (Direct Message) Access\n\n**Default**: `dmPolicy: \"open\"` — all users can send direct messages without approval.\n\n#### Approve Pairing\n\n```shell\nopenclaw pairing list wecom            # View pending pairing requests\nopenclaw pairing approve wecom <CODE>  # Approve a pairing request\n```\n\n#### Allowlist Mode\n\nConfigure allowed user IDs via `channels.wecom.allowFrom`:\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"dmPolicy\": \"allowlist\",\n      \"allowFrom\": [\"user_id_1\", \"user_id_2\"]\n    }\n  }\n}\n```\n\n#### Open Mode\n\nSet `dmPolicy: \"open\"` to allow all users to send direct messages without approval.\n\n#### Disabled Mode\n\nSet `dmPolicy: \"disabled\"` to completely block all direct messages.\n\n### Group Access\n\n#### Group Policy (`channels.wecom.groupPolicy`)\n\n- `\"open\"` — Allow messages from all groups (default)\n- `\"allowlist\"` — Only allow groups listed in `groupAllowFrom`\n- `\"disabled\"` — Disable all group messages\n\n### Group Configuration Examples\n\n#### Allow All Groups (Default Behavior)\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"groupPolicy\": \"open\"\n    }\n  }\n}\n```\n\n#### Allow Only Specific Groups\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"groupPolicy\": \"allowlist\",\n      \"groupAllowFrom\": [\"group_id_1\", \"group_id_2\"]\n    }\n  }\n}\n```\n\n#### Allow Only Specific Senders Within a Group (Sender Allowlist)\n\nIn 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**.\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"groupPolicy\": \"allowlist\",\n      \"groupAllowFrom\": [\"group_id_1\"],\n      \"groups\": {\n        \"group_id_1\": {\n          \"allowFrom\": [\"user_id_1\", \"user_id_2\"]\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n## ⏰ Cronjob (Scheduled Tasks)\n\nThe 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.\n\n### Target Formats\n\nThe `delivery.to` field supports the following target formats:\n\n| Format | Target | Example |\n|--------|--------|--------|\n| `party:<id>` | Department (all members) | `party:1` (root dept = all employees) |\n| `dept:<id>` | Department (alias for party) | `dept:5` |\n| `tag:<id>` | Tag group | `tag:Ops` |\n| `user:<id>` | Specific user | `user:zhangsan` |\n| `group:<id>` | External group chat | `group:wr123abc` |\n| `chat:<id>` | Group chat (alias for group) | `chat:wc456def` |\n| Pure number | Auto-detected as department | `1` → `party:1` |\n| `wr...` / `wc...` | Auto-detected as group chat | `wr123` → `chatid` |\n| Other string | Auto-detected as user | `zhangsan` → `touser` |\n\n> **Namespace prefixes** (`wecom:`, `qywx:`, `wework:`, `wechatwork:`, `wecom-agent:`) are automatically stripped before parsing.\n\n### Method 1: CLI (Recommended — takes effect immediately)\n\n```shell\nopenclaw cron add \\\n  --name \"daily-report\" \\\n  --agent main \\\n  --cron \"0 9 * * 1-5\" \\\n  --tz \"Asia/Shanghai\" \\\n  --message \"Good morning! Here is your daily briefing.\" \\\n  --announce \\\n  --channel wecom \\\n  --to \"party:1\"\n```\n\n> **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`.\n\nCommon CLI commands:\n\n```shell\nopenclaw cron list              # List all cron jobs\nopenclaw cron show <id>         # Show job details\nopenclaw cron enable <id>       # Enable a job\nopenclaw cron disable <id>      # Disable a job\nopenclaw cron remove <id>       # Remove a job\nopenclaw cron run <id>          # Manually trigger a job\nopenclaw cron runs --id <id>    # View run history\nopenclaw cron edit <id> --message \"New prompt\"  # Edit a job\n```\n\n### Method 2: Edit `jobs.json` (requires gateway restart)\n\nFile path: `~/.openclaw/cron/jobs.json`\n\n```json\n{\n  \"version\": 1,\n  \"jobs\": [\n    {\n      \"id\": \"daily-report\",\n      \"name\": \"Daily Report\",\n      \"agentId\": \"main\",\n      \"enabled\": true,\n      \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 9 * * 1-5\", \"tz\": \"Asia/Shanghai\" },\n      \"sessionTarget\": \"isolated\",\n      \"wakeMode\": \"now\",\n      \"payload\": {\n        \"kind\": \"agentTurn\",\n        \"message\": \"Generate today's briefing and send it.\"\n      },\n      \"delivery\": {\n        \"mode\": \"announce\",\n        \"channel\": \"wecom\",\n        \"to\": \"party:1\",\n        \"accountId\": \"main\"\n      },\n      \"state\": {}\n    }\n  ]\n}\n```\n\nAfter editing, restart the gateway:\n\n```shell\nopenclaw gateway restart\n```\n\n### Method 3: Create via chat (takes effect immediately)\n\nYou can ask the AI agent directly in a WeCom conversation:\n\n> \"Create a scheduled task: send a daily briefing to the entire company at 9am every weekday\"\n\nThe agent will call the Cron API to create the job — no restart needed.\n\n### Notes\n\n- Cron jobs use the **Agent outbound** path — Agent mode (`corpId` / `corpSecret` / `agentId`) must be configured.\n- The server IP must be in the WeCom trusted IP allowlist, or configure `egressProxyUrl` for a fixed egress proxy.\n- Jobs created via CLI or chat API take effect immediately. Manual edits to `jobs.json` require `openclaw gateway restart`.\n- For multi-account setups, set `delivery.accountId` to the target account (e.g. `\"main\"`, `\"support\"`).\n\n---\n\n## 📦 Update\n\n```shell\nopenclaw plugins update wecom-openclaw-plugin\n```\n\n---\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md"}