OpenClaw 企业微信（WeCom）Channel 插件

Warning

原创声明：本项目涉及的“多账号隔离与矩阵路由架构”、“Bot+Agent双模融合架构”、“长任务超时接力逻辑”及“全自动媒体流转接”等核心设计均为作者 YanHaidao 独立思考与实践的原创成果。欢迎技术交流与合规引用，但严禁任何不经授权的“功能像素级抄袭”或删除原作者署名的代码搬运行为。

🚀 企业级多模式 AI 助手接入方案（统一运行时架构）

💡 核心价值 • 📊 模式对比 • 📋 最近更新 • 一、快速开始 • 二、配置说明 • 三、企业微信接入 • 四、高级功能 • 五、详细行为说明 • 六、社区与维护

💡 核心价值：为什么选择本插件？

🎉 重大特性一览

防断连黑科技 (v2.3.11 升级)：针对 DeepSeek R1 等长时间的推理模型，Bot WS 已升级为 即时占位 + 持续保活 ACK 机制。收到用户消息后立即展示 streamPlaceholderContent，并在首个真实回复块到来前持续保活，显著降低 WebSocket invalid req_id 与消息卡死现象。
无需域名，极低门槛：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，彻底打通无公网 IP、无备案域名的内网服务器与企微的实时对话桥梁！
主动发消息，能力全覆盖：基于 Agent 模式，全面支持主动触达，轻松实现早报定时任务、服务器异常报警、自动每日总结。
向导自动路由自动适配 (v2.3.10 新增)：在终端执行 openclaw channels add 时，若是单企微账号接入，将静默触发自动 Agent 路由绑定，丝滑跳过全局冗杂的路由分配步骤。

🔧 全新统一运行时架构 (Unified Runtime)

插件现已采用全新解耦架构：

Bot / Agent 是能力层 (Capability)。
WS / Webhook / Callback / API 是传输层 (Transport)。
同一账号下，Bot 可以在长连接（WS）和主动回调（Webhook）之间通过 primaryTransport 自由无缝切换。
HTTP Callback 路径一律由系统基于 accountId 全自动派生，告别繁乱的手工 URL 配置。

🎭 独创架构：Bot + Agent 双模融合 (Original Design by YanHaidao)

传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。本插件采用 双模并行架构，同时压榨两种模式的极限能力：

Bot 通道 (智能体)：负责 实时对话。提供毫秒级流式响应（打字机效果），零延迟交互。
Agent 通道 (自建应用)：负责 能力兜底。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。

🚀 企业级：多账号（Multi-account）矩阵隔离 (Original Design)

本插件支持 无限扩展的账号矩阵，这是本插件区别于普通插件的核心壁垒：

千人千面 (Dynamic Agents)：内置自动会话隔离机制，百人同时私聊或群聊自动分摊至专属独立助理，告别上下文串扰。
账号级隔离 (Isolation)：不同 accountId 之间的收发链路、运行时实例与动态 Agent 默认隔离；若多个账号共用同一个静态 Agent，建议额外配合 session.dmScope = "per-account-channel-peer"，避免私聊上下文共用。
矩阵绑定 (Binding)：支持一个 OpenClaw 实例同时挂载多个企业/多个应用，通过 bindings 灵活分发流量。
智能路由 (Routing)：基于入站 accountId 自动分拣回复路径，Bot 无法回复时仅回退到同账号组内的 Agent，实现闭环的高可用。

功能特性全景

🗣 沉浸式交互 (Immersive Interaction)

原生流式 (Stream)：基于 HTTP 分块传输，拒绝 "转圈等待"，体验如 ChatGPT 网页版般丝滑。
交互式卡片 (Card)：支持 Button/Menu 交互回传，可构建审批、查询等复杂业务流 (Agent模式)。

📎 全模态支持 (Multi-Modal)

发什么都能看：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
要什么都能给：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。

📢 企业级触达 (Enterprise Reach)

精准广播：支持向 部门 (Party)、标签 (Tag) 或 外部群 批量推送消息。
Cronjob 集成：通过简单的 JSON 配置实现早报推送、日报提醒、服务器报警。

🛡 生产级稳定 (Production Ready)

容灾切换：Bot 模式 6 分钟超时自动熔断，切换 Agent 私信送达，防止长任务回答丢失。
Token 自动运维：内置 AccessToken 守护进程，自动缓存、提前刷新、过期重试。

📊 模式能力对比

能力维度	🤖 Bot 模式	🧩 Agent 模式	✨ 本插件 (双模)
部署网络要求	✅ 无需公网IP/域名 (WS)	❌ 必须公网IP/域名回调	✅ 全环境适用
接收消息 (单聊)	✅ 文本/图片/语音/文件	✅ 文本/图片/语音/视频/位置/链接	✅ 全能互补 (覆盖所有类型)
接收消息 (群聊)	✅ 文本/引用	❌ 不支持 (群聊无回调)	✅ 文本/引用
回复消息类型	❌ 仅文本/图片/Markdown	✅ 全模态 (文本/图片/视频/文件等)	✅ 智能路由 (自动判定切换)
交互卡片 (A2UI)	❌ 不支持	✅ 支持 (Button/Select等)	✅ 支持
AI 流式响应	✅ 支持 (丝滑打字机)	❌ 不支持 (全部生成完一次发送)	✅ 完美支持
主动触达 (Cron)	❌ 仅被动回复/有限推送	✅ 全量推送 (指定人/部门/标签)	✅ 企业级触达

📋 最近更新

项目保持高频迭代，核心改进一览：

v2.3.13（2026-03-13）

🛠 [重要修复] Bot WS 现在会把“引用 + 提问”中的引用内容一起带入 Agent 上下文，不再只保留用户当前这句提问。
🌊 [重要修复] Bot WS 流式回复改为按“累计全文刷新”发送，修复企业微信客户端里长回答断断续续、像被拆成多段的问题。
🧩 Bot WS 这次显式对齐企业微信 stream.id 的刷新语义：后续更新会覆盖为当前完整内容，而不是只发送最新增量片段。
✅ 新增 bot-ws 引用上下文与累计流式发送回归测试，避免后续重构回退。

v2.3.12（2026-03-12）

🛠 [重要修复] Bot WS 流式回复超 6 分钟后的 846608 stream message update expired 现在被识别为终态错误，不再导致进程退出。
🛠 [重要修复] SDK 5 秒回执超时 (Reply ack timeout) 也被识别为终态错误，超时后立即停止占位保活，不再产生 unhandledRejection。
🚀 Bot WS 模式下主动文本消息优先走 WS 长连接；Agent 仅兜底文件/媒体或未启用 WS 的场景。
🧯 sdk-adapter 为 WebSocket frame 异步处理补上显式兜底捕获，漏网异常记录为 runtime issue 而非崩溃。
⏱ 回复窗口过期时占位符保活立即停止。
🛠 [重要修复] Bot WS 模式下接收图片/文件现在使用消息体独立 aeskey 解密，修复之前保存密文导致 Failed to optimize image 的问题。
🛠 [重要修复] 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的 81013 错误。在 wecom-agent: 作用域下，纯数字目标现在优先解析为用户。

v2.3.11（2026-03-11）

Bot WS 升级为即时占位 + 持续保活，降低长思考时的 invalid req_id。
streamPlaceholderContent 统一作用于 Bot WS 与 Bot Webhook。
onboarding 在空配置下也会提供 default 账号选项。

v2.3.10（2026-03-10）

onboarding 默认收敛为 Bot + WS + 开放私聊。
修复 Bot WS 长文本双重回复问题。
Agent 新配置统一使用 agentSecret。

更早版本

v2.3.9（2026-03-09）

Bot 默认接入改为 WebSocket，无需域名更易上手。
完善中文 onboarding，减少重复提示。
恢复 Bot WS 流式输出能力。
增强 Agent 回调与发送日志，排障更直接。

详细版本记录见 changelog/ 目录。

一、🚀 快速开始

推荐统一使用多账号矩阵模型。即使只有一个账号，也建议写在 channels.wecom.accounts.default 节点下。

1.1 安装插件

openclaw plugins install @yanhaidao/wecom
openclaw plugins enable wecom

1.2 互动向导式配置 (推荐)

如果你不想手写 JSON 配置文件，可以通过互动式向导完成通道挂载：

确保已通过 npm 安装该插件：openclaw plugins install @yanhaidao/wecom并且启用了 openclaw plugins enable wecom
在终端中，输入以下命令，添加渠道：

openclaw channels add

在「Select channel」步骤的下拉列表中，找到并选择：企业微信 (WeCom)
按照屏幕终端提示，依次填入企业微信机器人 Bot ID 及 Secret 等必填项即可。

向导完成后，后台服务将自动装载你的配置并尝试建立长连接通信。

1.3 推荐配置结构（Bot + Agent 组合版）

这是生产环境最推荐的形态（进阶纯手工配置），兼顾了快速流式体验与 Agent 强大的兜底分发能力。如果您是给企业配置多名矩阵助理，或需要启动 Agent 兜底能力和定时推送能力，请进入 OpenClaw 的配置文件直接写入 JSON。以下是生产环境最推荐的综合形态：

{
  "channels": {
    "wecom": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "name": "默认企微账号",
          "bot": {
            "primaryTransport": "ws",             // 指定 Bot 主通讯协议：ws 或 webhook
            "streamPlaceholderContent": "正在思考...",
            "welcomeText": "你好，我已接入 OpenClaw。",
            "dm": {
              "policy": "pairing",
              "allowFrom": []
            },
            "ws": {                               // Bot WS 配置
              "botId": "BOT_ID",
              "secret": "BOT_SECRET"
            },
            "webhook": {                          // Bot Webhook 配置 (按需)
              "token": "BOT_TOKEN",
              "encodingAESKey": "BOT_AES_KEY",
              "receiveId": "BOT_RECEIVE_ID"
            }
          },
          "agent": {
            "corpId": "CORP_ID",
            "agentSecret": "AGENT_SECRET",
            "agentId": 1000001,
            "token": "AGENT_TOKEN",
            "encodingAESKey": "AGENT_AES_KEY",
            "welcomeText": "你好，这里是 Agent 通道。",
            "dm": {
              "policy": "open",
              "allowFrom": []
            }
          }
        }
      },
      "media": {
        "tempDir": "/tmp/openclaw-wecom-media",
        "retentionHours": 24,
        "cleanupOnStart": true,
        "maxBytes": 26214400
      },
      "network": {
        "egressProxyUrl": "http://127.0.0.1:3128"
      },
      "routing": {
        "failClosedOnDefaultRoute": true
      },
      "dynamicAgents": {
        "enabled": true,
        "dmCreateAgent": true,
        "groupEnabled": true,
        "adminUsers": ["zhangsan"]
      }
    }
  }
}

说明：

新配置推荐使用 agent.agentSecret
历史配置里的 agent.corpSecret 仍兼容读取，但后续文档统一使用 agentSecret
bot.streamPlaceholderContent 会同时作用于 Bot WS 与 Bot Webhook；在 Bot WS 下，收到用户消息后会立即显示该占位符，并在长思考期间持续保活。
如果你在一个 OpenClaw 实例里挂载多个 accounts，并让它们共同路由到同一个静态 Agent，建议在全局配置里加上 session.dmScope = "per-account-channel-peer"，让私聊 session key 显式带上 accountId。

1.3 高级网络配置（公网出口代理）

如果您的服务器使用 动态 IP (如家庭宽带、内网穿透) 或 无公网 IP，首先使用Bot模式的ws接入方式。

企业微信 API 会因 IP 变动报错 60020 not allow to access from your ip。此时需配置一个固定 IP 的正向代理 (如 Squid)，让插件通过该代理访问企微 API。

openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"

1.4 验证启动与观测

使用最新的自检命令以检查通道装载、端口绑定与运行情况：

openclaw channels status --deep

建议重点看这几个核心状态指标是否健康：

primaryTransport / transport / health

二、⚙️ 三模配置模式详解

新版已分离 Transport 传输层，以下是独立运转模式的基本构成（你可以随意组合它们入同一个 account）：

2.1 仅 Bot WS 模式

最简的流式交互版（无兜底分发功能）。关键约束：bot.primaryTransport = "ws" 必须包含 bot.ws 参数。

行为说明：

收到用户消息后立即发送一次 streamPlaceholderContent 占位流。
若模型首个真实文本块尚未产出，系统会持续发送保活占位，避免长思考期间 req_id 失效。

{
  "accounts": {
    "default": {
      "bot": {
        "primaryTransport": "ws",
        "ws": { "botId": "BOT_ID", "secret": "BOT_SECRET" }
      }
    }
  }
}

2.2 仅 Bot Webhook 模式

针对某些无法建立高可靠 WS 网关的环境，退化使用 URL 回调。关键约束：bot.primaryTransport = "webhook" 必须包含 bot.webhook 参数。

{
  "accounts": {
    "default": {
      "bot": {
        "primaryTransport": "webhook",
        "webhook": { "token": "BOT_TOKEN", "encodingAESKey": "BOT_AES_KEY" }
      }
    }
  }
}

2.3 自动分流与会话隔离 (dynamicAgents)

这属于插件的全局网络与行为组。

字段	类型	说明
`enabled`	`boolean`	是否启用动态 Agent
`dmCreateAgent`	`boolean`	私聊是否自动建 Agent
`groupEnabled`	`boolean`	群聊是否允许动态 Agent
`adminUsers`	`string[]`	管理员白名单

场景说明（解决真实企业痛点）

企业场景下，当多名同事或多个群组同时与系统交互时，系统默认只会连接同一个全局 AI Agent。这会导致会话上下文串扰（张三发的问题，李四接着问，上下文混乱）。

开启 dynamicAgents 后，可以解决此痛点，实现**“千人千面、万群万脑”**的并发隔离机制：

enabled (总开关)：一旦打开，系统会自动为每个会话的来源进行分流，并动态生成专属的底层 Agent 实例（如 wecom-default-dm-张三），无需人工配置。
dmCreateAgent (私聊自动建号)：实现员工私人助理模式。每个人私聊发消息，系统都会临时绑定独立记忆的专属助理，避免为全公司几百人挨个去后台扫码建号配置。
groupEnabled (群聊自动分群)：实现各个群聊主题封闭。A 群的讨论话题绝不会串扰到 B 群。
adminUsers (管理员特权后门)：填入管理员的微信 ID。遇到这几个人发消息时，系统不会去进动态 Agent 隔离区，而是直通后端的主控制台 Agent，以便执行全网管理指令。

🌟 多账号矩阵下的全局生效与物理隔离 dynamicAgents 属于通道级的全局开关，开启后会对配置的所有账号（accounts）生效。为了维持账号的绝对隔离，生成的隔离 Agent ID 内置了 Account 维度（例如：wecom-ops-dm-张三 vs wecom-sales-dm-张三），保证跨企业应用依旧安全隔绝。

如果你没有开启 dynamicAgents，但多个 accountId 共享同一个静态 Agent，请在 OpenClaw 全局配置里显式设置 session.dmScope = "per-account-channel-peer"，确保不同账号的私聊上下文不会被收敛到同一个 session key。

三、🏢 企业微信接入指南

新版系统已将 Callback 回调处理实现了全自动的账号分流路径派生，开发者不要在配置里手工定义 ReceiveID 的硬编码路由覆盖，请在企业微信管理后台直接指向对应路径。

3.1 明确各类模式的目标路径

类型	默认账号	非默认账号 (如 ops)
Bot Webhook	`/plugins/wecom/bot/default`	`/plugins/wecom/bot/ops`
Agent Callback	`/plugins/wecom/agent/default`	`/plugins/wecom/agent/ops`

(注：系统通过智能中间件，若只配了 default 且你访问 /plugins/wecom/bot 无后缀，也会尝试自动漂移至 default，但极不建议，必须写标准账号名后缀以规避未来扩展冲突。)

3.2 下发路由至企业微信后台

登录企业微信管理后台
机器人填入回调 URL：https://your-domain.com/plugins/wecom/bot/{accountId}
自建应用填入回调 URL：https://your-domain.com/plugins/wecom/agent/{accountId} (不要忘记加可信IP)。

四、✨ 高级功能

4.1 A2UI 交互卡片

Agent 输出 {"template_card": ...} 时自动渲染为交互卡片：

✅ 单聊场景：发送真实交互卡片
✅ 按钮点击：触发 template_card_event 回调
✅ 自动去重：基于 msgid 避免重复处理
⚠️ 群聊降级：自动转为文本描述

4.2 ⏰ Cronjob 企业级定时推送

本插件深度集成了 OpenClaw 的 Cronjob 调度能力，配合 Agent 强大的广播 API，轻松实现企业级通知服务。

核心场景：早报推送、服务器报警、日报提醒、节日祝福。

4.2.1 目标配置 (Target)

无需遍历用户列表，直接利用 Agent 强大的组织架构触达能力：

目标类型	格式示例	推送范围	典型场景
部门 (Party)	`party:1` (或 `1`)	📢 全员广播	全员通知、技术部周报
标签 (Tag)	`tag:Ops`	🎯 精准分组	运维报警、管理层汇报
外部群 (Group)	`group:wr...`	💬 群聊推送	项目组群日报 (需由Agent建群)
用户 (User)	`user:zhangsan`	👤 即时私信	个人待办提醒

4.2.2 配置示例 (`schedule.json`)

只需在工作区根目录创建 schedule.json 即可生效：

{
  "tasks": [
    {
      "cron": "0 9 * * 1-5", // 每周一至周五 早上9:00
      "action": "reply.send",
      "params": {
        "channel": "wecom",
        "to": "party:1",      // 一键发送给根部门所有人！
        "text": "🌞 早安！请查收[今日行业简报](https://example.com/daily)。"
      }
    }
  ]
}

4.3 🤖 动态 Agent 扩容引擎

在《二、配置说明》中讲解的 dynamicAgents，除了在运行时把会话隔离，它还在内存里做了一套高吞吐状态写入：系统会自动以异步、排队、防冲突的队列，将被激活的动态专用助理自动追加写入底层核心系统配置文件 openclaw.json (或相应 yaml) 的 agents.list 数组中，这就意味着：这套扩容体系是对上层管理员完全透明且免运维的，机器人活了，号也就落盘注册好了。

五、📖 详细行为说明 & 运行约束

5.1 运行约束原则

协议单工限制：同一账号下，Bot 只能选择一个主传输协议 primaryTransport (ws 或 webhook) 运作。
帧边界不可打破：Bot WS 是基于官方微信内部通信协议的扩展，它必须携带并原路奉还对应的 req_id。插件会在长思考期间自动发送占位/保活帧来维持该回复窗口，但标准化事件不会替代原始数据帧，业务流始终可访问该原始微信底层框架。
媒体沙盒边界：不论是 Webhook，还是 WS，涉及企微媒体加解密的处理绝不再跨界干预业务执行层。由内部服务自动在 Transport / Media Service 网关边界卸载 aeskey 解密并转换为统一 OpenClaw 媒体类抛出。

5.2 企业微信群聊交付规则

默认 (Bot 回复)：群聊里 @Bot，默认由 Bot 在群内直接回复（优先文本/图片/Markdown）。
例外 (文件兜底)：如果回复内容包含非图片文件（如 PDF/Word/表格/压缩包等），由于企微 Bot 接口不支持，插件会自动：
1. Bot 在群里提示："由于格式限制，文件将通过私信发送给您"。
2. 无缝切换到 自建应用 (Agent) 通道，将文件私信发送给触发者。
提示：若未配置 Agent，Bot 会明确提示“需要管理员配置自建应用通道”。

5.3 长任务可靠性保障

超时熔断：企业微信限制 Bot 流式回复窗口约为 6 分钟。
自动接力：当对话时长接近此阈值时，Monitor 会自动截断 Bot 流，提示 "剩余内容将私信发送"，并立即启动 Agent 通道私信发送完整结果。

5.4 命令行排障抓包指南

利用自带命令直接追溯到新版本的微架构心跳：

openclaw channels status --deep

如果出故障，除了系统根日志外，新版强化了命名空间隔离的抓包日志锚点，你可以直接在日志中过滤检索：

[wecom-runtime]：插件整体初始化装配线、出入站分检
[wecom-ws]：专门看 Bot WS 链路是否频繁掉线被踢、握手授权是否有效。
[wecom-http]：监控与企微云端所有 HTTP 通信（如 Token 刷新、向企微主动抛消息等网络损耗/限流情况）。
[wecom-agent-delivery]：看自建应用的被动反向代投情况以及群发选型问题。

六、🙋 社区问答 (FAQ)

针对社区反馈的高频问题，解答如下：

Q1: 能不能同时配置 bot.ws 和 bot.webhook？

A: 完全可以，且强烈推荐一起预置填写。但真正被框架加载用于接管实时会话流量的，永远遵循 bot.primaryTransport 这个单选项切换开关。

Q2: 为什么不要手写 callback path？

A: 因为由于重构后的引擎能承载大量的企业企微号同时并发挂载，所以必须抛弃写死的映射表。运行时已强制执行 {accountId} 前置命名空间策略路由分配。强行手写旧路由会被中间件劫并产生警告抛出。

Q3: 为什么 plugins list 出现重复 wecom 报错？

A: 一定是因为你既使用了 npm i @yanhaidao/wecom，又尝试 clone 代码本地挂载了 openclaw plugins install -l ./extensions/wecom 产生了 npm/file 包竞态冲突导致。请进入配置目录显露出的隐藏子目录彻底清除只留其一即可。

Q4: 使用内网穿透时，企业微信报错 60020 (IP 不白名单) 怎么办？

A: 请启用配置中的 config.network.egressProxyUrl 项。利用具有独立静态外网IP的二级跳板代理（比如 Squid），来穿透这层官方强制保护盾。

Q5: 为什么发视频给 Bot 没反应？

A: 官方 Bot 接口不支持接收视频。如果您需要处理视频内容，必须配置 Agent 小微应用，由于 Agent 下行具备富媒体流承接功能，本插件会自动从底层拦截将其解码并传输给底层大模型看。

Q6: 支持个人微信吗？

A: 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），这不等同于“个人微信网页版协议”。您可以在个人微信中直接与企业号/应用对话，无需打开企业微信 App。

七、📮 联系我与版本协议

微信交流群（扫码入群）：

维护者：YanHaidao（VX：YanHaidao）

本项目采用 ISC License 开源协议，并在此强调以下要求：

保留署名：在任何分发、修改或使用本项目时，必须完整保留本项目的版权声明。
尊重原创：本项目包含的“架构”“长对话超时接力”等均为作者 YanHaidao 核心成果，拒绝任何去署名的“纯搬运”剽窃。

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.claude		.claude
.github/workflows		.github/workflows
assets		assets
changelog		changelog
scripts		scripts
src		src
.gitignore		.gitignore
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
README.md		README.md
compat-single-account.md		compat-single-account.md
index.test.ts		index.test.ts
index.ts		index.ts
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation