Warning
原创声明:本项目涉及的“多账号隔离与矩阵路由架构”、“Bot+Agent双模融合架构”、“长任务超时接力逻辑”及“全自动媒体流转接”等核心设计均为作者 YanHaidao 独立思考与实践的原创成果。 欢迎技术交流与合规引用,但严禁任何不经授权的“功能像素级抄袭”或删除原作者署名的代码搬运行为。
🚀 企业级多模式 AI 助手接入方案(统一运行时架构)
企业真正需要的,不是“把一个模型接进企业微信”,而是让企业微信变成一个能长期工作的 AI 协作入口。
大多数团队最终只关心五件事:
- 能不能先低门槛接起来,而不是先做一轮重部署
- 多人同时使用时,会不会串上下文、串身份、串会话
- 长任务会不会因为长连接窗口太短而白跑
- 能不能既有实时对话体验,又能做正式推送和稳定投递
- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框
常见方案通常会很快碰到边界:
- 只用 Bot WS:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制
- 只用 Agent:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑
- 只选单一路径:团队最后往往被迫在“体验”和“能力”之间二选一
本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。
-
多人共用一个入口,但上下文不会串
- 问题本质:企业里真正难的不是“接入一个机器人”,而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。
- 插件做法:按
(底层账号 + 部门/群组/人员)动态切分运行上下文和 Agent 实例。 - 用户收益:同一个企业微信入口可以承接多人并发使用,而不会出现“张三的问题让李四接上回答”的串流灾难。
-
长任务不白跑,回复不轻易丢
- 问题本质:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。
- 插件做法:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。
- 用户收益:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心“算完了却发不回来”。
-
实时对话体验和正式投递能力,不用二选一
- 问题本质:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。
- 插件做法:会话内实时交互、流式回复、异步追发优先走
Bot WS;组织级广播、冷启动触达、正式通知由Agent兜底。 - 用户收益:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。
-
AI 不只会聊天,还能进入企业微信协作层
- 问题本质:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。
- 插件做法:把企业微信原生协作能力按两条能力平面接入 OpenClaw。
- 用户收益:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。
-
小团队能低门槛上手,大团队也能正式上线
- 问题本质:小团队怕折腾,大团队怕失控。
- 插件做法:
Bot WS适合快速启用,Agent适合正式治理,两者可以并存。 - 用户收益:您不用在“今天先跑起来”和“将来能不能正规化”之间做破坏性迁移。
从用户视角看,差别不在于协议名词,而在于你要解决的是什么问题。
| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |
|---|---|---|---|
| 先跑起来的速度 | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |
| 实时聊天体验 | ✅ 最强,天然适合低延迟和流式回复 | ✅ 默认把实时交互交给 Bot | |
| 异步结果回推 | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |
| 组织级广播与冷启动触达 | ✅ 更适合 | ✅ 正式通知和广播走 Agent | |
| 企业微信协作能力 | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |
| 适合谁 | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要“体验”和“能力”的团队 |
建议理解方式:
- 如果您最在意的是“先接起来、先用起来、先聊顺”,优先上
Bot WS- 如果您最在意的是“正式部署、组织级能力、自动化治理”,补齐
Agent- 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存
很多企业微信 AI 机器人,本质上只是把答案发回聊天框。
真正有价值的,是让 AI 进入您已经在工作的地方。
在本插件里,企业微信的文档、日程、会议、待办、通讯录等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。
根据企业微信最新开放说明,面向 5 人及以下的小微企业,Bot WS 模式现已开放以用户个人身份调用部分企业微信协作能力。
在本插件里,这条链路以 wecom_mcp 的方式挂载,只在 WeCom Bot WS 会话 中可用:
- 能力入口:
wecom_mcp - 典型能力品类:
doc、meeting、todo、contact - 触发条件:当前会话必须来自
Bot WS - 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景
它的价值在于:
- 门槛低:无需先走完整的自建应用接入流程
- 身份自然:更贴近当前聊天用户自己的协作上下文
- 启动快:对小团队尤其友好
它的边界也要明确:
- 依赖
Bot WS会话存在 - 主动推送仍然以已建立会话为前提
- 实际开放范围以企业微信后台可见权限为准
Agent 模式走的是自建应用 API 平面,更适合企业级稳定自动化与组织级治理。
在本插件里,当前内置的协作工具主要包括:
wecom_doc:文档、表格、权限、分享可用性诊断等wecom_calendar:日历、日程、参与人、回执、默认日历等
它更适合:
- 把协作能力放进正式企业应用权限体系
- 与定时任务、异步流程、正式投递联动
- 面向组织对象做更稳定的自动化操作
当前插件已经把这两条协作链路都注册进来:
wecom_mcp:仅在Bot WS会话中暴露wecom_doc:仅在Agent会话中暴露wecom_calendar:仅在Agent会话中暴露
也就是说,您拿到的不是“一个只能聊天的企微插件”,而是:
- 一条适合实时对话和个人协作的入口
- 一条适合正式应用和组织自动化的入口
请按所选平面分别授权:
- Bot WS 模式授权:前往企业微信管理后台 👉「工作台 - 智能机器人」,找到对应机器人,点击编辑,在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。
- Agent 模式授权:前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」,将您的自建应用加入“可调用接口的应用”。
一句话理解:
- Bot WS 更像“当前聊天用户的实时协作入口”
- Agent 更像“企业正式应用身份下的自动化执行入口”
两者同时配置后,您既能拿到顺滑的实时交互,也能拿到企业级可治理的协作能力。
项目保持高频迭代,全面对齐甚至超越企业真实业务诉求。 为保持精简,以下仅展示近期 4 次重大架构演进,完整历史版本(含全部
v2.2.x)请前往 changelog/ 目录 查阅。
- [重要修复] Bot WS 现在也真正走
dynamicAgents🧭 之前同样开启动态路由时,不同消息链路的行为并不完全一致:Webhook / Agent 能按用户、群聊隔离,Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑,会话隔离终于统一了。 - [配置统一] 媒体大小开始优先跟随 OpenClaw 标准
mediaMaxMb📦 之前 WeCom 插件更偏向读取自己的media.maxBytes,用户改了 OpenClaw 主配置却可能感觉“改了没生效”。现在插件优先支持channels.wecom.mediaMaxMb,并支持channels.wecom.accounts.<accountId>.mediaMaxMb做账号级覆盖;旧配置仍兼容,但只作为兜底。 - [体验修复] 常见本地目录文件现在更符合直觉地可发送 🖼 过去本地媒体白名单更偏向 OpenClaw 自己目录,导致像
Downloads、Desktop、Pictures里的图片明明存在,却常被拦下。现在插件默认额外放行这些常见用户目录,同时保留channels.wecom.media.localRoots继续追加共享盘、挂载盘和业务目录。
- [重大升级] 双平面能力融合(Bot WS + MCP 强化) 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时,将官方新开放的企业微信能力暴露给大模型。现在,大模型可凭用户身份读写待办、日程、查通讯录。
- [多账号硬隔离] 彻底重构 MCP 缓存池实现
accountId + category的二次硬维隔离,无论您的矩阵挂载了多少家企业的助手,上下文及鉴权缓存绝不会交叉重叠。 - [媒体通道重构] 补齐 Bot WS 本地的媒体上传链,同时设立了严格的
5秒熔断机制,若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。
- [解析增强] 混合消息媒体正确接管 🛠 重点修复在
Bot WS通道下,用户如果发了“一张截图 + 一段文字指示”,以前容易丢掉截图或者 AI 只能看到无法查看的腾讯云临时链接。新版底层引擎将自动扫过所有的媒体节点摘取 URL 与解密 AES Key,还大模型一双慧眼。
- [原生资产稳定写入] 📄 深度强化大模型创建企微相关原生存根文档/表格时的写入稳定性。执行
init_content有了更强的前置图片上传清洗能力;极大程度杜绝了混发段落/文本/图片触发的企微官方Validator异常。 - [复杂分发目标解包] 💬 补齐所有关于企业微信“群聊、部门、标签组”作为
To目标的精确指令解析算法,保障向全公司的组织架构层级呼气 AI 报告不再报出81013 target invalid。
(查看更早期关于“超时熔断代投、动态扩容矩阵”等功能的更新日志,请移步 changelog/ 目录)
推荐统一使用多账号矩阵模型。 即使您的企业只接入了一个账号,也强烈建议将其配入
channels.wecom.accounts.default节点下。
openclaw plugins install @yanhaidao/wecom
openclaw plugins enable wecom如果您不想手写繁杂的 JSON 配置文件,可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署:
- 确保已启用本插件。
- 在终端运行添加渠道指令:
openclaw channels add
- 选择下拉列表中第一顺位的:企业微信 (WeCom)
- 根据终端亮色指引,填入企微机器人对应的
Bot ID及Secret,机器人即可完成握手并进入可用状态。
如果您的目标不是“接进来能聊两句”,而是让团队在企业微信里长期稳定使用 AI,这套组合更接近生产环境的推荐形态:
Bot WS负责实时对话、低延迟流式回复和更轻的接入门槛Agent负责主动推送、媒体发送和长任务后的兜底交付dynamicAgents负责把不同用户、不同群聊的会话真正隔离开,避免多人共用一个入口时互相串上下文
请进入 OpenClaw 配置文件(openclaw.json)的 channels.wecom 内使用:
其中:
- 插件现在默认额外放行常见用户目录:
~/Desktop、~/Documents、~/Downloads、~/Movies、~/Pictures。 channels.wecom.mediaMaxMb是首选的媒体大小上限配置,channels.wecom.accounts.<id>.mediaMaxMb可以做账号级覆盖。channels.wecom.media.localRoots用于继续追加你自己的全局目录,例如共享盘、挂载盘或业务导出目录。- 旧的
channels.wecom.media.maxBytes仍然兼容,但仅作为向后兼容兜底;新配置建议统一改成mediaMaxMb。 - 这些目录会和 OpenClaw 默认允许的媒体目录一起生效,不会覆盖默认白名单。
- 也就是说,像
~/Downloads/01.png这类本机文件现在默认就可以直接发到企微,不需要再单独配置。
注意: 历史配置里的
agent.corpSecret引擎依然能够向后兼容拾起,但后续的新项目推荐采用标准的agentSecret作为对齐键。
dynamicAgents 的核心价值,不是“自动创建很多 Agent”,而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。
如果不开它,所有消息更容易汇入同一个主 Agent;一旦开始多人共用,最先出问题的通常不是模型能力,而是上下文、长期记忆和处理边界混在一起。
更简单地看,可以直接按下面这张表决定要不要开:
| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |
|---|---|---|---|
| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络,长期上下文可能互相污染 | enabled=true + dmCreateAgent=true |
每个人都有自己的稳定上下文 |
| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent,群与群之间边界不清晰 | enabled=true + groupEnabled=true |
每个群都有独立会话空间 |
| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent,排障更分散 | adminUsers=["管理员userid"] |
管理账号继续直连主 Agent |
| 只是做 PoC 或单人试用 | 一上来就启用隔离,理解成本偏高 | enabled=false |
先把连通性和基础回复跑通 |
系统当前的真实行为如下:
- 开启后,会按
账号 + 会话类型 + 对端 ID生成确定性的 Agent ID,例如wecom-default-dm-zhangsan或wecom-default-group-wr123456 - 同一个用户或同一个群,下次再发消息时会继续命中同一个动态 Agent,而不是临时随机分配
- 首次命中时,插件会自动把这个动态 Agent 追加到
agents.list,不需要您手工维护一长串列表 - 这套逻辑同时作用于
Bot WS和Agent Callback两条主消息链路,不是只有某一种模式才生效 adminUsers中的账号会始终绕过动态路由,直接走主 Agent,适合放管理员、运营或排障账号- 默认值是
enabled=false、dmCreateAgent=true、groupEnabled=true、adminUsers=[],也就是不开总开关时不会生效,但一旦开启,单聊和群聊会默认一起进入隔离模式
需要注意的是,dynamicAgents 解决的是“路由隔离”和“会话隔离”,不是权限系统本身。
也就是说,它能显著减少上下文串线,但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent,仍然要结合 dm.policy、bindings 和企业微信授权配置一起看。
localRoots 只决定一件事:这个本地路径允不允许被当作可发送媒体读取。
| 现象 | 实际含义 |
|---|---|
| 文件存在,但发送失败 | 不代表系统允许读取它 |
日志出现 Local media path is not under an allowed directory |
路径不在白名单里 |
远程 https://... 媒体可以发 |
远程 URL 不走 localRoots |
默认已经额外放行这些目录:
| 默认允许目录 | 用途 |
|---|---|
~/Desktop |
桌面文件、临时截图 |
~/Documents |
文档导出目录 |
~/Downloads |
下载图片、下载文件 |
~/Movies |
视频文件 |
~/Pictures |
图片、相册导出 |
另外也保留 OpenClaw 自己的 tmp / state / workspace 相关目录。
如果文件不在默认目录里,再补 localRoots:
{
"channels": {
"wecom": {
"media": {
"localRoots": [
"/srv/company-share",
"/data/reports",
"/mnt/nas/public"
]
}
}
}
}配置规则:
| 规则 | 说明 |
|---|---|
localRoots 是追加 |
不会覆盖默认目录 |
| 建议写绝对路径 | 团队环境更稳定、更清楚 |
| 只加业务需要的目录 | 不要为了省事把范围放太大 |
| 不建议放整个大盘或整个用户目录 | 会把本地文件读取边界放得过宽 |
排障判断:
| 问题类型 | 看什么 |
|---|---|
| 本地路径是否允许读取 | localRoots |
| 媒体能处理多大 | channels.wecom.mediaMaxMb |
| 企业微信最终能不能收 | 企业微信自身媒体限制 |
| 远程媒体能不能发 | URL 可访问性,不看 localRoots |
一句话:localRoots 管“能不能读这个本地路径”,mediaMaxMb 管“最多读多大”。
如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件,需要将系统的路径下发到企业微信管理后台。
由于系统默认采纳多账号分流路径派生,请切记不要随意丢弃末尾的 {accountId},如下所示:
| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |
|---|---|---|---|
| Bot Webhook | https://x.com |
/plugins/wecom/bot/default |
/plugins/wecom/bot/ops |
| Agent Callback | https://x.com |
/plugins/wecom/agent/default |
/plugins/wecom/agent/ops |
警告:极度不推荐将老旧单一根路径(如 /plugins/wecom/bot)在未指定账户空间下裸奔使用,一旦您的业务扩张到第二个账号,将会引发难以追溯的回调抢占雪崩。
当前版本请使用以下三条命令组合排障。注意:openclaw channels status 不支持 --deep,插件级探测参数是 --probe;--deep 属于顶层 openclaw status。
openclaw channels status --probe适合回答这些问题:
- 企业微信账号是否已被网关识别并加载
- 账号当前是否
enabled/configured - 运行时是否
running/connected/authenticated - 最近一次错误、最近进出站时间是否异常
如果网关可达,这条命令会返回企业微信账号的运行时快照。
如果网关不可达,它会自动退化为“只看配置”的摘要输出。
openclaw status --deep这条命令是 OpenClaw 全局诊断入口,适合确认:
- Gateway 本身是否健康
- 当前机器上的整体通道探测是否正常
- 最近心跳、会话、服务状态是否异常
当您怀疑问题不只在企业微信插件,而是 Gateway、网络、配置路径或其他通道共同影响时,优先跑这条。
openclaw channels logs --channel wecom --lines 200当发生疑难连接断开、消息不回、媒体文件下发神秘消失时,直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下,助你顺藤摸瓜:
[wecom-runtime]:统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。[wecom-ws]:Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。[wecom-agent-delivery]:Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。
建议按下面顺序执行:
openclaw channels status --probe
openclaw status --deep
openclaw channels logs --channel wecom --lines 200您可以按输出这样判断:
configured=false:先检查bot.ws.botId、bot.ws.secret、agent.corpId、agent.agentSecret、agent.agentId等配置是否完整。running=false:说明账号没有真正启动,优先看[wecom-runtime]。connected=false或authenticated=false:优先看[wecom-ws],一般是 WebSocket 握手、密钥或连接稳定性问题。- 能收不能发,或群里发文件/卡片失败:优先看
[wecom-agent-delivery]。 lastError持续刷新:通常不是一次性误报,建议结合最近 200 行日志一起看。
感谢所有为本项目提交代码、测试、文档与反馈的协作者。
如果头像墙没有立刻刷新,通常是 GitHub 统计或第三方缓存延迟,稍后再看即可。
如果您在搭建这套极度庞大的多端复合体系时遇到迷思,或者对底层代理流量重定向有着深度企业定制化需求,请毫无顾虑地与我连接:
- 微信直接交流群(扫描底部二维码进群探讨技术):
- 维护者:YanHaidao
本项目遵循 ISC License,您可以将其用于极其广阔的项目天地中。但开源不是拿来主义: 在此明确强调,包括所谓的“Bot+Agent 保活接力超时融合机制”、“千人千面多账户切面”、“自动寻的路由下沉” 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。 愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。

{ "channels": { "wecom": { "enabled": true, "defaultAccount": "default", "accounts": { "default": { "enabled": true, "name": "企微销售二部支持中枢", "bot": { "primaryTransport": "ws", // 指定 Bot 主通讯协议:ws 或 webhook "streamPlaceholderContent": "正在深思熟虑,请稍候...", // 避免流式回复开始前长时间无反馈 "welcomeText": "你好,我是已连网的专属大脑。", "dm": { "policy": "pairing", "allowFrom": [] }, "ws": { // Bot WS 建连所需凭证 "botId": "YOUR_BOT_ID", "secret": "YOUR_BOT_SECRET" } }, "agent": { // 主动推送、媒体发送与兜底交付链路 "corpId": "YOUR_CORP_ID", "agentSecret": "YOUR_AGENT_SECRET", "agentId": 1000001, "token": "AGENT_TOKEN", "encodingAESKey": "AGENT_AES_KEY", "welcomeText": "若长连接断开,我将使用此通道传递残存报告。", "dm": { "policy": "open", "allowFrom": [] } } } }, "mediaMaxMb": 50, // 优先使用 OpenClaw 标准媒体上限配置 "media": { "tempDir": "/tmp/openclaw-wecom-media", "localRoots": [ "/srv/company-share", "/data/reports" ] }, "network": { // 内网或受限网络环境可通过代理出网 "egressProxyUrl": "http://127.0.0.1:3128" }, "dynamicAgents": { // 为单聊/群聊创建独立路由,减少多人串上下文 "enabled": true, "dmCreateAgent": true, "groupEnabled": true, "adminUsers": ["zhangsan001"] // 管理员绕过动态路由,直连主 Agent } } } }